surmux 0.2.0

极简 SurrealDB WebSocket 客户端 — 单连接 JSON-RPC 多路复用, 极简依赖
Documentation

surmux

SurrealDB WebSocket 客户端 — 最小依赖, 单连接 JSON-RPC 多路复用, typed CBOR Tag 兼容.

[dependencies]
surmux = "0.1"

Examples

命令 覆盖
cargo run --example basic connect / health / version / CRUD (create select update upsert delete) / QueryBuilder (bind bind_all timeout one all exec raw) / transaction / set / unset
cargo run --example bucket BucketOps 文件存: put_bytes / get_bytes / list / delete (CBOR 原生 Bytes, 零膨胀)
cargo run --example pool SurrealPool 高并发 round-robin (见 tests/high_concurrency.rs 实测)
cargo run --example json_protocol JSON 协议烟雾测试
cargo run --example typed_vs_value .all::<T>() 通用路径 vs .all_typed::<T>() typed path 对比
cargo run --example bench_typed_adapter typed path + 4 个 Tag wrapper decode 加速测试
cargo run --example bench_protocol_compare CBOR vs JSON 4 场景配对基准

启动 SurrealDB

--user --pass 必填 (源码强校验).

# KV 持久化 (推荐 dev / 集成测试)
surreal start \
  --bind 127.0.0.1:8124 --user <USER> --pass <***> \
  surrealkv:///path/to/data

# --allow-experimental files (bucket 例子需要)
surreal start ... --allow-experimental files

环境变量等价: SURREAL_USER / SURREAL_PASS / SURREAL_BIND.

4 核 / 4 GB 部署 (默认不 OOM 配置)

4GB 机器不配会 OOM-kill. 必须显式压:

# SurrealDB 服务端
SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY=134217728   # 128 MB
SURREAL_SURREALKV_MAX_MEMTABLE_SIZE=33554432        # 32 MB
MALLOC_CONF=background_thread:true,dirty_decay_ms:1000,muzzy_decay_ms:0

# systemd
MemoryMax=2G
MemoryHigh=1536M

为什么限内存不 OOM: SurrealKV 是 LSM-tree, memtable 写满自动 flush 到 sstable (落盘). block_cache 只是热数据缓存, 容量变小只是降低缓存命中率 → 读路径变慢, 不限制总数据量. 磁盘容量上限即可用数据上限 (与内存无关).

详细测试结果: docs/MEM_PRESSURE_RESULTS.md.

客户端:

# Cargo.toml 已含
[profile.release]
opt-level = 3
lto = "thin"          # fat 在 4H4G cargo build 内存峰值 > 4 GB
codegen-units = 1     # codec 单态化, all_typed +8-12%
panic = "abort"
strip = "symbols"
#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() { /* ... */ }

typed path + Tag adapter (CBOR Tag 自动适配)

SurrealDB 返回的 CBOR 含自定义 Tag, 默认 chrono/uuid Deserialize 不识别, 报错. serde_compat 模块提供 4 个 wrapper 让 typed path 直接吃:

use surmux::serde_compat::{cbor_record_id, cbor_datetime, cbor_uuid, RecordId};

#[derive(Deserialize)]
struct User {
    #[serde(deserialize_with = "cbor_record_id::deserialize")]
    id: RecordId,                              // Tag 8
    #[serde(deserialize_with = "cbor_datetime::deserialize")]
    created_at: chrono::DateTime<chrono::Utc>, // Tag 0 / Tag 12
    #[serde(deserialize_with = "cbor_uuid::deserialize")]
    session_id: uuid::Uuid,                    // Tag 9 / Tag 37
    name: String,
    age: i64,
}

let users: Vec<User> = client.query("SELECT * FROM user").all_typed().await?;

CBOR Tag 表:

Tag 类型 内部 wire
6 None Null
8 RecordId Text("t:k") 或 Array[t,k]
9 UUID Text(uuid-string)
12 Datetime Array[i64 secs, u32 nanos]
37 UUID Bytes(16)

