surmux 0.2.0

极简 SurrealDB WebSocket 客户端 — 单连接 JSON-RPC 多路复用, 极简依赖
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
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
//! Router: WebSocket 连接管理与请求多路复用.
//!
//! 核心职责:
//! - 管理单个 WS 连接的完整生命周期
//! - 通过 id-based 多路复用实现并发请求
//! - 断线自动重连 + 指数退避
//!
//! 协议: 由 `SurrealConfig::protocol` 决定 (CBOR 或 JSON).
//! CBOR (RFC 8949) over Binary 帧: 高性能, `Value::Bytes` 零膨胀.
//! JSON over Text 帧: 兼容性优先, `Bytes` 字段 ~4x 膨胀.
//!
//! 整个连接锁定一种协议 (由 WS 子协议协商决定), router 不做跨格式分发.
//!
//! 架构:
//! ```text
//! SurrealClient ──(RouterCommand)──> Router
//!                                     ├── 发送: 编码 → WS Binary/Text 帧
//!                                     └── 接收: WS 帧 → peek id → pending oneshot 投递原始 bytes
//! ```
//!
//! decode 责任下沉到 query 层: router 只 peek id 定位等待者, 不解析响应内容.

use std::collections::HashMap;

use futures_util::{SinkExt, StreamExt};
use serde_json::Value;
use tokio::net::TcpStream;
use tokio::sync::mpsc::{UnboundedReceiver, UnboundedSender};
use tokio::sync::oneshot;
use tokio_tungstenite::MaybeTlsStream;
use tokio_tungstenite::WebSocketStream;
use tokio_tungstenite::tungstenite::Message;
use tokio_tungstenite::tungstenite::client::IntoClientRequest;
use tokio_tungstenite::tungstenite::http::HeaderValue;
use tokio_tungstenite::tungstenite::http::header::SEC_WEBSOCKET_PROTOCOL;

use crate::codec;
use crate::config::{SurrealConfig, WireProtocol};
use crate::error::{SurrealError, SurrealResult};
use crate::protocol::RpcResponse;

// ============================================================
// Router 命令类型
// ============================================================

/// Router 投递的原始响应字节 (decode 责任下沉到 query 层).
///
/// router 只 peek id 定位等待者, 投递完整 bytes 由 query 层按 `protocol` 选择 decode 路径.
/// `protocol` 在 router 接收帧时按当前 `SurrealConfig.protocol` 填充, 整个连接内恒定.
/// `id` 字段保留供 query 层做日志/诊断 (oneshot 接收侧可 log "收到 id=X 的响应").
#[allow(dead_code)]
pub(crate) struct RawRpcBytes {
    pub id: u64,
    pub protocol: WireProtocol,
    pub bytes: Vec<u8>,
}

/// 从 Client 发往 Router 的命令.
pub(crate) struct RouterCommand {
    /// RPC 方法名.
    pub method: String,
    /// JSON 参数 (数组格式) — codec 内部按 protocol 转换.
    pub params: Value,
    /// 响应通道 (投递 RawRpcBytes, 由 query 层按需 decode).
    pub response_tx: oneshot::Sender<Result<RawRpcBytes, SurrealError>>,
}

/// 创建命令通道.
pub(crate) fn router_channel() -> (
    UnboundedSender<RouterCommand>,
    UnboundedReceiver<RouterCommand>,
) {
    tokio::sync::mpsc::unbounded_channel()
}

// ============================================================
// 类型别名
// ============================================================

type WsStream = WebSocketStream<MaybeTlsStream<TcpStream>>;
type WsSink = futures_util::stream::SplitSink<WsStream, Message>;
type WsSource = futures_util::stream::SplitStream<WsStream>;

// ============================================================
// 公开入口
// ============================================================

/// 启动 Router 后台任务.
///
/// 在 tokio 任务中运行, 管理 WS 连接生命周期:
/// 连接 → 认证 → 多路复用 → 断开 → 重连.
pub(crate) fn spawn_router(
    request_rx: UnboundedReceiver<RouterCommand>,
    config: SurrealConfig,
) -> tokio::task::JoinHandle<()> {
    tokio::spawn(async move {
        run_router_loop(request_rx, config).await;
    })
}

