socket_io_client 0.4.0

A Socket.IO client implemented in Rust. It implements Engine.IO v4 and Socket.IO v5, and includes paired examples with socketioxide.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
# Engine.IO 协议


> 本文翻译自 [Socket.IO 官方文档 - The Engine.IO protocol]https://socket.io/zh-CN/docs/v4/engine-io-protocol/,介绍 Engine.IO 协议第 4 版。

## 目录


- [简介]#简介
- [传输方式(Transports)]#传输方式transports
  - [HTTP 长轮询]#http-长轮询
    - [请求路径]#请求路径
    - [查询参数]#查询参数
    - [请求头]#请求头
    - [发送与接收数据]#发送与接收数据
  - [WebSocket]#websocket
- [协议(Protocol)]#协议protocol
  - [握手(Handshake)]#握手handshake
  - [心跳(Heartbeat)]#心跳heartbeat
  - [升级(Upgrade)]#升级upgrade
  - [消息(Message)]#消息message
- [数据包编码]#数据包编码
  - [HTTP 长轮询]#http-长轮询-1
  - [WebSocket]#websocket-1
- [版本历史]#版本历史
  - [从 v2 到 v3]#从-v2-到-v3
  - [从 v3 到 v4]#从-v3-到-v4
- [测试套件]#测试套件

---

## 简介


> Engine.IO 协议支持客户端与服务器之间的**全双工**、**低开销**通信。

该协议基于 WebSocket 协议,并在无法建立 WebSocket 连接时,回退到 HTTP 长轮询作为备用机制。

官方参考实现使用 TypeScript 编写:

- 服务端:<https://github.com/socketio/engine.io>
- 客户端:<https://github.com/socketio/engine.io-client>

Socket.IO 协议在 Engine.IO 的基础上构建,为通信通道补充了额外的特性。

---

## 传输方式(Transports)


Engine.IO 客户端与服务器之间的连接可以通过以下两种方式建立:

- HTTP 长轮询
- WebSocket

### HTTP 长轮询


HTTP 长轮询传输由一系列连续的 HTTP 请求组成:

- 长连接 GET 请求:用于接收服务器推送的数据;
- 短连接 POST 请求:用于客户端向服务端发送数据。

#### 请求路径


默认的 HTTP 请求路径为 `/engine.io/`。基于该协议构建的库可以修改此路径,例如 Socket.IO 使用 `/socket.io/`。

#### 查询参数


| 名称 | 取值 | 说明 |
|------|------|------|
| `EIO` | `4` | 必填,协议版本 |
| `transport` | `polling` | 必填,传输方式名称 |
| `sid` | `<sid>` | 会话建立之后必填,会话标识符 |

若缺少必填查询参数,服务器必须返回 HTTP 400 错误。

#### 请求头


传输二进制数据时,发送方必须添加请求头 `Content-Type: application/octet-stream`。若未显式设置 content-type,接收方应将数据视为纯文本处理。

#### 发送与接收数据


##### 发送数据


客户端通过 HTTP POST 请求将编码后的数据包放在请求体中发送:

```
CLIENT                                                 SERVER

  │                                                      │
  │   POST /engine.io/?EIO=4&transport=polling&sid=...   │
  │ ───────────────────────────────────────────────────► │
  │ ◄──────────────────────────────────────────────────┘ │
  │                        HTTP 200                      │
  │                                                      │
```

若会话 ID 未知,服务器必须返回 HTTP 400。请求成功时返回 HTTP 200,响应体为 `ok`。

> 为保证数据包顺序,客户端同一时刻**不得**有一个以上处于活动状态的 POST 请求。

##### 接收数据


客户端通过 HTTP GET 请求接收数据包:

```
CLIENT                                                SERVER

  │   GET /engine.io/?EIO=4&transport=polling&sid=...   │
  │ ──────────────────────────────────────────────────► │
  │                                                   . │
  │                                                   . │
  │                                                   . │
  │                                                   . │
  │ ◄─────────────────────────────────────────────────┘ │
  │                       HTTP 200                      │
```

若会话 ID 未知,服务器必须返回 HTTP 400。若当前无缓冲的数据包,服务器可延迟响应;一旦有数据可发送,应将数据包编码后放入响应体返回。