单元测试: cargo test --lib --release (4 个 wrapper).

CBOR vs JSON 性能 (surrealkv, 1M 行 × 4 字段, 走 typed path)

数据集总规模 1M 行, S3 单次读 LIMIT 10000 (1.3 MB).

场景 CBOR JSON CBOR / JSON
S1 空查询 p50 88 μs 90 μs 0.98×
S2 1 行读 p50 176 μs 189 μs 0.93×
S3 10 000 行读 (1.3 MB) p50 33.2 ms 41.9 ms 0.79× (CBOR 反超)
S4 100 并发吞吐 6 219 qps 6 182 qps 1.01×
数据集插入速率 78 884 行/s — —

详细 + 测试方法: docs/PROTOCOL_BENCH_RESULTS.md.

重构后 typed path decode 加速 (vs 重构前 .all::<T>() 通用路径):

路径 S3 p50 加速
.all::<T>() 通用 (3 次全树物化) 73.8 ms 1.00× 基线
.all_typed::<T>() typed (1 次流式) 33.2 ms 2.22× (-55%)

S3 反转原因: .all::<T>() 通用路径 CBOR 多走 CborValue → JsonValue 中间树两次物化, decode 比 JSON 还慢 (73.8 vs 41.9 ms, CBOR/JSON = 1.76×). typed path 跳过中间树, CBOR 解码常数小, 反超 JSON 1.26×.

CBOR 必胜场景: Bytes 字段 (bucket 文件 / 图片) — JSON 走 [byte,...] 4× 膨胀, CBOR 走原生 byte string.

API 速览

类型 作用
SurrealConfig::new(url) builder: user / password / namespace / database / connect_timeout / query_timeout
SurrealClient::connect(config) 单连接入口 (自动重连 + 重连后自动重新认证)
client.health() / version() 健康检查 / 服务端版本
client.set(k,v) / unset(k) key-value 持久化
client.query(sql) → QueryBuilder 流式构建: bind bind_all timeout one::<T> all::<T> all_typed::<T> exec raw
client.transaction(&[...]) 多语句原子事务
client.create/update/upsert/delete/select 便捷 CRUD
client.bucket(name) → BucketOps 文件存储 (put_bytes / get_bytes / list / delete)
SurrealPool::connect(config, n) N 个 WS 连接 round-robin 池
serde_compat::RecordId 等 CBOR Tag adapter (见 §typed path)

设计原则

  • 单 WS 连接 + id-based 多路复用, 单连接数千并发请求.
  • 仅 ~11 个直接依赖 (vs 官方 SDK ~500+).
  • 自动重连: 指数退避 + 重连后自动重新执行 signin / use ns/db.
  • 协议默认 CBOR, 二进制 Bytes / Bucket 文件零膨胀.

Lint (clippy)

Cargo.toml [lints.clippy] 三档:

[lints.clippy]
all          = { level = "warn",  priority = -1 }  # 所有 clippy lint → warning
correctness  = { level = "deny",  priority = -1 }  # 正确性 bug 必拦
perf         = { level = "deny",  priority = -1 }  # 性能陷阱必拦
suspicious   = { level = "deny",  priority = -1 }  # 怀疑代码必拦

CI / 本地验证:

cargo clippy --all-targets -- -D warnings   # 0 warning 才算过

设计取舍: all = warn 而非 deny — clippy 默认集已涵盖 correctness, 新版本加 lint 不会突然拦死构建; correctness/perf/suspicious 三组 deny 兜底, 真正的高危 bug 编译就报.

这是个 surrealdb 的学习与验证库

  • 环境 / 性能 / Tag adapter / typed path 全部覆盖.
  • docs/ 是 SurrealDB 部署 + bench 真测数据, 供学.
  • tests/ 是功能 + 压力 + 并发 + 4H4G 内存 验证, 跑得通即真实.

License

MIT