🌜
🌞
socket.io-redis

socket.io-redis

v6.1.1

[![Build Status](https://github.com/socketio/socket.io-redis/workflows/CI/badge.svg?branch=master)](https://github.com/socketio/socket.io-redis/actions) [![NPM version](https://badge.fury.io/js/socket.io-redis.svg)](http://badge.fury.io/js/socket.io-redis

npm install socket.io-redis

README

socket.io-redis

Build Status NPM version

Table of contents

How to use

CommonJS

const io = require('socket.io')(3000);
const redisAdapter = require('socket.io-redis');
io.adapter(redisAdapter({ host: 'localhost', port: 6379 }));

ES6 modules

import { Server } from 'socket.io';
import redisAdapter from 'socket.io-redis';

const io = new Server(3000);
io.adapter(redisAdapter({ host: 'localhost', port: 6379 }));

TypeScript

// npm i -D @types/redis
import { Server } from 'socket.io';
import { createAdapter } from 'socket.io-redis';
import { RedisClient } from 'redis';

const io = new Server(8080);
const pubClient = new RedisClient({ host: 'localhost', port: 6379 });
const subClient = pubClient.duplicate();

io.adapter(createAdapter({ pubClient, subClient }));

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.

So any of the following commands:

io.emit('hello', 'to all clients');
io.to('room42').emit('hello', "to all clients in 'room42' room");

io.on('connection', (socket) => {
  socket.broadcast.emit('hello', 'to all clients except sender');
  socket.to('room42').emit('hello', "to all clients in 'room42' room except sender");
});

will properly be broadcast to the clients through the Redis Pub/Sub mechanism.

If you need to emit events to socket.io instances from a non-socket.io process, you should use socket.io-emitter.

Compatibility table

Redis Adapter version Socket.IO server version
4.x 1.x
5.x 2.x
6.0.x 3.x
6.1.x and above 4.x

How does it work under the hood?

This adapter extends the in-memory adapter that is included by default with the Socket.IO server.

The in-memory adapter stores the relationships between Sockets and Rooms in two Maps.

When you run socket.join("room21"), here's what happens:

console.log(adapter.rooms); // Map { "room21" => Set { "mdpk4kxF5CmhwfCdAHD8" } }
console.log(adapter.sids); // Map { "mdpk4kxF5CmhwfCdAHD8" => Set { "mdpk4kxF5CmhwfCdAHD8", room21" } }
// "mdpk4kxF5CmhwfCdAHD8" being the ID of the given socket

Those two Maps are then used when broadcasting:

  • a broadcast to all sockets (io.emit()) loops through the sids Map, and send the packet to all sockets
  • a broadcast to a given room (io.to("room21").emit()) loops through the Set in the rooms Map, and sends the packet to all matching sockets

The Redis adapter extends the broadcast function of the in-memory adapter: the packet is also published to a Redis channel (see below for the format of the channel name).

Each Socket.IO server receives this packet and broadcasts it to its own list of connected sockets.

To check what's happening on your Redis instance:

$ redis-cli
127.0.0.1:6379> PSUBSCRIBE *
Reading messages... (press Ctrl-C to quit)
1) "psubscribe"
2) "*"
3) (integer) 1

1) "pmessage"
2) "*"
3) "socket.io#/#" (a broadcast to all sockets or to a list of rooms)
4) <the packet content>

1) "pmessage"
2) "*"
3) "socket.io#/#room21#" (a broadcast to a single room)
4) <the packet content>

Note: no data is stored in Redis itself

There are 3 Redis subscriptions per namespace:

  • main channel: <prefix>#<namespace>#* (glob)
  • request channel: <prefix>-request#<namespace>#
  • response channel: <prefix>-response#<namespace>#

The request and response channels are used in the additional methods exposed by the Redis adapter, like RedisAdapter#allRooms().

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)
  • pubClient: optional, the redis client to publish events on
  • subClient: optional, the redis client to subscribe to events on
  • requestsTimeout: optional, after this timeout the adapter will stop waiting from responses to request (5000ms)

