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
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
//! RPC 编解码器: CBOR 与 JSON 协议的请求/响应序列化与反序列化.
//!
//! SurrealDB v3.x 通过 WS 子协议 (`Sec-WebSocket-Protocol: cbor` / `json`) 协商协议,
//! 整个连接锁定一种格式. CBOR (默认) 对二进制数据有原生支持, `Value::Bytes` 零膨胀;
//! JSON 兼容更好但 `Bytes` 会变成 `[byte, byte, ...]` 整数数组 (~4x 膨胀).
//!
//! ## 函数命名约定
//! 所有公开函数都用 `*_cbor` 或 `*_json` 后缀明确协议, 不提供不带后缀的别名.

use std::io;

use ciborium::value::Integer;
use ciborium::value::Value as CborValue;
use serde::de::DeserializeOwned;
use serde::Deserialize;
use serde_json::Value as JsonValue;

use crate::error::{SurrealError, SurrealResult};
use crate::protocol::{RpcError, RpcResponse};

// ============================================================
// 辅助
// ============================================================

fn json_error(msg: impl Into<String>) -> serde_json::Error {
    serde_json::Error::io(io::Error::other(msg.into()))
}

// ============================================================
// CBOR 编码
// ============================================================

/// 将 RPC 请求编码为 CBOR 字节 (等价于 JSON `{id, method, params}`).
///
/// CBOR 结构:
/// ```cbor
/// { "id": 1, "method": "query", "params": [...] }
/// ```
pub fn encode_request_cbor(id: u64, method: &str, params: &JsonValue) -> SurrealResult<Vec<u8>> {
    let cbor_params = json_to_cbor(params);
    let map = CborValue::Map(vec![
        (
            CborValue::Text("id".into()),
            CborValue::Integer(Integer::from(id)),
        ),
        (
            CborValue::Text("method".into()),
            CborValue::Text(method.into()),
        ),
        (CborValue::Text("params".into()), cbor_params),
    ]);

    let mut buf = Vec::new();
    ciborium::into_writer(&map, &mut buf).map_err(|e| {
        SurrealError::SerializationFailed(json_error(format!("CBOR 编码失败: {e}")))
    })?;
    Ok(buf)
}

/// 将 serde_json::Value 递归转换为 ciborium::Value.
///
/// 特殊处理: 单键 `$cbor_bytes` (base64) 转为原生 CBOR byte string.
fn json_to_cbor(v: &JsonValue) -> CborValue {
    match v {
        JsonValue::Null => CborValue::Null,
        JsonValue::Bool(b) => CborValue::Bool(*b),
        JsonValue::Number(n) => {
            if let Some(i) = n.as_i64() {
                CborValue::Integer(Integer::from(i))
            } else if let Some(f) = n.as_f64() {
                CborValue::Float(f)
            } else {
                CborValue::Text(n.to_string())
            }
        }
        JsonValue::String(s) => CborValue::Text(s.clone()),
        JsonValue::Array(arr) => CborValue::Array(arr.iter().map(json_to_cbor).collect()),
        JsonValue::Object(obj) => {
            // $cbor_bytes 标记: base64 字符串 → CBOR byte string (BucketOps::put_bytes 用)
            if obj.len() == 1
                && let Some(JsonValue::String(b64)) = obj.get("$cbor_bytes") {
                    use base64::Engine;
                    if let Ok(bytes) = base64::engine::general_purpose::STANDARD.decode(b64) {
                        return CborValue::Bytes(bytes);
                    }
                }
            CborValue::Map(
                obj.iter()
                    .map(|(k, v)| (CborValue::Text(k.clone()), json_to_cbor(v)))
                    .collect(),
            )
        }
    }
}

// ============================================================
// JSON 编码
// ============================================================

/// 将 RPC 请求编码为 JSON 字符串.
///
/// JSON 结构: `{"id":1,"method":"query","params":[...]}`
pub fn encode_request_json(id: u64, method: &str, params: &JsonValue) -> SurrealResult<String> {
    let obj = JsonValue::Object({
        let mut m = serde_json::Map::new();
        m.insert("id".into(), JsonValue::Number(id.into()));
        m.insert("method".into(), JsonValue::String(method.to_string()));
        m.insert("params".into(), params.clone());
        m
    });
    serde_json::to_string(&obj).map_err(SurrealError::SerializationFailed)
}

// ============================================================
// CBOR 解码 (通用路径, 经 CborValue → JsonValue 树)
// ============================================================

