README
socket-redis
socket-redis is a WebSocket pub/sub server and client, exposing an API over Redis (allowing you to use WebSocket functionality in your application using a Redis client).
About
socket-redis starts a WebSocket server (SockJS) where clients can connect to, and subscribe to multiple channels.
The server will let you consume client-related events like message
, subscribe
and unsubscribe
on a Redis pub/sub channel socket-redis-up
.
Additionally it will subscribe to another pub/sub channel socket-redis-down
where you can send messages to all clients in a channel.
When specifying multiple --socket-ports
the script will spawn a child process for each port. This is provided as a simple way to make use of all your CPU cores.
Server
Installation & Configuration
Package is available through npm registry:
npm install socket-redis [-g]
socket-redis.js --redis-host=my-redis
Or as a Docker image:
docker run cargomedia/socket-redis ./bin/socket-redis.js --redis-host=my-redis
See also the provided docker-compose.yml
for reference.
Available options:
--redis-host
Specify host of redis server. Defaults tolocalhost
.--redis-port
Specify port. Default 6379--redis-pass
Specify password if needed--socket-ports
Comma separated public ports which SockJS workers will listen on. Defaults to8090
.--log-dir
Directory where log is stored. Script will try to create directory if needed. Defaults tonull
which means it will output to stdout.--sockjs-client-url
Specify custom url for sockjs-client library.--status-port
Specify port for http status requests. It should not be publicly accesible. Defaults to8085
--status-secret
Specify secret token to allow/deny http status requests (optional).--ssl-key
Specify ssl private key file. Combine withssl-cert
option.--ssl-cert
Specify ssl public certificate file. Combine withssl-key
option. Append CA-chain within this file.--ssl-pfx
Specify ssl pfx file (key + cert). Overridesssl-key
andssl-cert
options.--ssl-passphrase
Specify file containing the ssl passphrase.
Redis API
socket-redis-up
:
Messages published to redis pub/sub channel {type: "subscribe", data: {channel: <channel>, clientKey: <clientKey>, data: <subscribe-data>}}
{type: "unsubscribe", data: {channel: <channel>, clientKey: <clientKey>}}
{type: "message", data: {clientKey: <clientKey>, data: <data>}}
socket-redis-down
:
Messages consumed on redis pub/sub channel {type: "publish", data: {channel: <channel>, event: <event>, data: <data>}}
For example you could publish messages using Redis CLI:
redis-cli 'publish' 'socket-redis-down' '{"type":"publish", "data": {"channel":"<channel>", "event":"<event>", "data":"<data>"}}'
HTTP status API
Server also answers http status requests (on port 8085 by default).
A JSON representation of all current subscribers is returned on /
:
$ curl 'http://localhost:8085/'
{<channel>: {
"subscribers": {
<clientKey>: {
"clientKey": <clientKey>,
"subscribeStamp": <subscribe-stamp>,
"data": {}
}
}
}
A Prometheus scraping endpoint is responding on /metrics
:
$ curl 'http://localhost:8085/metrics'
# HELP socketredis_channels_total Number of channels
# TYPE socketredis_channels_total gauge
socketredis_channels_total 30
# HELP socketredis_subscribers_total Number of subscribers
# TYPE socketredis_subscribers_total gauge
socketredis_subscribers_total 90
Client
Building
Client is written as a node module. If you want to access it as a global variable in browser then you need to browserify client/index.js
. It will be exposed under SocketRedis
. Also it requires a global variable SockJS
that contains sockjs client.
browserify --standalone SocketRedis ./client/index.js -o ./client/socket-redis.js
Installation
Include the SockJS and socket-redis client libraries in your html file:
<script src="http://cdn.sockjs.org/sockjs-0.3.min.js"></script>
<script src="./client/socket-redis.js"></script>
Example
To receive messages from the server create a new SocketRedis
instance and subscribe to some channels:
var socketRedis = new SocketRedis('http://example.com:8090');
socketRedis.onopen = function() {
socketRedis.subscribe('channel-name', null, {foo: 'bar'}, function(event, data) {
console.log('New event `' + event + '` on channel `channel-name`:', data);
});
socketRedis.unsubscribe('channel-name');
};
socketRedis.open();
To publish messages to a channel from the client:
socketRedis.publish('channel-name', 'event-name', {foo: 'bar'});
(The event name will be prefixed with client-
and thus become client-event-name
.)
To send messages to the server:
socketRedis.send({foo: 'bar'});
Development
Install dependencies:
npm install
Build the docker image:
docker-compose build
Running Tests
docker-compose run --rm --volume $(pwd):/opt/socket-redis socket-redis ./script/test.sh
Running the Server
docker-compose run --volume $(pwd):/opt/socket-redis --service-ports socket-redis
Releasing new Versions
- Update package.json with a new version
- Push a new git tag with the updated package.json
- The Travis build should deploy to NPM automatically
If it doesn't work you could release it manually with:
npm publish https://github.com/cargomedia/socket-redis/archive/<GitTagWithUpdatedPackageJson>.tar.gz