surmux 0.2.0

极简 SurrealDB WebSocket 客户端 — 单连接 JSON-RPC 多路复用, 极简依赖
Documentation
//! RPC 协议类型: 请求/响应/查询结果.
//!
//! SurrealDB WebSocket RPC 使用 JSON-RPC 风格消息:
//! - 请求: `{id, method, params}`
//! - 成功响应: `{id, result}`
//! - 错误响应: `{id, error: {code, message}}`

use serde::{Deserialize, Serialize};
use serde_json::Value;

// ============================================================
// RPC 请求
// ============================================================

/// 发送给 SurrealDB 的 RPC 请求.
#[derive(Debug, Clone, Serialize)]
pub struct RpcRequest {
    /// 请求 ID (u64), 用于匹配响应.
    pub id: u64,
    /// RPC 方法名: "query", "signin", "use", "ping", "let", 等.
    pub method: String,
    /// 方法参数, JSON 数组.
    pub params: Value,
}

impl RpcRequest {
    /// 创建新请求.
    pub fn new(id: u64, method: impl Into<String>, params: Value) -> Self {
        Self {
            id,
            method: method.into(),
            params,
        }
    }

    /// 序列化为 JSON 字符串 (用于 WebSocket Text 帧).
    pub fn to_json(&self) -> Result<String, serde_json::Error> {
        serde_json::to_string(self)
    }
}

// ============================================================
// RPC 响应
// ============================================================

/// SurrealDB 返回的原始响应 (可能成功或失败).
///
/// 字段 `id` 和 `result` 是所有成功响应共有,
/// `error` 仅在失败时存在.
#[derive(Debug, Clone, Deserialize)]
pub struct RpcResponse {
    /// 匹配请求的 id.
    pub id: u64,
    /// 成功时的结果 (可能是 Value, 也可能是包含 status/result 的数组).
    #[serde(default)]
    pub result: Value,
    /// 失败时的错误信息.
    #[serde(default)]
    pub error: Option<RpcError>,
}

/// RPC 错误详情 (SurrealDB 服务端返回).
#[derive(Debug, Clone, Deserialize)]
pub struct RpcError {
    /// SurrealDB 错误码 (负数).
    pub code: i64,
    /// SurrealDB 错误消息.
    pub message: String,
}

impl RpcResponse {
    /// 检查响应是否成功.
    pub fn is_success(&self) -> bool {
        self.error.is_none()
    }

    /// 获取 result, 如果 error 存在则返回错误.
    pub fn into_result(self) -> Result<Value, (i64, String)> {
        match self.error {
            Some(e) => Err((e.code, e.message)),
            None => Ok(self.result),
        }
    }
}

// ============================================================
// 查询结果
// ============================================================

/// `query` RPC 方法的返回结果: 一个或多个语句的执行结果数组.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct SurrealQueryResult {
    /// 执行耗时 (字符串格式, 如 "120.5µs").
    #[serde(default)]
    pub time: String,
    /// 状态: "OK" 或错误信息.
    #[serde(default)]
    pub status: String,
    /// 查询结果 (通常是 `[{...}, ...]` 格式的 JSON 数组).
    #[serde(default)]
    pub result: Value,
}

impl SurrealQueryResult {
    /// 检查此条查询是否成功.
    pub fn is_ok(&self) -> bool {
        self.status == "OK"
    }

    /// 从 result 字段中提取 Vec<T>.
    ///
    /// result 类型为 `[{...}, ...]` 数组.
    pub fn take<T: for<'de> Deserialize<'de>>(&self) -> Result<Vec<T>, serde_json::Error> {
        if self.result.is_null() {
            return Ok(Vec::new());
        }
        serde_json::from_value(self.result.clone())
    }

    /// 从 result 数组中提取第一个元素.
    pub fn take_first<T: for<'de> Deserialize<'de>>(&self) -> Result<Option<T>, serde_json::Error> {
        let items: Vec<T> = self.take()?;
        Ok(items.into_iter().next())
    }
}

// ============================================================
// 辅助: 构建 signin 参数
// ============================================================

/// 构建 signin 方法的 params.
pub fn signin_params(user: &str, pass: &str) -> Value {
    serde_json::json!([{
        "user": user,
        "pass": pass,
    }])
}

/// 构建 use 方法的 params (设置 NS + DB).
pub fn use_params(ns: &str, db: &str) -> Value {
    serde_json::json!([ns, db])
}

/// 构建 query 方法的 params.
pub fn query_params(sql: &str, bindings: Option<&Value>) -> Value {
    match bindings {
        Some(b) if !b.as_object().map(|o| o.is_empty()).unwrap_or(true) => {
            serde_json::json!([sql, b])
        }
        _ => serde_json::json!([sql]),
    }
}

/// 构建 let/set 方法的 params.
pub fn set_params(key: &str, value: &Value) -> Value {
    serde_json::json!([key, value])
}