|
| 1 | +# Socket.IO Redis Streams adapter |
| 2 | + |
| 3 | +The `@socket.io/redis-streams-adapter` package allows broadcasting packets between multiple Socket.IO servers. |
| 4 | + |
| 5 | +Supported features: |
| 6 | + |
| 7 | +- [broadcasting](https://socket.io/docs/v4/broadcasting-events/) |
| 8 | +- [utility methods](https://socket.io/docs/v4/server-instance/#Utility-methods) |
| 9 | + - [`socketsJoin`](https://socket.io/docs/v4/server-instance/#socketsJoin) |
| 10 | + - [`socketsLeave`](https://socket.io/docs/v4/server-instance/#socketsLeave) |
| 11 | + - [`disconnectSockets`](https://socket.io/docs/v4/server-instance/#disconnectSockets) |
| 12 | + - [`fetchSockets`](https://socket.io/docs/v4/server-instance/#fetchSockets) |
| 13 | + - [`serverSideEmit`](https://socket.io/docs/v4/server-instance/#serverSideEmit) |
| 14 | +- [connection state recovery](https://socket.io/docs/v4/connection-state-recovery) |
| 15 | + |
| 16 | +Related packages: |
| 17 | + |
| 18 | +- Redis adapter: https://github.com/socketio/socket.io-redis-adapter/ |
| 19 | +- Redis emitter: https://github.com/socketio/socket.io-redis-emitter/ |
| 20 | +- MongoDB adapter: https://github.com/socketio/socket.io-mongo-adapter/ |
| 21 | +- MongoDB emitter: https://github.com/socketio/socket.io-mongo-emitter/ |
| 22 | +- Postgres adapter: https://github.com/socketio/socket.io-postgres-adapter/ |
| 23 | +- Postgres emitter: https://github.com/socketio/socket.io-postgres-emitter/ |
| 24 | + |
| 25 | +**Table of contents** |
| 26 | + |
| 27 | +- [Installation](#installation) |
| 28 | +- [Usage](#usage) |
| 29 | +- [Options](#options) |
| 30 | +- [How it works](#how-it-works) |
| 31 | +- [License](#license) |
| 32 | + |
| 33 | +## Installation |
| 34 | + |
| 35 | +``` |
| 36 | +npm install @socket.io/redis-streams-adapter redis |
| 37 | +``` |
| 38 | + |
| 39 | +## Usage |
| 40 | + |
| 41 | +```js |
| 42 | +import { createClient } from "redis"; |
| 43 | +import { Server } from "socket.io"; |
| 44 | +import { createAdapter } from "@socket.io/redis-streams-adapter"; |
| 45 | + |
| 46 | +const redisClient = createClient({ host: "localhost", port: 6379 }); |
| 47 | + |
| 48 | +await redisClient.connect(); |
| 49 | + |
| 50 | +const io = new Server({ |
| 51 | + adapter: createAdapter(redisClient) |
| 52 | +}); |
| 53 | + |
| 54 | +io.listen(3000); |
| 55 | +``` |
| 56 | + |
| 57 | +## Options |
| 58 | + |
| 59 | +| Name | Description | Default value | |
| 60 | +|---------------------|--------------------------------------------------------------------|---------------| |
| 61 | +| `streamName` | The name of the Redis stream. | `socket.io` | |
| 62 | +| `maxLen` | The maximum size of the stream. Almost exact trimming (~) is used. | `10_000` | |
| 63 | +| `readCount` | The number of elements to fetch per XREAD call. | `100` | |
| 64 | +| `heartbeatInterval` | The number of ms between two heartbeats. | `5_000` | |
| 65 | +| `heartbeatTimeout` | The number of ms without heartbeat before we consider a node down. | `10_000` | |
| 66 | + |
| 67 | +## How it works |
| 68 | + |
| 69 | +The adapter will use a [Redis stream](https://redis.io/docs/data-types/streams/) to forward events between the Socket.IO servers. |
| 70 | + |
| 71 | +Notes: |
| 72 | + |
| 73 | +- a single stream is used for all namespaces |
| 74 | +- the `maxLen` option allows to limit the size of the stream |
| 75 | +- 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 |
| 76 | +- if [connection state recovery](https://socket.io/docs/v4/connection-state-recovery) is enabled, the sessions will be stored in Redis as a classic key/value pair |
| 77 | + |
| 78 | +## License |
| 79 | + |
| 80 | +[MIT](LICENSE) |
0 commit comments