🌜
🌞
@socket.io/redis-adapter

@socket.io/redis-adapter

v7.2.0

The Socket.IO Redis adapter, allowing to broadcast events between several Socket.IO servers

npm install @socket.io/redis-adapter

README

socket.io-redis

Build Status npm version

Table of contents

How to use

Installation:

$ npm install @socket.io/redis-adapter redis

CommonJS

const { Server } = require('socket.io');
const { createClient } = require('redis');
const { createAdapter } = require('@socket.io/redis-adapter');

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

Promise.all([pubClient.connect(), subClient.connect()]).then(() => {
  io.adapter(createAdapter(pubClient, subClient));
  io.listen(3000);
});

With [email protected], calling connect() on the Redis clients is not needed:

const { Server } = require('socket.io');
const { createClient } = require('redis');
const { createAdapter } = require('@socket.io/redis-adapter');

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

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

io.listen(3000);

ES6 modules

import { Server } from 'socket.io';
import { createClient } from 'redis';
import { createAdapter } from '@socket.io/redis-adapter';

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

Promise.all([pubClient.connect(), subClient.connect()]).then(() => {
  io.adapter(createAdapter(pubClient, subClient));
  io.listen(3000);
});

TypeScript

import { Server } from 'socket.io';
import { createClient } from 'redis';
import { createAdapter } from '@socket.io/redis-adapter';

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

Promise.all([pubClient.connect(), subClient.connect()]).then(() => {
  io.adapter(createAdapter(pubClient, subClient));
  io.listen(3000);
});

By running Socket.IO with the @socket.io/redis-adapter 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(pubClient, subClient[, opts])

The following options are allowed:

  • key: the name of the key to pub/sub events on as prefix (socket.io)
  • requestsTimeout: optional, after this timeout the adapter will stop waiting from responses to request (5000ms)

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(new Set());
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
}

With ioredis client

Cluster example

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

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

const pubClient = new Redis.Cluster(startupNodes);
const subClient = pubClient.duplicate();

io.adapter(redisAdapter(pubClient, subClient));

Sentinel Example

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

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

const pubClient = new Redis(options);
const subClient = pubClient.duplicate();

io.adapter(redisAdapter(pubClient, subClient));

Protocol

The @socket.io/redis-adapter 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:

Migrating from socket.io-redis

The package was renamed from socket.io-redis to @socket.io/redis-adapter in v7, in order to match the name of the Redis emitter (@socket.io/redis-emitter).

To migrate to the new package, you'll need to make sure to provide your own Redis clients, as the package will no longer create Redis clients on behalf of the user.

Before:

const redisAdapter = require("socket.io-redis");

io.adapter(redisAdapter({ host: "localhost", port: 6379 }));

After:

const { createClient } = require("redis");
const { createAdapter } = require("@socket.io/redis-adapter");

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

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

Please note that the communication protocol between the Socket.IO servers has not been updated, so you can have some servers with socket.io-redis and some others with @socket.io/redis-adapter at the same time.

License

MIT

Release Notes

7.2.0
By Damien Arrachequesne • Published on May 3, 2022

Bug Fixes

Features

  • broadcast and expect multiple acks (e4c40cc)

This feature was added in [email protected]:

io.timeout(1000).emit("some-event", (err, responses) => {
  // ...
});

Thanks to this change, it will now work with multiple Socket.IO servers.

Diff: https://github.com/socketio/socket.io-redis-adapter/compare/7.1.0...7.2.0

7.1.0
By Damien Arrachequesne • Published on November 29, 2021

Features

  • add support for redis v4 (aa681b3)
  • do not emit "error" events anymore (8e5c84f)

Error handling can now be done on the redis clients directly.

Before:

io.of("/").adapter.on("error", () => {
  // ...
});

After:

pubClient.on("error", () => {
  // something went wrong
});

subClient.on("error", () => {
  // something went wrong
});
  • send response to the requesting node only (f66de11)

A more performant way to do request-response is available behind an option, publishOnSpecificResponseChannel:

const io = require('socket.io')(3000);
const { createClient } = require('redis');
const redisAdapter = require('@socket.io/redis-adapter');

const pubClient = createClient({ host: 'localhost', port: 6379 });
const subClient = pubClient.duplicate();
io.adapter(redisAdapter(pubClient, subClient, {
  publishOnSpecificResponseChannel: true
}));

To upgrade an existing deployment, you will need to upgrade all nodes to the latest version with publishOnSpecificResponseChannel = false, and then toggle the option on each node.

Please check the commit for more information.

7.0.1
By Damien Arrachequesne • Published on November 15, 2021

Bug Fixes

  • allow numeric rooms (214b5d1)
  • ignore sessionStore in the fetchSockets method (c5dce43)
7.0.0
By Damien Arrachequesne • Published on May 11, 2021

:warning: IMPORTANT :warning:

The package was renamed to @socket.io/redis-adapter, in order to match the name of the Redis emitter (@socket.io/redis-emitter).

Features

  • implement the serverSideEmit functionality (3a0f29f)
  • remove direct redis dependency (c68a47c)
  • rename the package to @socket.io/redis-adapter (3cac178)

BREAKING CHANGES

  • the library will no longer create Redis clients on behalf of the user.

Before:

io.adapter(redisAdapter({ host: "localhost", port: 6379 }));

After:

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

io.adapter(redisAdapter(pubClient, subClient));

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
No

Popularity

GitHub Stargazers
2,588
Community Interest
3,152
Number of Forks
476

Maintenance

Commits
11/2110/22010
Last Commit
May 3, 2022
Open Issues
20
Closed Issues
283
Open Pull Requests
3
Closed Pull Requests
60

Versions

Versions Released
11/2110/2202
Latest Version Released
Current Tags
latest7.2.0

Contributors

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