Using the Pipe
As well as providing a REST interface to the Pusher service, we have now created the Pipe, a new API for interacting with our service from your Node applications. There is a quickstart guide here.
This is an alpha feature. For now, access is invitation only. Contact support@pusher.com for access.
Overview
WebSockets and event-based libraries make it easy for any developer to make realtime applications. Pusher makes it easy to scale such applications. Now, with the Pipe and the Node Pipe client, you can use the power of Pusher from Node. Even better, because the Node Pipe client keeps a long-running connection, you can send a lot of messages to Pusher and avoid the overhead of using the REST API to establish large numbers of HTTP connections.
Technical details
The Node Pipe client establishes a bi-directional WebSocket connection to Pusher. This connection has two purposes:
- Receiving information about browsers or other devices that are connecting to Pusher, and the events they are creating.
- Sending events to connected browsers or other devices.
The Node Pipe client
NOTE: in the following, we refer to a connection to Pusher - whether from a browser, or some other device - as a socket.
- Installation
- Establishing a connection to the Pipe
- Managing connection state
- Listening for events
- Sending messages
- to a socket
- to a channel
Installation
npm install pusher-pipe
Establishing a connection to the Pipe
Instantiate a Node Pipe client:
var Pipe = require('pusher-pipe');
var client = Pipe.createClient({key: 'cd1731aae21c98a6d2b1',
secret: '671229af735ec34004e7',
app_id: 3
});
Connect the Node Pipe client instance to the Pipe:
client.connect();
Managing connection state
You can bind pieces of code that will be run when the Node Pipe client connects, disconnects or causes an internal error:
client.on('connected', function() {});
client.on('disconnected', function() {});
client.on('error', function(err) {});
Listening for events
In order to be able to start receiving events you need to first indicate which event types you wish to receive by subscribing to them.
client.subscribe(eventTypes);
eventTypes should be an array with one or more of the following event type elements:
socket_existence- events related to web clients connection status. See Socket Connections.
socket_message- events triggered by connecting web clients. See Socket Events.
channel_existence- Coming soon... events triggered by a channel becoming occupied (having at least one subscription) or becoming vacant (the last subscriber unsubscribing from the channel).
Example
client.subscribe(['socket_message', 'socket_existence']);
Socket Connections
You must subscribe to socket_existence events in order to bind to Socket Connection events. See Listening for events.
You can bind some code that will run when a new socket connects:
client.sockets.on('open', function(socketId) {});
The socketId that is returned can be stored for future communication with this socket.
You can bind code that will run when a socket closes their connection to Pusher:
client.sockets.on('close', function(socketId) {});
Socket Events
You must subscribe to socket_message events in order to bind to Socket Events. See Listening for events.
At the socket level, your code can listen for these events in the following ways:
Listen for all events on all sockets.
Returns the socketId of the originator and the eventName.
client.sockets.on('event', function(eventName, socketId, data) {});
Listen for my_event on all sockets.
Returns the socketId of the originator.
client.sockets.on('event:my_event', function(socketId, data) {});
Listen for all events on a specific socket.
Returns the eventName.
client.socket(socketId).on('event', function(eventName, data) {});
Listen for my_event on a specific socket.
client.socket(socketId).on('event:my_event', function(data) {});
Listen for the close event for a specific socket:
client.socket(socketId).on('close', function() {});
Channel Events
You must subscribe to socket_message events in order to bind to Channel Events. See Listening for events.
Listen for all events on all channels.
Returns the socketId of the originator, the channelName and the eventName.
client.channels.on('event', function(eventName, channelName, socketId, data) {});
Listen for my_event on all channels.
Returns the socketId of the originator and the channelName of the channel it was triggered on.
client.channels.on('event:my_event', function(channelName, socketId, data) {});
Listen for all events on a channel specified by channelName.
Returns the socketId of the originator and the eventName.
client.channel('my_channel').on('event', function(eventName, socketId, data) {});
Listen for my_event on a channel specified by channelName.
Returns the socketId of the originator.
client.channel('my_channel').on('event:my_event', function(socketId, data) {});
Sending events from the Node server
Sockets can call trigger to send an event to your Node server.
Send an event to a particular socket:
client.socket(socketId).trigger('my_event', data)
Send an event to a channel:
client.channel('my_channel').trigger('my_event', data)
Changes to the pusher-js browser client library
Because the Node Pipe client uses the concept of sockets extensively, we have made some changes to our browser library.
Listen for events targetted at the socket:
pusher.back_channel.bind('my_event', function(data) {});
Send an event to your Node server:
pusher.back_channel.trigger('my_event', data);
To send an event on a channel, subscribe to the channel and then trigger on it.
pusher.subscribe('my_channel');
pusher.channel('my_channel').trigger('my_event', data);
Limitations of the alpha
This is the first version of this API and we plan to improve it. The initial version does not have support for:
- Querying the status of Pusher.
- Handling more than one connected Node process.
- Buffering events after a connection interruption.