// ============================================================
// Router 主循环
// ============================================================

/// 连接 → 服务 → 断开 → 重连.
async fn run_router_loop(mut request_rx: UnboundedReceiver<RouterCommand>, config: SurrealConfig) {
    let mut attempt: u32 = 0;

    loop {
        match serve_connection(&mut request_rx, &config).await {
            Ok(()) => {
                log::debug!("[surreal] Router 正常退出");
                break;
            }

            Err(e) => {
                attempt += 1;
                if attempt > config.max_reconnect_attempts {
                    log::error!("[surreal] Router 重连失败 (已尝试 {attempt} 次), 退出: {e}");
                    // 显式给每条 in-flight 请求回 ReconnectFailed, 而不是默默 drain 让
                    // oneshot Receiver 收到 cancellation (后者会让用户等满 query_timeout
                    // 才知道连不上). 后续新到的命令因 sender 未 drop 仍可入队, 故再补一个
                    // drain 清空, 避免堆积.
                    let reason = format!("重连失败 ({attempt} 次): {e}");
                    while let Ok(cmd) = request_rx.try_recv() {
                        let _ = cmd.response_tx.send(Err(SurrealError::ReconnectFailed(reason.clone())));
                    }
                    break;
                }

                let delay = backoff_delay(attempt, &config);
                log::warn!(
                    "[surreal] Router 断开 (attempt {attempt}/{max}): {e}, {delay:?} 后重连...",
                    max = config.max_reconnect_attempts,
                );
                tokio::time::sleep(delay).await;
            }
        }
    }
}

/// 单次连接生命周期: 握手 → 认证 → 多路复用 → 断开.
async fn serve_connection(
    request_rx: &mut UnboundedReceiver<RouterCommand>,
    config: &SurrealConfig,
) -> Result<(), SurrealError> {
    // 1. WebSocket 连接 (协商子协议)
    let ws_url = config.ws_url()?;
    log::debug!("[surreal] 连接 ({}): {ws_url}", config.protocol.subprotocol());

    let mut http_request = ws_url
        .into_client_request()
        .map_err(|e| SurrealError::ConnectionFailed(format!("无效的 WS URL: {e}")))?;

    // 协商子协议 (SurrealDB 服务端支持 cbor / json / flatbuffers).
    // 协商失败由 tungstenite 报错 (服务端不支持时 connect 会失败), 我们不"降级".
    http_request
        .headers_mut()
        .insert(
            SEC_WEBSOCKET_PROTOCOL,
            HeaderValue::from_static(config.protocol.subprotocol()),
        );

    let (ws_stream, _response) = tokio::time::timeout(
        config.connect_timeout,
        tokio_tungstenite::connect_async(http_request),
    )
    .await
    .map_err(|_| SurrealError::Timeout("WebSocket 连接超时".into()))?
    .map_err(|e| SurrealError::ConnectionFailed(format!("WebSocket 连接失败: {e}")))?;

    // 2. 分拆为 Sink + Stream
    let (mut ws_sink, mut ws_stream) = ws_stream.split();

    // 3. 认证 (signin + use ns/db)
    authenticate(&mut ws_sink, &mut ws_stream, config).await?;
    log::debug!(
        "[surreal] 认证成功 ({}), 进入多路复用模式",
        config.protocol.subprotocol()
    );

    // 4. 多路复用循环
    let mut pending: HashMap<u64, oneshot::Sender<Result<RawRpcBytes, SurrealError>>> =
        HashMap::new();
    let mut next_id: u64 = 0;

    loop {
        tokio::select! {
            // ===== 发送: Client → 编码 → WS 帧 =====
            cmd = request_rx.recv() => {
                match cmd {
                    Some(cmd) => {
                        let id = next_id;
                        next_id = next_id.wrapping_add(1);

                        // 按当前协议编码为对应类型的 WS Message (Binary/Text), 零中间 buffer.
                        let msg = encode_message(config.protocol, id, &cmd.method, &cmd.params)?;
                        let send_result = ws_sink.send(msg).await;
                        if let Err(e) = send_result {
                            let _ = cmd.response_tx.send(Err(SurrealError::ConnectionLost));
                            fail_all_pending(&mut pending);
                            return Err(SurrealError::ConnectionFailed(
                                format!("WS 写入失败: {e}")
                            ));
                        }

                        pending.insert(id, cmd.response_tx);
                    }
                    None => {
                        fail_all_pending(&mut pending);
                        return Ok(());
                    }
                }
            }

            // ===== 接收: WS 帧 → peek id → pending 投递原始 bytes =====
            msg = ws_stream.next() => {
                let frame_data = match decode_inbound_frame(msg, config.protocol) {
                    Ok(Some(data)) => data,
                    Ok(None) => continue, // ping/pong 跳过
                    Err(e) => {
                        fail_all_pending(&mut pending);
                        return Err(e);
                    }
                };

                // 仅 peek id (decode 责任下沉到 query 层)
                let id = peek_id(config.protocol, &frame_data)?;
                if let Some(tx) = pending.remove(&id) {
                    let _ = tx.send(Ok(RawRpcBytes {
                        id,
                        protocol: config.protocol,
                        bytes: frame_data,
                    }));
                } else {
                    log::debug!("[surreal] 收到未知 id 的响应: {id}");
                }
            }
        }
    }
}