/// 通用解码: 把 CBOR 字节先解到 `CborValue` 全树, 再递归转为 `serde_json::Value`,
/// 最终构造 `RpcResponse`. QueryBuilder 的 `raw()` / `all()` / `one()` 走这里.
///
/// 性能敏感场景改用 typed path `decode_query_result_typed` 跳过中间树.
pub fn decode_response_cbor(data: &[u8]) -> SurrealResult<RpcResponse> {
    let value: CborValue = ciborium::from_reader(data)
        .map_err(|e| SurrealError::SerializationFailed(json_error(format!("CBOR 解码失败: {e}"))))?;
    cbor_to_response(&value)
}

fn cbor_to_response(map: &CborValue) -> SurrealResult<RpcResponse> {
    let fields = match map {
        CborValue::Map(m) => m,
        _ => {
            return Err(SurrealError::SerializationFailed(json_error(
                "响应不是 CBOR Map",
            )));
        }
    };

    let mut id: Option<u64> = None;
    let mut result: Option<CborValue> = None;
    let mut error: Option<RpcError> = None;

    for (key, val) in fields {
        let key_str = match key {
            CborValue::Text(s) => s.as_str(),
            _ => continue,
        };

        match key_str {
            "id" => {
                id = match val {
                    CborValue::Integer(i) => u64::try_from(*i).ok(),
                    _ => None,
                };
            }
            "result" => {
                result = Some(val.clone());
            }
            "error" => {
                error = parse_cbor_error(val);
            }
            _ => {}
        }
    }

    let id = id.unwrap_or(0);
    let json_result = match result {
        Some(ref v) => cbor_to_json(v),
        None => JsonValue::Null,
    };

    Ok(RpcResponse {
        id,
        result: json_result,
        error,
    })
}

fn parse_cbor_error(val: &CborValue) -> Option<RpcError> {
    match val {
        CborValue::Map(fields) => {
            let mut code: i64 = -1;
            let mut message = String::new();
            for (key, val) in fields {
                let key_str = match key {
                    CborValue::Text(s) => s.as_str(),
                    _ => continue,
                };
                match key_str {
                    "code" => {
                        if let CborValue::Integer(i) = val {
                            code = i64::try_from(*i).unwrap_or(-1);
                        }
                    }
                    "message" => {
                        if let CborValue::Text(s) = val {
                            message = s.clone();
                        }
                    }
                    _ => {}
                }
            }
            Some(RpcError { code, message })
        }
        _ => None,
    }
}

/// CBOR Value → JSON Value 递归转换.
fn cbor_to_json(val: &CborValue) -> JsonValue {
    match val {
        CborValue::Null => JsonValue::Null,
        CborValue::Bool(b) => JsonValue::Bool(*b),
        CborValue::Integer(i) => {
            if let Ok(n) = i64::try_from(*i) {
                JsonValue::Number(n.into())
            } else if let Ok(n) = u64::try_from(*i) {
                JsonValue::Number(n.into())
            } else {
                JsonValue::String(i128::from(*i).to_string())
            }
        }
        CborValue::Float(f) => serde_json::Number::from_f64(*f)
            .map(JsonValue::Number)
            .unwrap_or(JsonValue::Null),
        CborValue::Text(s) => JsonValue::String(s.clone()),
        // CBOR byte string → base64 字符串 (JSON 无法表示字节)
        CborValue::Bytes(data) => {
            use base64::Engine;
            JsonValue::String(base64::engine::general_purpose::STANDARD.encode(data))
        }
        CborValue::Array(arr) => JsonValue::Array(arr.iter().map(cbor_to_json).collect()),
        CborValue::Map(fields) => {
            let mut obj = serde_json::Map::new();
            for (key, val) in fields {
                let key_str = match key {
                    CborValue::Text(s) => s.clone(),
                    CborValue::Integer(i) => i128::from(*i).to_string(),
                    _ => continue,
                };
                obj.insert(key_str, cbor_to_json(val));
            }
            JsonValue::Object(obj)
        }
        // Tag 透明穿透: 把内部值递归转换 (Tag 6 NONE → null, Tag 8 RecordId → 内部 array 等)
        CborValue::Tag(_tag, inner) => cbor_to_json(inner),
        _ => JsonValue::Null,
    }
}

// ============================================================
// JSON 解码
// ============================================================

/// 将 JSON 字符串解码为 RPC 响应.
pub fn decode_response_json(data: &[u8]) -> SurrealResult<RpcResponse> {
    serde_json::from_slice::<RpcResponse>(data).map_err(SurrealError::SerializationFailed)
}

// ============================================================
// 路由 peek: 仅提取 id 字段
// ============================================================

