sseries-of-tubes
Takes Express/Connect routes and creates stream.Writable endpoints for Server Sent Events.
Introduction
SSEriesOfTubes attaches to an http.Server and efficiently manages each endpoint for Server Sent Events by creating a writeable StringTube
Stream that is piped to every http.Response. StringTube
is a utf8 String Stream subclassed from Through2.
Additionally, SSEriesOfTubes can wrap a standard Express/Connect route controller (a function
that takes arguments (req, res, next)
), poll that controller for data, and push that data to the SSE stream.
This way, any API can easily support REST/polling and Server Sent Events with the same route controller.
SSEriesOfTubes is an EventEmitter based on chrisdickinson/sse-stream, so it handles SSE headers, keep-alive messaging, and emits events around the connection and polling lifecycle.
Installation
npm install --save sseries-of-tubes
Usage
Example
# on server http = require "http"express = require "express"SSEriesOfTubes = require "sseries-of-tubes" server = app = expresssseriesOfTubes = server = resjson hello: "world" # Sends {"hello": "world"} every 3s to every client connected to /sse/hello appget "/sse/hello"sseriesOfTubesplumb sendHello3 ... # on client source = "/sse/hello"# log {"hello": "world"} as received every 3s = consolelog data
Interface
SSEriesOfTubes.StringTube
Pointer to class StringTube, a Through2 Readable/Writable stream.
SSEriesOfTubes::constructor(server, keepAliveInterval)
httpServer serverint keepAliveInterval
returns sseriesOfTubes instance
Creates a new SSEriesOfTubes instance that reacts to http.Server "listening" and "close" events.
sseriesOfTubes.plumb(fn, interval)
sseriesOfTubesplumb Function routeint interval
returns Function route
Creates a new StringTube source which polls a route to write to all clients for an endpoint.
sseriesOfTubes.plumb(fn, interval, event)
sseriesOfTubesplumb Function routeint intervalString event
returns Function route
Creates a new StringTube source which polls a route to write to all clients for an endpoint, and will send the event event
(in EventSource syntax) before sending data.
sseriesOfTubes.plumb()
sseriesOfTubesplumb
returns Function route
Creates a new StringTube source which writes to all clients for an endpoint.
sseriesOfTubes.source(url)
sseriesOfTubessource String url
returns StringTube source
Retrieves the StringTube source for an endpoint.
sseriesOfTubes.combine(router, paths...)
sseriesOfTubescombine expressRouter routerString paths...
returns Function route
Creates a new StringTube source by combining existing StringTube sources referenced by their path
. This way different combinations of streams can be provided without duplicating pollers. Requires a router
conforming to the express.Router interface for method handle
.
sseriesOfTubes.multiplex(router, param = "streams")
sseriesOfTubesmultiplex expressRouter routerString param
returns Function route
Creates new StringTube sources by dynamically combining existing StringTube sources, referenced by their path
in an comma-separated list provided by the client in the query or body as parameter param
. This method is similar to combine
, but works with paths that have route parameters. Requires a router
conforming to the express.Router interface for method handle
.
sseriesOfTubes.destroy()
sseriesOfTubesdestroy
Ends all SSE client connections and destroys all clients.
Events
connection
sseriesOfTubeson "connection"
On client connection, calls bound function with an instance of Client.
poll
sseriesOfTubeson "poll"
On route start poll, calls bound function with the url endpoint.
plumb
sseriesOfTubeson "plumb"
On route start plumb (creates StringTube source), calls bound function with the url endpoint.
stop
sseriesOfTubeson "stop"
On last client disconnect, calls bound function with the url endpoint.
License
MIT