0
# Socket.IO Redis Adapter
1

2
The Socket.IO Redis adapter enables broadcasting packets between multiple Socket.IO servers through Redis pub/sub functionality. It provides comprehensive Redis integration with support for both regular Redis and Redis clusters, using either the 'redis' or 'ioredis' client libraries.
3

4
## Package Information
5

6
- **Package Name**: @socket.io/redis-adapter
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @socket.io/redis-adapter`
10

11
## Core Imports
12

13
```typescript
14
import { createAdapter, createShardedAdapter } from "@socket.io/redis-adapter";
15
```
16

17
Default import (equivalent to createAdapter):
18

19
```typescript
20
import createAdapter from "@socket.io/redis-adapter";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { createAdapter, createShardedAdapter } = require("@socket.io/redis-adapter");
27
// or
28
const createAdapter = require("@socket.io/redis-adapter");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import { createClient } from "redis";
35
import { Server } from "socket.io";
36
import { createAdapter } from "@socket.io/redis-adapter";
37

38
// Create Redis clients
39
const pubClient = createClient({ url: "redis://localhost:6379" });
40
const subClient = pubClient.duplicate();
41

42
await Promise.all([
43
  pubClient.connect(),
44
  subClient.connect()
45
]);
46

47
// Create Socket.IO server with Redis adapter
48
const io = new Server({
49
  adapter: createAdapter(pubClient, subClient)
50
});
51

52
io.listen(3000);
53
```
54

55
## Architecture
56

57
The Redis adapter is built around several key components:
58

59
- **Regular Adapter**: `RedisAdapter` class for standard Redis pub/sub operations
60
- **Sharded Adapter**: `ShardedRedisAdapter` class utilizing Redis 7.0+ sharded pub/sub features
61
- **Multi-Client Support**: Compatible with both `redis` and `ioredis` client libraries
62
- **Cluster Support**: Handles both standalone Redis and Redis cluster configurations
63
- **Inter-Server Communication**: Manages request/response patterns between Socket.IO servers
64
- **Message Parsing**: Configurable message encoding/decoding with binary data support
65

66
## Capabilities
67

68
### Regular Redis Adapter
69

70
Standard Redis adapter implementation using traditional pub/sub channels. Supports broadcasting, socket management, and inter-server communication.
71

72
```typescript { .api }
73
function createAdapter(
74
  pubClient: any,
75
  subClient: any,
76
  opts?: Partial<RedisAdapterOptions>
77
): (nsp: any) => RedisAdapter;
78

79
interface RedisAdapterOptions {
80
  key: string;
81
  requestsTimeout: number;
82
  publishOnSpecificResponseChannel: boolean;
83
  parser: Parser;
84
}
85
```
86

87
[Regular Redis Adapter](./regular-adapter.md)
88

89
### Sharded Redis Adapter
90

91
Advanced adapter implementation using Redis 7.0+ sharded pub/sub features for improved scalability.
92

93
```typescript { .api }
94
function createShardedAdapter(
95
  pubClient: any,
96
  subClient: any,
97
  opts?: ShardedRedisAdapterOptions
98
): (nsp: any) => ShardedRedisAdapter;
99

100
interface ShardedRedisAdapterOptions {
101
  channelPrefix?: string;
102
  subscriptionMode?: "static" | "dynamic" | "dynamic-private";
103
}
104
```
105

106
[Sharded Redis Adapter](./sharded-adapter.md)
107

108
### Utility Functions
109

110
Cross-client compatibility utilities for Redis operations and binary data handling.
111

112
```typescript { .api }
113
function hasBinary(obj: any, toJSON?: boolean): boolean;
114
function SSUBSCRIBE(
115
  redisClient: any,
116
  channel: string,
117
  handler: (rawMessage: Buffer, channel: Buffer) => void
118
): void;
119
function SUNSUBSCRIBE(redisClient: any, channel: string | string[]): void;
120
function SPUBLISH(
121
  redisClient: any,
122
  channel: string,
123
  payload: string | Uint8Array
124
): Promise<any>;
125
function PUBSUB(redisClient: any, arg: string, channel: string): Promise<number>;
126
function parseNumSubResponse(res: any[]): number;
127
function sumValues(values: number[]): number;
128
```
129

130
[Utility Functions](./utilities.md)
131

132
## Types
133

134
```typescript { .api }
135
interface Parser {
136
  decode(msg: any): any;
137
  encode(msg: any): any;
138
}
139
```