If you decide to supply pubClient and subClient, make sure you use node_redis as a client or one with an equivalent API.

RedisAdapter

The redis adapter instances expose the following properties that a regular Adapter does not

  • uid
  • prefix
  • pubClient
  • subClient
  • requestsTimeout

RedisAdapter#sockets(rooms: Set)

Returns the list of socket IDs connected to rooms across all nodes. See Namespace#allSockets()

const sockets = await io.of('/').adapter.sockets();
console.log(sockets); // a Set containing all the connected socket ids

const sockets = await io.of('/').adapter.sockets(new Set(['room1', 'room2']));
console.log(sockets); // a Set containing the socket ids in 'room1' or in 'room2'

// this method is also exposed by the Server instance
const sockets = await io.in('room3').allSockets();
console.log(sockets); // a Set containing the socket ids in 'room3'

RedisAdapter#allRooms()

Returns the list of all rooms.

const rooms = await io.of('/').adapter.allRooms();
console.log(rooms); // a Set containing all rooms (across every node)

RedisAdapter#remoteJoin(id:String, room:String)

Makes the socket with the given id join the room.

try {
  await io.of('/').adapter.remoteJoin('<my-id>', 'room1');
} catch (e) {
  // the socket was not found
}

RedisAdapter#remoteLeave(id:String, room:String)

Makes the socket with the given id leave the room.

try {
  await io.of('/').adapter.remoteLeave('<my-id>', 'room1');
} catch (e) {
  // the socket was not found
}

RedisAdapter#remoteDisconnect(id:String, close:Boolean)

Makes the socket with the given id to get disconnected. If close is set to true, it also closes the underlying socket.

try {
  await io.of('/').adapter.remoteDisconnect('<my-id>', true);
} catch (e) {
  // the socket was not found
}

Client error handling

Access the pubClient and subClient properties of the Redis Adapter instance to subscribe to its error event:

const adapter = require('socket.io-redis')('localhost:6379');
adapter.pubClient.on('error', function(){});
adapter.subClient.on('error', function(){});

The errors emitted from pubClient and subClient will also be forwarded to the adapter instance:

const io = require('socket.io')(3000);
const redisAdapter = require('socket.io-redis');
io.adapter(redisAdapter({ host: 'localhost', port: 6379 }));
io.of('/').adapter.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.

const redis = require('redis');
const redisAdapter = require('socket.io-redis');
const pubClient = redis.createClient(port, host, { auth_pass: "pwd" });
const subClient = pubClient.duplicate();
io.adapter(redisAdapter({ pubClient, subClient }));

With ioredis client

Cluster example

const io = require('socket.io')(3000);
const redisAdapter = require('socket.io-redis');
const Redis = require('ioredis');

const startupNodes = [
  {
    port: 6380,
    host: '127.0.0.1'
  },
  {
    port: 6381,
    host: '127.0.0.1'
  }
];

io.adapter(redisAdapter({
  pubClient: new Redis.Cluster(startupNodes),
  subClient: new Redis.Cluster(startupNodes)
}));

Sentinel Example

const io = require('socket.io')(3000);
const redisAdapter = require('socket.io-redis');
const Redis = require('ioredis');

const options = {
  sentinels: [
    { host: 'somehost1', port: 26379 },
    { host: 'somehost2', port: 26379 }
  ],
  name: 'master01'
};

io.adapter(redisAdapter({
  pubClient: new Redis(options),
  subClient: new Redis(options)
}));

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 + '#'

A number of other libraries adopt this protocol including:

License

MIT

Release Notes

6.1.0
By Damien Arrachequesne • Published on March 12, 2021

Features

  • implement utility methods from Socket.IO v4 (468c3c8)

Performance Improvements

  • remove one round-trip for the requester (6c8d770)
6.0.1
By Damien Arrachequesne • Published on November 14, 2020

