search

rexxars / sse-channel

Server-Sent Events "channel" where all messages are broadcasted to all connected clients, history is maintained automatically and server attempts to keep clients alive by sending "keep-alive" packets automatically.
MIT License
111 stars 11 forks source link

readme

sse-channel (Server-Sent Events channel)

Version npmBuild StatusCoverage StatusCode Climate

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

Features

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.

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.

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:

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 and stop sending "keep alive"-pings. Note that this will usually only trigger all clients to reconnect, which is probably not what you want. You might 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:

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,
});

// 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