> 为保证数据包顺序,客户端同一时刻**不得**有一个以上处于活动状态的 GET 请求。

### WebSocket


WebSocket 传输在服务端与客户端之间提供双向、低延迟的通信能力。

使用的查询参数:

| 名称 | 取值 | 说明 |
|------|------|------|
| `EIO` | `4` | 必填,协议版本 |
| `transport` | `websocket` | 必填,传输方式名称 |
| `sid` | `<sid>` | 可选,取决于是否由 HTTP 长轮询升级而来 |

若缺少必填参数,服务器必须关闭该连接。

> 每个数据包(无论是读还是写)都在各自独立的 WebSocket 帧中发送。

> 每个会话客户端**不得**建立一个以上的 WebSocket 连接。

---

## 协议(Protocol)


一个 Engine.IO 数据包由下列部分构成:

- 数据包类型(packet type)
- 可选的数据包负载(packet payload)

可用的数据包类型:

| 类型 | ID | 用途 |
|------|----|----|
| open | 0 | 握手阶段使用 |
| close | 1 | 表示传输通道可以关闭 |
| ping | 2 | 心跳机制中使用 |
| pong | 3 | 心跳机制中使用 |
| message | 4 | 向对端发送负载数据 |
| upgrade | 5 | 传输升级过程中使用 |
| noop | 6 | 传输升级过程中使用 |

### 握手(Handshake)


客户端通过 HTTP GET 请求向服务器发起连接建立。

先使用 HTTP 长轮询(默认方式):

```
CLIENT                                                    SERVER

  │                                                          │
  │        GET /engine.io/?EIO=4&transport=polling           │
  │ ───────────────────────────────────────────────────────► │
  │ ◄──────────────────────────────────────────────────────┘ │
  │                        HTTP 200                          │
  │                                                          │
```

仅使用 WebSocket 的会话:

```
CLIENT                                                    SERVER

  │                                                          │
  │        GET /engine.io/?EIO=4&transport=websocket         │
  │ ───────────────────────────────────────────────────────► │
  │ ◄──────────────────────────────────────────────────────┘ │
  │                        HTTP 101                          │
  │                                                          │
```

当服务器接受连接时,会返回一个 `open` 数据包,其 JSON 负载包含以下字段:

| 键名 | 类型 | 说明 |
|------|------|------|
| `sid` | `string` | 会话 ID |
| `upgrades` | `string[]` | 可用的传输升级选项 |
| `pingInterval` | `number` | 心跳 ping 的间隔(毫秒) |
| `pingTimeout` | `number` | 心跳 ping 的超时时间(毫秒) |
| `maxPayload` | `number` | 客户端聚合数据包时每段的最大字节数 |

示例:

```json
{
  "sid": "lv_VI97HAXpY6yYWAAAC",
  "upgrades": ["websocket"],
  "pingInterval": 25000,
  "pingTimeout": 20000,
  "maxPayload": 1000000
}
```

> 客户端在之后所有的请求中,**必须**在查询参数中携带 `sid` 值。

### 心跳(Heartbeat)


握手完成之后,通过心跳机制来验证连接是否仍然存活:

```
CLIENT                                                 SERVER

  │                   *** Handshake ***                  │
  │                                                      │
  │  ◄─────────────────────────────────────────────────  │
  │                           2                          │  (ping packet)
  │  ─────────────────────────────────────────────────►  │
  │                           3                          │  (pong packet)
```

> 按照固定的时间间隔(握手时返回的 `pingInterval` 值),服务器发送一个 ping 包,客户端必须在若干秒内(`pingTimeout` 值)回复一个 pong 包。

若服务器未收到 pong 响应,应认为连接已关闭;若客户端在 `pingInterval + pingTimeout` 时间内未收到 ping 数据包,也应认为连接已关闭。

### 升级(Upgrade)


> 默认情况下,客户端**应当**先建立 HTTP 长轮询连接,之后在条件允许时升级到更优的传输方式。

要升级至 WebSocket,客户端必须:

- 暂停 HTTP 长轮询传输,以避免数据包丢失;
- 使用相同的会话 ID 建立 WebSocket 连接;
- 发送一个 ping 数据包,负载为字符串 `probe`。

服务器必须:

