sse-broadcast

Server-Sent Events through a Publish/Subscribe API for Node.js. This package is intended to simplify the use of SSE by providing a convenient way to organize ongoing streams into classes (or channels). You can bind an open response stream to one or more channels - specified by a string identifier - and in other parts of the codebase you can address messages (or events) by that channel. Let's take a look at the following example!

Usage

With Express:

const app = require('express')(),
      sse = require('sse-broadcast')()
 
app.get('/events', function (req, res) {
    sse.subscribe('channel', res)
})
 
app.post('/event/:type', function (req, res) {
    sse.publish('channel', req.params.type, 'whoo! something happened!')
    res.send()
})
 
app.listen(3333)

If you're interested about the usage with Koa or a vanilla Node.js server, see the examples folder.

Send event directly to a specified client (instead of a channel):

app.get('/events', function (req, res) {
    var time = Date.now()
    
    setInterval(function () {
        sse.sendEvent(res, 'elapsed-since-connected', Date.now() - time)      
    }, 1000)
})

For more convenience, there are helpers to extend http.ServerResponse.prototype and to easily create middleware for Connect/Express:

const app = require('express')(),
      sse = require('sse-broadcast')
 
sse.proto(sse())
 
app.get('/events/:type', function (req, res) {
        res.subscribe(req.params.type)
    })
// or
app.get('/events/:type', sse.middleware({ param: 'type' }))

Compression

This package supports response compression. If you want to compress outgoing event streams then you have to provide the request object for subscriptions.

const app = require('express')(),
      sse = require('sse-broadcast')({ compression: true }) // !!!
 
app
    .get('/events', function (req, res) {
        sse.subscribe('channel', req, res) // !!!
    })
    .post('/event', function (req, res) {
        sse.publish('channel', 'event', 'data')
        res.end()
    })
    .listen(3333)

The compression option can be set to true or an object containing settings for the compression module.

Using multiple nodes

SSE is a long-polling solution, consequently if you want to broadcast events to every client subscribed to a given channel then you’ll need some way of passing messages between processes or computers.

You can implement your own mechanism to do this or simply use sse-broadcast-redis to distribute events on top of Redis:

const os      = require('os'),
      cluster = require('cluster')
 
if (cluster.isMaster)
    for (var i = os.cpus().length; i--;)
        cluster.fork()
else {
    const app = require('express')(),
          sse = require('sse-broadcast')()
 
    require('sse-broadcast-redis')(sse, { host: 'localhost', port: 6379 })
 
    app.get('/events', function (req, res) {
        sse.subscribe('channel', res)
    })
 
    app.post('/event', function (req, res) {
        sse.publish('channel', 'event', 'data')
        res.send()
    })
 
    app.listen(3333)
}

Note: options are passed to redis directly.

API

The overall API documentation is available here.

Compatibility

sse-broadcast is compatible with Node 0.8 and above but in versions lower than 1 you'll need to use a process.nextTick() polyfill.

Installation

With npm:

npm install sse-broadcast

License

MIT