README
socket.io-redis
How to use
var io = require('socket.io')(3000);
var redis = require('socket.io-redis');
io.adapter(redis({ host: 'localhost', port: 6379 }));
By running socket.io with the socket.io-redis
adapter you can run
multiple socket.io instances in different processes or servers that can
all broadcast and emit events to and from each other.
If you need to emit events to socket.io instances from a non-socket.io process, you should use socket.io-emitter.
API
adapter(uri[, opts])
uri
is a string like localhost:6379
where your redis server
is located. For a list of options see below.
adapter(opts)
The following options are allowed:
key
: the name of the key to pub/sub events on as prefix (socket.io
)host
: host to connect to redis on (localhost
)port
: port to connect to redis on (6379
)subEvent
: optional, the redis client event name to subscribe to (message
)pubClient
: optional, the redis client to publish events onsubClient
: optional, the redis client to subscribe to events on
If you decide to supply pubClient
and subClient
, make sure you use
node_redis as a client or one
with an equivalent API.
If you supply clients, make sure you initialized them with
the return_buffers
option set to true
.
You can supply ioredis as a client
by providing messageBuffer
as the subEvent option.
RedisAdapter
The redis adapter instances expose the following properties
that a regular Adapter
does not
uid
prefix
pubClient
subClient
Client error handling
Access the pubClient
and subClient
properties of the
Redis Adapter instance to subscribe to its error
event:
var redis = require('socket.io-redis');
var adapter = redis('localhost:6379');
adapter.pubClient.on('error', function(){});
adapter.subClient.on('error', function(){});
Custom client (eg: with authentication)
If you need to create a redisAdapter to a redis instance that has a password, use pub/sub options instead of passing a connection string.
var redis = require('redis').createClient;
var adapter = require('socket.io-redis');
var pub = redis(port, host, { auth_pass: "pwd" });
var sub = redis(port, host, { return_buffers: true, auth_pass: "pwd" });
io.adapter(adapter({ pubClient: pub, subClient: sub }));
Make sure the return_buffers
option is set to true
for the sub client.
Protocol
The socket.io-redis
adapter broadcasts and receives messages on particularly named Redis channels. For global broadcasts the channel name is:
prefix + '#' + namespace + '#'
In broadcasting to a single room the channel name is:
prefix + '#' + namespace + '#' + room + '#'
prefix
: The base channel name. Default value issocket.io
. Changed by settingopts.key
inadapter(opts)
constructornamespace
: See https://github.com/socketio/socket.io#namespace.room
: Used if targeting a specific room.
A number of other libraries adopt this protocol including:
License
MIT