- 向挂起的 GET 请求发送一个 noop 数据包,以便干净地关闭 HTTP 长轮询;
- 回复一个 pong 数据包,负载为字符串 `probe`。

随后客户端必须发送 upgrade 数据包完成升级:

```
CLIENT                                                 SERVER

  │                                                      │
  │   GET /engine.io/?EIO=4&transport=websocket&sid=...  │
  │ ───────────────────────────────────────────────────► │
  │  ◄─────────────────────────────────────────────────┘ │
  │            HTTP 101 (WebSocket handshake)            │
  │                                                      │
  │            -----  WebSocket frames -----             │
  │  ─────────────────────────────────────────────────►  │
  │                         2probe                       │ (ping 数据包)
  │  ◄─────────────────────────────────────────────────  │
  │                         3probe                       │ (pong 数据包)
  │  ─────────────────────────────────────────────────►  │
  │                         5                            │ (upgrade 数据包)
  │                                                      │
```

### 消息(Message)


握手完成之后,客户端与服务器可通过 message 数据包相互交换数据。

---

## 数据包编码


Engine.IO 数据包的序列化方式取决于两点:负载类型(纯文本或二进制)、传输方式。字符编码使用 UTF-8;二进制负载采用 base64 编码。

### HTTP 长轮询


为提升吞吐量,可以将多个数据包拼接在一起发送。

格式:

```
<数据包类型>[<数据>]<分隔符><数据包类型>[<数据>]<分隔符><数据包类型>[<数据>][...]
```

示例:

```
4hello\x1e2\x1e4world

其中:

4      => message 数据包类型
hello  => message 负载
\x1e   => 分隔符
2      => ping 数据包类型
\x1e   => 分隔符
4      => message 数据包类型
world  => message 负载
```

数据包之间使用记录分隔符 `\x1e` 隔开。

> 二进制负载**必须**先以 base64 编码,并在前面添加前缀字符 `b`:

示例:

```
4hello\x1ebAQIDBA==

其中:

4         => message 数据包类型
hello     => message 负载
\x1e      => 分隔符
b         => 二进制前缀
AQIDBA==  => 缓冲区 <01 02 03 04> 的 base64 编码
```

> 客户端**应当**依据握手阶段获得的 `maxPayload` 值,来决定一次拼接多少个数据包。

### WebSocket


> 每个 Engine.IO 数据包都在独立的 WebSocket 帧中发送。

格式:

```
<数据包类型>[<数据>]
```

示例:

```
4hello

其中:

4      => message 数据包类型
hello  => message 负载(UTF-8 编码)
```

二进制负载无需任何转换,直接发送。

---

## 版本历史


### 从 v2 到 v3


- 新增对二进制数据的支持。

版本 2 用于 Socket.IO v0.9 及更早版本。

版本 3 用于 Socket.IO v1 与 v2。

### 从 v3 到 v4


- 反转 ping/pong 机制

> 现在由服务器来发送 ping 数据包,因为浏览器中设置的定时器不够可靠。

- 对包含二进制数据的负载,始终使用 base64 编码

这样就不必关心客户端或传输层是否支持二进制数据,所有负载都能被一致处理。该规则仅适用于 HTTP 长轮询;WebSocket 的二进制数据仍无需做任何转换。

- 使用记录分隔符(`\x1e`)替代字符计数

> 使用字符计数会阻碍(或至少使之更困难)用其他语言实现该协议,因为这些语言未必使用 UTF-16 编码。

例如:`€` 原本被编码为 `2:4€`,但 `Buffer.byteLength('€') === 3`。

注意:此方案假定数据中不会出现记录分隔符字符。

版本 4(当前版本)被 Socket.IO v3 及之后的版本所采用。

---

## 测试套件


位于 `test-suite/` 目录下的测试套件可用于检查服务端实现的合规性。

使用方法:

- 在 Node.js 中运行:`npm ci && npm test`
- 在浏览器中运行:直接打开目录下的 `index.html` 文件

一份可通过全部测试的 JavaScript 服务端参考配置:

```javascript
import { listen } from "engine.io";

const server = listen(3000, {
  pingInterval: 300,
  pingTimeout: 200,
  maxPayload: 1e6,
  cors: {
    origin: "*"
  }
});

server.on("connection", socket => {
  socket.on("data", (...args) => {
    socket.send(...args);
  });
});
```