/// 仅从 CBOR map 中提取 `id` 字段 (router 路由用).
///
/// 比完整 `decode_response_cbor` 省掉 CborValue 全树物化 + cbor_to_json 递归.
/// 用 thread-local scratch 避免每次调用 memzero 64KB (cb 内存带宽).
pub fn peek_response_id_cbor(data: &[u8]) -> SurrealResult<u64> {
    #[derive(Deserialize)]
    struct IdOnly {
        id: u64,
    }
    // 64KB scratch 由 ciborium 内部按需 memset, 复用避免每次都 memzero.
    thread_local! {
        static SCRATCH: std::cell::RefCell<[u8; 64 * 1024]> = const { std::cell::RefCell::new([0u8; 64 * 1024]) };
    }
    SCRATCH.with(|s| {
        let mut scratch = s.borrow_mut();
        let v: IdOnly = ciborium::from_reader_with_buffer(data, &mut *scratch)
            .map_err(|e| SurrealError::CborDecodeFailed(e.to_string()))?;
        Ok(v.id)
    })
}

/// 仅从 JSON 文本中提取 `id` 字段.
pub fn peek_response_id_json(data: &[u8]) -> SurrealResult<u64> {
    #[derive(Deserialize)]
    struct IdOnly {
        id: u64,
    }
    serde_json::from_slice::<IdOnly>(data)
        .map(|v| v.id)
        .map_err(SurrealError::SerializationFailed)
}

// ============================================================
// CBOR 直反序列化到 T (方案 2: 跳过 JsonValue 中间树)
// ============================================================

/// CBOR RPC 响应包装 (强类型直反序列化目标).
///
/// SurrealDB 字段顺序 (BTreeMap 字母序): `error / id / result`.
/// `#[allow(dead_code)]` 用于 `id` / `kind`: deserialize 必须声明字段以匹配 schema,
/// 但 query 路径只读 `result`, 不读其余字段.
#[derive(Deserialize)]
#[serde(bound(deserialize = "T: Deserialize<'de>"))]
#[allow(dead_code)]
struct CborRpcResponse<T> {
    id: u64,
    #[serde(default = "Vec::new")]
    result: Vec<CborQueryResult<T>>,
    #[serde(default)]
    error: Option<CborRpcError>,
}

/// 单条 query 语句的 CBOR 结果包装.
///
/// SurrealDB 字段顺序 (字母序): `result / status / time / type`.
/// `type` 是 CBOR Tag 6 包 Null (NONE), 用 `IgnoredAny` 丢弃.
///
/// **已知 trade-off**: 当语句执行失败 (status != "OK") 时, SurrealDB 把 `result`
/// 字段填为错误字符串而非数组. typed path 直接对 `result: Vec<T>` 反序列化,
/// serde 会先报 `CborDecodeFailed` 而不是友好的 `QueryFailed`. 想拿到
/// 语句级错误信息请走 `.all::<T>()` 通用路径 (或用 CBOR + 显式 try).
#[derive(Deserialize)]
#[serde(bound(deserialize = "T: Deserialize<'de>"))]
#[allow(dead_code)]
struct CborQueryResult<T> {
    status: String,
    #[serde(default)]
    time: Option<String>,
    result: Vec<T>,
    #[serde(default, rename = "type")]
    _type: serde::de::IgnoredAny,
}

/// CBOR 错误响应包装 (宽容解析, 所有字段可选).
#[derive(Deserialize)]
#[allow(dead_code)]
struct CborRpcError {
    #[serde(default)]
    code: Option<i64>,
    #[serde(default)]
    message: Option<String>,
    #[serde(default)]
    kind: Option<String>,
}

/// CBOR 直反序列化到 `Vec<T>`, 跳过 CborValue → JsonValue 中间树.
///
/// ## 数据流
/// ```text
/// CBOR bytes → CborRpcResponse<T> (serde 自动驱动 T::deserialize)
///           → 第一条 query statement 的 result 字段
/// ```
///
/// ## 性能
/// 对比 `decode_response_cbor + cbor_to_json + from_value<Vec<T>>`,
/// 省去一次全树物化 (CBOR → CborValue) + 一次递归转换 (CborValue → JsonValue).
/// 实测 decode 阶段提速 50-120% (见 `examples/bench_cbor_typed.rs`).
///
/// ## CBOR Tag 兼容性
/// SurrealDB 对 Datetime 用 Tag 12 `[secs, nanos]`, 对 RecordId 用 Tag 8 `[table, key]`,
/// 对 UUID 用 Tag 37 (16 bytes). 配合 `serde_compat` 模块的 wrapper 用.
pub fn decode_query_result_typed<T: DeserializeOwned>(data: &[u8]) -> SurrealResult<Vec<T>> {
    // 64KB scratch 用 thread_local 复用, 避免每次调用 memzero (cb 内存带宽).
    thread_local! {
        static SCRATCH: std::cell::RefCell<[u8; 64 * 1024]> = const { std::cell::RefCell::new([0u8; 64 * 1024]) };
    }
    SCRATCH.with(|s| -> SurrealResult<Vec<T>> {
        let mut scratch = s.borrow_mut();
        let resp: CborRpcResponse<T> = ciborium::from_reader_with_buffer(data, &mut *scratch)
            .map_err(|e| SurrealError::CborDecodeFailed(e.to_string()))?;

        if let Some(err) = resp.error {
            return Err(SurrealError::QueryFailed {
                code: err.code.unwrap_or(-1),
                message: err.message.unwrap_or_else(|| "未知错误".into()),
            });
        }

        let first = resp.result.into_iter().next().ok_or(SurrealError::NoResult)?;

        if first.status != "OK" {
            return Err(SurrealError::QueryFailed {
                code: -1,
                message: format!("查询状态异常: {}", first.status),
            });
        }
        Ok(first.result)
    })
}

