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
//! 参数提取器(Extractor)机制组件。
//! Parameter extractor mechanism component.
//!
//! 提供类似 `axum` 或 `socketioxide` 的参数提取机制,允许用户在事件处理函数中
//! Provides a parameter extraction mechanism similar to `axum` or `socketioxide`, allowing users to declare
//! 声明需要的参数类型(如 `Socket<S>`, `Data<T>`, `State<S>` 等),框架会自动从
//! required parameter types (such as `Socket<S>`, `Data<T>`, `State<S>`, etc.) in event handler functions.
//! 底层的 `(socket, IncomingEvent)` 上下文中提取出对应的数据并注入。
//! The framework will automatically extract the corresponding data from the underlying `(socket, IncomingEvent)` context and inject it.
use DeserializeOwned;
use Value;
use Arc as StdArc;
use ClientSocketRef;
use IncomingEvent;
// =====================================================
// Extractor Trait
// =====================================================
/// 核心 `Extractor` Trait。
/// Core `Extractor` Trait.
///
/// 用于将事件处理函数的参数从 `(socket, IncomingEvent)` 中提取出来。
/// Used to extract the parameters of the event handler function from `(socket, IncomingEvent)`.
/// 任何实现了此 trait 的类型都可以作为 `on` 等事件注册方法的参数。
/// Any type that implements this trait can be used as a parameter for event registration methods like `on`.
// =====================================================
// Socket<S>
// =====================================================
/// 提取当前触发事件的 `ClientSocketRef`。
/// Extracts the `ClientSocketRef` of the currently triggered event.
///
/// 通过此提取器,处理器中可以获得触发该事件的 Socket 引用,从而进行回复消息、加入房间等操作。
/// Through this extractor, the handler can obtain a reference to the Socket that triggered the event, allowing operations like replying to messages and joining rooms.
;
// =====================================================
// Data<T> —— 自动 JSON 反序列化
// =====================================================
/// 将事件载荷自动反序列化为类型 `T`。
/// Automatically deserializes the event payload into type `T`.
///
/// 对于 Socket.IO 协议解析后的事件:`event.data` 是 `[arg1, arg2, ...]` 的 JSON 数组形式。
/// For events parsed from the Socket.IO protocol: `event.data` is in the form of a JSON array `[arg1, arg2, ...]`.
///
/// 解析规则:
/// Parsing rules:
/// 1. 若 `T` 本身能反序列化整个数组(例如 `Vec<Value>`、`(A, B)`),直接按数组反序列化。
/// 1. If `T` itself can deserialize the entire array (e.g., `Vec<Value>`, `(A, B)`), deserialize it directly as an array.
/// 2. 若失败,尝试用单参数形式,即将 `data[0]` 反序列化为 `T`。
/// 2. If it fails, try a single-parameter format, i.e., deserialize `data[0]` into `T`.
/// 3. 若均失败,将打印一行警告并使用 `T::default()`。
/// 3. If both fail, print a warning and use `T::default()`.
;
// =====================================================
// State<S>
// =====================================================
/// 提取全局状态 `S` 的引用。
/// Extracts a reference to the global state `S`.
///
/// 通过 `ClientApp::new(state)` 传入的全局状态可以通过此提取器在任意处理器中获得 `Arc<S>`。
/// The global state passed in via `ClientApp::new(state)` can be obtained as `Arc<S>` in any handler through this extractor.
;
// =====================================================
// Ack —— 对服务端主动发来的带 ack_id 的事件做回复
// =====================================================
/// 获取对带 `ack_id` 事件的响应能力(Ack 发送器)。
/// Obtains the ability to respond to events with an `ack_id` (Ack sender).
///
/// 通过调用 `.send(Value)` 能够向服务端回发 ACK(即回复客户端已处理完成该请求的数据)。
/// Calling `.send(Value)` can send an ACK back to the server (i.e., reply with data that the client has finished processing the request).
/// 若服务端没有带 `ack_id` 发起请求,则调用 `send()` 什么都不会发生。
/// If the server initiated the request without an `ack_id`, calling `send()` will do nothing.
// =====================================================
// Raw —— 原始 IncomingEvent(方便进阶使用)
// =====================================================
/// 提取原始的 `IncomingEvent` 数据对象。
/// Extracts the raw `IncomingEvent` data object.
///
/// 当 `Data<T>` 等提取器无法满足需求时,可以直接提取原始事件,
/// When extractors like `Data<T>` cannot meet the requirements, the raw event can be extracted directly,
/// 包含解析出的 `data`, `namespace` 和 `ack_id`。
/// containing the parsed `data`, `namespace`, and `ack_id`.
;