Skip to main content
Version: 4.x

Redis Streams adapter

How it works

The adapter will use a Redis stream to forward packets between the Socket.IO servers.

The main difference with the existing Redis adapter (which use the Redis Pub/Sub mechanism) is that this adapter will properly handle any temporary disconnection to the Redis server and resume the stream without losing any packets.

Notes:

  • a single stream is used for all namespaces
  • the maxLen option allows to limit the size of the stream
  • unlike the adapter based on Redis PUB/SUB mechanism, this adapter will properly handle any temporary disconnection to the Redis server and resume the stream
  • if connection state recovery is enabled, the sessions will be stored in Redis as a classic key/value pair

Source code: https://github.com/socketio/socket.io-redis-streams-adapter

Supported features

Featuresocket.io versionSupport
Socket management4.0.0✅ YES (since version 0.1.0)
Inter-server communication4.1.0✅ YES (since version 0.1.0)
Broadcast with acknowledgements4.5.0✅ YES (since version 0.1.0)
Connection state recovery4.6.0✅ YES (since version 0.1.0)

Installation

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

Usage

With the redis package

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

const redisClient = createClient({ url: "redis://localhost:6379" });

await redisClient.connect();

const io = new Server({
adapter: createAdapter(redisClient)
});

io.listen(3000);

With the redis package and a Redis cluster

import { createCluster } from "redis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = createCluster({
rootNodes: [
{
url: "redis://localhost:7000",
},
{
url: "redis://localhost:7001",
},
{
url: "redis://localhost:7002",
},
],
});

await redisClient.connect();

const io = new Server({
adapter: createAdapter(redisClient)
});

io.listen(3000);

With the ioredis package

import { Redis } from "ioredis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = new Redis();

const io = new Server({
adapter: createAdapter(redisClient)
});

io.listen(3000);

With the ioredis package and a Redis cluster

import { Cluster } from "ioredis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = new Cluster([
{
host: "localhost",
port: 7000,
},
{
host: "localhost",
port: 7001,
},
{
host: "localhost",
port: 7002,
},
]);

const io = new Server({
adapter: createAdapter(redisClient)
});

io.listen(3000);

Options

NameDescriptionDefault value
streamNameThe name of the Redis stream.socket.io
maxLenThe maximum size of the stream. Almost exact trimming (~) is used.10_000
readCountThe number of elements to fetch per XREAD call.100
sessionKeyPrefixThe prefix of the key used to store the Socket.IO session, when the connection state recovery feature is enabled.sio:session:
heartbeatIntervalThe number of ms between two heartbeats.5_000
heartbeatTimeoutThe number of ms without heartbeat before we consider a node down.10_000

Common questions

Do I still need to enable sticky sessions when using the Redis Streams adapter?

Yes. Failing to do so will result in HTTP 400 responses (you are reaching a server that is not aware of the Socket.IO session).

More information can be found here.

What happens when the Redis server is down?

Unlike the classic Redis adapter, this adapter will properly handle any temporary disconnection to the Redis server and resume the stream without losing any packets.

Latest releases

VersionRelease dateRelease notesDiff
0.2.1March 2024link0.2.0...0.2.1
0.2.0February 2024link0.1.0...0.2.0
0.1.0April 2023link

Complete changelog