/// JSON 直反序列化到 `Vec<T>`.
///
/// 与 `decode_query_result_typed` 对称, 用于 JSON 协议路径.
pub fn decode_query_result_typed_json<T: DeserializeOwned>(data: &[u8]) -> SurrealResult<Vec<T>> {
    #[derive(Deserialize)]
    #[serde(bound(deserialize = "T: Deserialize<'de>"))]
    #[allow(dead_code)]
    struct JsonRpcResponse<T> {
        id: u64,
        #[serde(default = "Vec::new")]
        result: Vec<JsonQueryResult<T>>,
        #[serde(default)]
        error: Option<RpcError>,
    }
    #[derive(Deserialize)]
    #[serde(bound(deserialize = "T: Deserialize<'de>"))]
    #[allow(dead_code)]
    struct JsonQueryResult<T> {
        status: String,
        #[serde(default)]
        time: Option<String>,
        #[serde(default)]
        result: Vec<T>,
        #[serde(default, rename = "type")]
        _type: serde::de::IgnoredAny,
    }

    let resp: JsonRpcResponse<T> =
        serde_json::from_slice(data).map_err(SurrealError::SerializationFailed)?;

    if let Some(err) = resp.error {
        return Err(SurrealError::QueryFailed {
            code: err.code,
            message: err.message,
        });
    }

    let first = resp
        .result
        .into_iter()
        .next()
        .ok_or(SurrealError::NoResult)?;

    if first.status != "OK" {
        return Err(SurrealError::QueryFailed {
            code: -1,
            message: format!("查询状态异常: {}", first.status),
        });
    }
    Ok(first.result)
}

// ============================================================
// CBOR 字节直接提取 (BucketOps::get_bytes 高效路径)
// ============================================================

/// 从查询响应的 CBOR 数据中提取原始字节 (file::get 用).
///
/// 查询响应结构: `{ id, result: [{ status, time, type, result: h'.....' }] }`.
pub fn extract_query_result_bytes(data: &[u8]) -> SurrealResult<Vec<u8>> {
    let value: CborValue = ciborium::from_reader(data).map_err(|e| {
        SurrealError::SerializationFailed(json_error(format!("CBOR 解码失败: {e}")))
    })?;

    let rpc_result = match &value {
        CborValue::Map(fields) => fields
            .iter()
            .find(|(k, _)| matches!(k, CborValue::Text(s) if s == "result"))
            .map(|(_, v)| v),
        _ => None,
    }
    .ok_or(SurrealError::NoResult)?;

    let results: &[CborValue] = match rpc_result {
        CborValue::Array(arr) => arr.as_slice(),
        _ => &[],
    };

    let first = results.first().ok_or(SurrealError::NoResult)?;

    if let CborValue::Map(fields) = first {
        let status_ok = fields.iter().any(|(k, v)| {
            matches!(k, CborValue::Text(s) if s == "status")
                && matches!(v, CborValue::Text(s) if s == "OK")
        });
        if !status_ok {
            return Err(SurrealError::QueryFailed {
                code: -1,
                message: "file::get 查询状态非 OK".into(),
            });
        }

        for (key, val) in fields {
            if matches!(key, CborValue::Text(s) if s == "result") {
                return match val {
                    CborValue::Bytes(data) => Ok(data.clone()),
                    CborValue::Text(s) => {
                        use base64::Engine;
                        base64::engine::general_purpose::STANDARD
                            .decode(s)
                            .map_err(|e| SurrealError::QueryFailed {
                                code: -1,
                                message: format!("base64 解码失败: {e}"),
                            })
                    }
                    _ => Err(SurrealError::QueryFailed {
                        code: -1,
                        message: "file::get 返回类型不是 Bytes".into(),
                    }),
                };
            }
        }
    }

    Err(SurrealError::NoResult)
}