surmux
SurrealDB WebSocket 客户端 — 最小依赖, 单连接 JSON-RPC 多路复用, typed CBOR Tag 兼容.
[]
= "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 / 集成测试)
# --allow-experimental files (bucket 例子需要)
环境变量等价: 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 已含
[]
= 3
= "thin" # fat 在 4H4G cargo build 内存峰值 > 4 GB
= 1 # codec 单态化, all_typed +8-12%
= "abort"
= "symbols"
async
typed path + Tag adapter (CBOR Tag 自动适配)
SurrealDB 返回的 CBOR 含自定义 Tag, 默认 chrono/uuid Deserialize 不识别, 报错.
serde_compat 模块提供 4 个 wrapper 让 typed path 直接吃:
use ;
let users: = client.query.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] 三档:
[]
= { = "warn", = -1 } # 所有 clippy lint → warning
= { = "deny", = -1 } # 正确性 bug 必拦
= { = "deny", = -1 } # 性能陷阱必拦
= { = "deny", = -1 } # 怀疑代码必拦
CI / 本地验证:
设计取舍: all = warn 而非 deny — clippy 默认集已涵盖 correctness, 新版本加 lint 不会突然拦死构建; correctness/perf/suspicious 三组 deny 兜底, 真正的高危 bug 编译就报.
这是个 surrealdb 的学习与验证库
- 环境 / 性能 / Tag adapter / typed path 全部覆盖.
- docs/ 是 SurrealDB 部署 + bench 真测数据, 供学.
- tests/ 是功能 + 压力 + 并发 + 4H4G 内存 验证, 跑得通即真实.
License
MIT