Bug Fixes

  • typings: properly expose the createAdapter method (0d2d69c)
  • fix broadcasting (#361) (3334d99)
6.0.0
By Damien Arrachequesne • Published on November 12, 2020

:warning: This release is only compatible with Socket.IO v3. For Socket.IO v2, please use previous versions.

See also: https://github.com/socketio/socket.io-redis#compatibility-table

Features

  • add support for Socket.IO v3 (d9bcb19)

BREAKING CHANGES:

  • all the requests (for inter-node communication) now return a Promise instead of accepting a callback

Before:

io.of('/').adapter.allRooms((err, rooms) => {
  console.log(rooms); // an array containing all rooms (across every node)
});

After:

const rooms = await io.of('/').adapter.allRooms();
console.log(rooms); // a Set containing all rooms (across every node)
  • RedisAdapter.clients() is renamed to RedisAdapter.sockets()

See https://github.com/socketio/socket.io-adapter/commit/130f28a43c5aca924aa2c1a318422d21ba03cdac

  • RedisAdapter.clientRooms() is removed

It has been replaced by the fetchSockets() method in Socket.IO v4:

const sockets = await io.in(theSocketId).fetchSockets();
if (sockets.length) {
  console.log(sockets[0].rooms);
}
  • RedisAdapter.customHook() and RedisAdapter.customRequest() are removed

Those methods will be replaced by a more intuitive API in a future iteration.

  • support for Node.js 8 is dropped

See https://github.com/nodejs/Release

5.4.0
By Damien Arrachequesne • Published on September 2, 2020

Features

  • update node-redis version to 3.x (fa4d474)
5.3.0
By Damien Arrachequesne • Published on June 4, 2020

Features

  • add support for Redis Cluster (7a19075)
5.2.0
By Damien Arrachequesne • Published on August 24, 2017

Features

  • increase default requestsTimeout to 5000 ms (#243)
5.1.0
By Damien Arrachequesne • Published on June 4, 2017

Features

  • add support for ArrayBuffer (#226)

Bug fixes

  • use the requestid from response when deleting requests (#225)
5.0.1
By Damien Arrachequesne • Published on May 13, 2017

Bug fixes

  • fix broken protocol in 5.0.0 (#221)

Milestone: 5.0.1 Diff: 5.0.0...5.0.1

5.0.0
By Damien Arrachequesne • Published on May 10, 2017

Performance improvements

  • use notepack instead of msgpack-lite (#218)
  • use pattern matching at the namespace level (#217)

:warning: Breaking changes :warning:

This is the first version compatible with socket.io v2. Please use previous versions (4.x) for socket.io v1.x. If not, you may encounter Cannot read property 'encode' of undefined errors.

Milestone: 5.0.0 Diff: 4.0.1...5.0.0

4.0.1
By Damien Arrachequesne • Published on May 10, 2017

Bug fixes

  • fix duplicate identifier declaration (#213)

Milestone: 4.0.1 Diff: 4.0.0...4.0.1

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
No

Popularity

GitHub Stargazers
2,588
Community Interest
3,196
Number of Forks
477

Maintenance

Commits
11/2110/22010
Last Commit
Open Issues
20
Closed Issues
283
Open Pull Requests
4
Closed Pull Requests
60

Versions

Versions Released
11/2110/2201
Latest Version Released
May 18, 2021
Current Tags
latest6.1.1

Contributors

darrachequesne
darrachequesne
Commits: 75
rauchg
rauchg
Commits: 47
nkzawa
nkzawa
Commits: 5
hgcummings
hgcummings
Commits: 3
ryoqun
ryoqun
Commits: 3
kevin-roark
kevin-roark
Commits: 2
overflowz
overflowz
Commits: 2
omrilitov
omrilitov
Commits: 2
barisusakli
barisusakli
Commits: 2
komachi
komachi
Commits: 1
CarsonF
CarsonF
Commits: 1
tomasvts
tomasvts
Commits: 1
veyond
veyond
Commits: 1
reqshark
reqshark
Commits: 1
TomasVidhall
TomasVidhall
Commits: 1