sse-channel (Server-Sent Events channel)

SSE-implementation which can be used to any node.js http request/response stream.

Features

Easily attach to any node.js http request (express, hapi, node http)
History is maintained automatically, max size is configurable
Optionally pre-populate history when creating the channel
Automatically sends missed events to clients when reconnecting
Attempts to keep clients alive by sending "pings" automatically
Easily send messages to all clients or to specific clients
Configurable reconnection timeout
Auto-encode packets as JSON (configurable)
Supports CORS
Supports a number of different polyfills
Works with the compression middleware
If polyfilled on the client side, works down to IE8 and Android 2.x
Maintains active connection count per channel

Installing

npm install --save sse-channel

Basic usage

var SseChannel = require('sse-channel');
var http = require('http');

// Set up an interval that broadcasts server date every second
var dateChannel = new SseChannel();
setInterval(function broadcastDate() {
    dateChannel.send((new Date()).toISOString());
}, 1000);

// Create a regular HTTP server (works with express, too)
http.createServer(function(req, res) {
    // Note that you can add any client to an SSE channel, regardless of path.
    // Only requirement is not having written data to the response stream yet
    if (req.url.indexOf('/channel/date') === 0) {
        dateChannel.addClient(req, res);
    } else {
        res.writeHead(404);
        res.end();
    }
}).listen(7788, '127.0.0.1', function() {
    console.log('Listening on http://127.0.0.1:7788/');
});

See examples for express/hapi/node server examples.

Options

The following are available as options to the SseChannel constructor.

historySize - The maximum number of messages to keep in history. Note: Only messages with an id property are saved to history. Default: 500
history - Array of messages to pre-populate the history with. Note: If the size of the array specified exceeds the specified historySize, the array will be sliced to contain only the last X elements. Default: []
retryTimeout - How many milliseconds clients should wait before attempting to reconnect, if disconnected. Default: undefined - browser default.
pingInterval - How often the server should send a "ping" to clients in order to keep the connection alive (milliseconds). Default: 20000 (20s)
jsonEncode - Whether the client should auto-encode messages as JSON before sending. Default: false.
cors - An object of options related to Cross-Origin Resource Sharing. Uses the access-control module - see that for options. Note: The Last-Event-ID-header needs to be allowed. By default, no origins are allowed.

Methods

All instances of SseChannel have the following methods:

channel.addClient(request, response, [callback])

Add a client to the channel. request is the http.IncomingMessage instance for the connection, while response is the http.ServerResponse instance to write data to.

If specified, the callback supplied will be called once the client has been added. The first argument to the callback can be an error if the request was cross-origin and did not validate against the provided CORS configuration.

channel.removeClient(response)

Removes a client (response) from a channel. Note that this does not actually close the connection - for that, use response.end(). Also worth mentioning is that most clients will see this as an unintentional disconnect and will thus attempt to reconnect. Developers are encouraged to implement some sort of disconnect event that can be sent prior to disconnecting clients.

channel.getConnectionCount()

Get the number of active connections currently connected to the channel.

channel.ping()

Manually broadcast a "ping" to all connected clients, to keep the connections alive. Note that this is handled automatically by specifying the pingInterval option when instantiating the channel.

channel.retry(duration)

Tell clients how many milliseconds (duration) they should wait before attempting to reconnect, if disconnected.

channel.send(msg, [clients])

Send a message to all (or a subset of) connected clients.

msg can either be a string or an object. Specifying just a string will send the message without any id or event name, and will not end up in the history for the channel. The alternative is to provide an object:

msg.data - Data to send to the client. Data will be JSON-encoded if jsonEncode is enabled for the channel, otherwise it is sent as-is.
msg.id - ID of the event. Used by clients when reconnecting to ensure all messages are received. You are required to specify this if you want the message to be added to the channel history and have clients request missed data on reconnects.
msg.event - Event name, used on the client side to trigger on specific events.
msg.retry - Retry timeout (same as retry())

channel.sendEventsSinceId(response, sinceId)

Send events since a given ID from the channel history to the specified client. Usually handled automatically on reconnect, but could be useful for more customized implementations.

channel.close()

Close all connections on this channel. Note that this will usually only trigger all clients to reconnect, which is probably not what you want. You probably want to implement some sort of disconnect-contract between the server and client, before you call this.

Events

SseChannel implements the EventEmitter contract, and emits the following events:

connect - When a client has successfully connected and the initial headers have been queued for writing. Listeners are provided with the following arguments: channel, request, response
disconnect - When a client closes the connection for any reason. Listeners are provided with the following arguments: channel, response
message - When a message has been queued for sending. Listeners are provided with the following arguments: channel, msg, clients. In this case, clients is an array of either the clients provided or the full array of clients.

Client usage

In browsers, use EventSource as you normally would. For browsers that don't natively support EventSource, I recommend amvtek's polyfill. Basic client usage:

var es = new EventSource('http://localhost:1337/channels/soccer-goals');
es.addEventListener('goal', function(e) {
    alert('GOAL! ' + e.data);
});

// On the server:
soccerGoalChannel.send({
    event: 'goal',
    data: 'Manchester Utd - Swansea (2-1: Wayne Rooney)'
})

Note that the above is the usage when using named events. The default (and most basic) way is:

var es = new EventSource('http://localhost:1337/channels/ticker');
es.onmessage = function(e) {
    alert(e.data);
};

// On the server:
tickerChannel.send({ data: 'Some message here' });

Also note that when using jsonEncode option of SSE-Channel, you'll have to decode the message on the client:

var es = new EventSource('http://localhost:1337/channels/sysinfo');
es.onmessage = function(e) {
    var data = JSON.parse(e.data);
    console.log('CPU usage: ' + e.cpuUsage);
};

// On the server:
var sysInfoChannel = new SseChannel({ jsonEncode: true });
sysInfoChannel.send({
    data: { cpuUsage: 13.37 }
});

Advanced example

var SseChannel = require('sse-channel');
var http = require('http');
var os = require('os');

// Set up a new channel. Most of these options have sane defaults,
// feel free to look at lib/sse-channel.js for all available options
var sysInfoChannel = new SseChannel({
    retryTimeout: 250,
    historySize: 300,
    pingInterval: 15000,
    jsonEncode: true,
    cors: {
        origins: ['*'] // Defaults to []
    }
});

// Set up an HTTP server
http.createServer(function(req, res) {
    // The '/channel' prefix is not necessary - you can add any client
    // to an SSE-channel, if you want to.
    if (req.url.indexOf('/channel/sysinfo') === 0) {
        // Serve the client using sysinfo SSE-channel
        sysInfoChannel.addClient(req, res);
    } else {
        res.writeHead(404);
        res.end();
    }
}).listen(7788, '127.0.0.1', function() {
    console.log('Listening on http://127.0.0.1:7788/');
});

// Set up an interval that broadcasts system info every 250ms
var sysInfoCounter = 0;
setInterval(function broadcastSysInfo() {
    sysInfoChannel.send({
        id: sysInfoCounter++,
        data: {
            freemem: os.freemem(),
            loadavg: os.loadavg()
        }
    });
}, 250);

License

MIT-licensed, see LICENSE

willyboy/sse-channel