/// 按协议编码请求为对应格式的 WS `Message` (CBOR → Binary, JSON → Text),
/// 直接交给 sink, 不留中间 buffer.
fn encode_message(
    protocol: WireProtocol,
    id: u64,
    method: &str,
    params: &Value,
) -> Result<Message, SurrealError> {
    match protocol {
        WireProtocol::Cbor => {
            let bytes = codec::encode_request_cbor(id, method, params)?;
            Ok(Message::Binary(bytes.into()))
        }
        WireProtocol::Json => {
            let text = codec::encode_request_json(id, method, params)?;
            Ok(Message::Text(text.into()))
        }
    }
}

/// 按协议 peek 响应中的 id 字段 (用于多路复用路由).
fn peek_id(protocol: WireProtocol, data: &[u8]) -> SurrealResult<u64> {
    match protocol {
        WireProtocol::Cbor => codec::peek_response_id_cbor(data),
        WireProtocol::Json => codec::peek_response_id_json(data),
    }
}

/// 解析一次 WS 接收, 严格按协议检查帧类型.
///
/// 返回值:
/// - `Ok(Some(bytes))`: 协议匹配的响应帧, bytes 是 CBOR 二进制或 JSON UTF-8.
/// - `Ok(None)`: Ping/Pong 帧, 调用方跳过本帧.
/// - `Err(_)`: 协议不匹配 / 连接关闭 / 读取错误, 调用方应断连.
fn decode_inbound_frame(
    msg: Option<Result<Message, tokio_tungstenite::tungstenite::Error>>,
    protocol: WireProtocol,
) -> Result<Option<Vec<u8>>, SurrealError> {
    let msg = match msg {
        Some(m) => m.map_err(|e| SurrealError::ConnectionFailed(format!("WS 读取错误: {e}")))?,
        None => return Err(SurrealError::ConnectionLost),
    };
    match msg {
        Message::Binary(data) if protocol == WireProtocol::Cbor => Ok(Some(data.to_vec())),
        Message::Binary(_) => {
            log::error!("[surreal] 协议 {:?} 期望 Text 帧, 但收到 Binary", protocol);
            Err(SurrealError::ConnectionFailed("协议不匹配: 收到 Binary 帧".into()))
        }
        Message::Text(text) if protocol == WireProtocol::Json => {
            Ok(Some(text.as_bytes().to_vec()))
        }
        Message::Text(_) => {
            log::error!("[surreal] 协议 {:?} 期望 Binary 帧, 但收到 Text", protocol);
            Err(SurrealError::ConnectionFailed("协议不匹配: 收到 Text 帧".into()))
        }
        Message::Close(frame) => {
            log::info!("[surreal] 收到 Close 帧: {frame:?}");
            Err(SurrealError::ConnectionLost)
        }
        _ => Ok(None), // Ping/Pong/Frame 由 tungstenite 自动处理
    }
}

