redis-subscribe-sse
v1.0.0
Published
Stream Redis subscribe events to client with SSE
Downloads
68
Maintainers
Readme
redis-subscribe-sse
(from) Redis subscribe (to) HTML5 Server-Sent Events
A Readable Stream that transforms messages received over a Redis PUBSUB channel to valid HTML5 Server-Sent Events.
Features:
- Can listen to one or more Redis PUBSUB channels
- Can associate Redis
channel
name to SSEevent
property, so publish ontest
channel means listening totest
event on client-side - Supports both
subscribe
andpsubscribe
modes
We also provide examples (backend and frontend) with:
- Koa - Example
- Express - Example
- Plain node http server - Example
- CORS (EventSource on a different host/port) - Example
Install
With npm:
npm install redis-subscribe-sse
Use cases
A typical use case is when you want to notify the end of an async task to a client, and you use Redis PUBSUB as a messaging service (which very fast and reliable). Example: a background worker has terminated its work, sends a message over Redis PUBSUB, and you want to forward that on the client side in order to show a notification.
How to use
To obtain a redis-subscribe-stream
instance, you have to do:
var subscribe = require('redis-subscribe-sse');
var stream = subscribe({ /* options */ });
stream available options
are:
channels
(Array, required): list of Redis channels to subscribe.streamOptions
: (Object, optional): options passed to underlying Readable stream. Default:{}
.host
(String, optional): Redis host. Default:127.0.0.1
port
(Number, optional): Redis port. Default:6379
password
(String, optional): Redis password (if you needAUTH
)clientOptions
: node_redis client optionsretry
(Number, optional): SSE retry property. Usually a client tries to reconnect after 3-4 seconds after losing SSE connection. If you want to change that interval, you can set this property (in ms). Default:5000
.channelsAsEvents
: (Boolean, optional): Associate Redis channel names to SSE event property. This way, on client side you can listen to names events instead of generic messages. Seeexamples/koa.js
for a detailed example. Default:false
.patternSubscribe
: (Boolean, optional): Use Redis PSUBSCRIBE instead of SUBSCRIBE. Default:false
.transform
: (Function, optional): It can be used for doing some message manipulation before pushing it to the stream. Signature is(message, *callback)
and it must returns a string (See below).
Message manipulation
Sometimes you need to some operation on the received messages before pushing them to the client. For example, you may need to do some encoding or decoding operations.
The transform
option is a function with this signature: (message, callback)
. The callback is optional and if passed it will allow to perform some async message manipulation. Otherwise, it will do a sync message manipulation.
Some examples:
Async message manipulation
In this mode, you have to pass a callback function as the second argument to transform
:
let s = subscribe({
channels: 'transform-test',
transform: (msg, callback) => {
setTimeout(() => {
callback(`${msg} world`)
}, 100)
}
})
Sync message manipulation
In this mode, simply return the manipulated message from transform
function:
let s = subscribe({
channels: 'transform-test',
transform: (msg) => {
return `${msg} world`
}
})
Tests
npm test
Debug
This module is built with debug. If you want to see debug messages:
$ DEBUG=redis-subscribe-sse node ./examples/express
Examples
Server side
See /examples
folder. You'll find examples using redis-subscribe-sse with:
- Koa - Example
- Express - Example
- Plain node http server - Example
- CORS (EventSource on a different host/port) - Example
$ node ./examples/express
$ node ./examples/koa
Client side
On client side, you can listen to SSE events using EventSource API (or a polyfill):
// NOTE: If you want full cross-browser support,
// you may have to use a polyfill
var source = new EventSource('/stream');
source.onopen = function() {
console.log('Connected');
});
// if you set `channelsAsEvents: true`:
source.addEventListener('test-express', function(e) {
console.log(e.type) // => Redis channel name
console.log(e.data) // => message
// Here you can show a notification or else
}, false);
// otherwise:
source.onmessage = function(e) {
console.log(e.data); // => message
// Here you can show a notification or else
});
The MIT License (MIT)
Copyright (c) 2016 Michele Pangrazzi <[email protected]>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.