// ============================================================
// 认证 (signin + use ns/db)
// ============================================================

/// 在新连接上执行 signin → use ns/db.
async fn authenticate(
    ws_sink: &mut WsSink,
    ws_stream: &mut WsSource,
    config: &SurrealConfig,
) -> Result<(), SurrealError> {
    // 步骤 1: signin
    let signin_params = crate::protocol::signin_params(&config.user, &config.password);
    auth_send_recv(ws_sink, ws_stream, 0, "signin", &signin_params, config.protocol)
        .await
        .map_err(|e| SurrealError::AuthFailed(format!("signin 失败: {e}")))?;

    // 步骤 2: use ns + db
    let use_params = crate::protocol::use_params(&config.namespace, &config.database);
    auth_send_recv(ws_sink, ws_stream, 1, "use", &use_params, config.protocol)
        .await
        .map_err(|e| SurrealError::AuthFailed(format!("use ns/db 失败: {e}")))?;

    Ok(())
}

/// 认证阶段的同步发送/接收 (一次一个请求).
async fn auth_send_recv(
    ws_sink: &mut WsSink,
    ws_stream: &mut WsSource,
    id: u64,
    method: &str,
    params: &Value,
    protocol: WireProtocol,
) -> Result<RpcResponse, SurrealError> {
    let msg = encode_message(protocol, id, method, params)?;
    ws_sink
        .send(msg)
        .await
        .map_err(|e| SurrealError::ConnectionFailed(format!("WS 发送失败: {e}")))?;

    // 等待匹配 id 的响应
    loop {
        let msg = ws_stream
            .next()
            .await
            .ok_or(SurrealError::ConnectionLost)?
            .map_err(|e| SurrealError::ConnectionFailed(format!("WS 读取错误: {e}")))?;

        let data: Vec<u8> = match msg {
            Message::Binary(data) => {
                if protocol != WireProtocol::Cbor {
                    return Err(SurrealError::ConnectionFailed(
                        "协议不匹配: 认证阶段收到 Binary".into(),
                    ));
                }
                data.to_vec()
            }
            Message::Text(text) => {
                if protocol != WireProtocol::Json {
                    return Err(SurrealError::ConnectionFailed(
                        "协议不匹配: 认证阶段收到 Text".into(),
                    ));
                }
                text.as_bytes().to_vec()
            }
            Message::Close(frame) => {
                return Err(SurrealError::ConnectionFailed(format!(
                    "认证期间连接关闭: {frame:?}"
                )));
            }
            _ => continue, // skip Ping/Pong
        };

        let resp = match protocol {
            WireProtocol::Cbor => codec::decode_response_cbor(&data)?,
            WireProtocol::Json => codec::decode_response_json(&data)?,
        };

        if resp.id == id {
            return if resp.is_success() {
                Ok(resp)
            } else {
                let msg = resp
                    .error
                    .map(|e| e.message)
                    .unwrap_or_else(|| "未知认证错误".into());
                Err(SurrealError::AuthFailed(msg))
            };
        }
        log::debug!(
            "[surreal] 认证阶段收到非预期响应 (id={}, expected={})",
            resp.id,
            id
        );
    }
}

// ============================================================
// 辅助函数
// ============================================================

/// 清空 pending map, 向所有等待者发送 ConnectionLost.
fn fail_all_pending(
    pending: &mut HashMap<u64, oneshot::Sender<Result<RawRpcBytes, SurrealError>>>,
) {
    for (_, tx) in pending.drain() {
        let _ = tx.send(Err(SurrealError::ConnectionLost));
    }
}

/// 指数退避延迟.
fn backoff_delay(attempt: u32, config: &SurrealConfig) -> std::time::Duration {
    let base = config.reconnect_base_delay.as_millis() as u64;
    let max = config.reconnect_max_delay.as_millis() as u64;
    let shift = (attempt.saturating_sub(1)).min(6);
    let delay_ms = base.saturating_mul(1u64 << shift);
    std::time::Duration::from_millis(delay_ms.min(max))
}