surmux 0.2.0

极简 SurrealDB WebSocket 客户端 — 单连接 JSON-RPC 多路复用, 极简依赖
Documentation
//! SurrealClient: 主入口, 连接管理 + 查询 API.
//!
//! 基于 Arc 实现廉价 Clone, 可安全地在多任务间共享.

use std::sync::Arc;
use std::time::Duration;

use serde::Serialize;
use serde::de::DeserializeOwned;
use serde_json::Value;
use tokio::sync::mpsc::UnboundedSender;

use crate::bucket::BucketOps;
use crate::config::SurrealConfig;
use crate::error::{SurrealError, SurrealResult};
use crate::query::{QueryBuilder, send_command, send_command_void};
use crate::router::{self, RouterCommand};

// ============================================================
// SurrealClient
// ============================================================

/// SurrealDB WebSocket 客户端.
///
/// # 特性
///
/// - **廉价 Clone**: 内部使用 `Arc`, Clone 仅增加引用计数
/// - **多路复用**: 单个 WS 连接承载所有并发请求
/// - **自动重连**: 连接断开后指数退避重连
/// - **线程安全**: `Send + Sync`, 可在多任务间共享
///
/// # 使用示例
///
/// ```rust,ignore
/// let config = SurrealConfig::new("localhost:8000")
///     .user("root").password("root")
///     .namespace("test").database("test");
///
/// let client = SurrealClient::connect(config).await?;
///
/// // 查询
/// let users: Vec<User> = client
///     .query("SELECT * FROM users WHERE status = $s")
///     .bind("s", "active")
///     .all()
///     .await?;
/// ```
#[derive(Clone)]
pub struct SurrealClient {
    inner: Arc<ClientInner>,
}

impl std::fmt::Debug for SurrealClient {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SurrealClient")
            .field("namespace", &self.inner.config.namespace)
            .field("database", &self.inner.config.database)
            .field("url", &self.inner.config.url)
            .finish()
    }
}

struct ClientInner {
    /// 向 Router 发送命令的通道.
    request_tx: UnboundedSender<RouterCommand>,
    /// 连接配置 (用于重连).
    #[allow(dead_code)]
    config: SurrealConfig,
    /// 默认查询超时.
    query_timeout: Duration,
    /// Router 后台任务句柄 (drop 时不自动取消, 由 ClientInner drop 时释放 sender 触发).
    _router_handle: Arc<tokio::task::JoinHandle<()>>,
}

impl SurrealClient {
    /// 建立连接并认证.
    ///
    /// 此方法会:
    /// 1. 建立 WebSocket 连接到 SurrealDB
    /// 2. 执行 signin 认证
    /// 3. 选择 namespace + database
    /// 4. 启动后台 Router 任务
    pub async fn connect(config: SurrealConfig) -> SurrealResult<Self> {
        config.validate()?;

        let query_timeout = config.query_timeout;
        let (request_tx, request_rx) = router::router_channel();

        // 启动 Router 后台任务 (内含 WS 握手 + signin + use ns/db)
        let handle = router::spawn_router(request_rx, config.clone());

        let client = Self {
            inner: Arc::new(ClientInner {
                request_tx: request_tx.clone(),
                config: config.clone(),
                query_timeout,
                _router_handle: Arc::new(handle),
            }),
        };

        // 等待 Router 完成握手与认证, 通过发送 ping 确认 WS 双向通信就绪.
        // health() 内部走 query_timeout (默认 30s), 不用 connect_timeout.
        match client.health().await {
            Ok(()) => Ok(client),
            Err(e) => {
                // 初次连接偶发失败 (服务端刚启动 / 网络抖动) — 给 Router 一点时间重连后重试一次
                log::warn!("[surreal] 初始 health check 失败: {e}, 等待重连后重试...");
                tokio::time::sleep(Duration::from_millis(200)).await;
                client.health().await?;
                Ok(client)
            }
        }
    }

    // ============================================================
    // 基础操作
    // ============================================================

    /// 健康检查 (发送 ping).
    pub async fn health(&self) -> SurrealResult<()> {
        send_command_void(
            &self.inner.request_tx,
            "ping",
            serde_json::json!([]),
            self.inner.query_timeout,
        )
        .await
    }

    /// 获取服务器版本.
    pub async fn version(&self) -> SurrealResult<String> {
        let result = send_command(
            &self.inner.request_tx,
            "version",
            serde_json::json!([]),
            self.inner.query_timeout,
        )
        .await?;

        match result {
            Value::String(s) => Ok(s),
            _ => Ok(result.to_string()),
        }
    }

    /// 设置会话变量.
    ///
    /// 对应 SurrealQL 的 `LET $key = value`.
    /// 注意: 连接断开重连后会话变量会丢失.
    pub async fn set(&self, key: &str, value: &(impl Serialize + ?Sized)) -> SurrealResult<()> {
        let v = serde_json::to_value(value).map_err(SurrealError::SerializationFailed)?;
        let params = crate::protocol::set_params(key, &v);

        send_command_void(
            &self.inner.request_tx,
            "let",
            params,
            self.inner.query_timeout,
        )
        .await
    }

    /// 取消会话变量.
    pub async fn unset(&self, key: &str) -> SurrealResult<()> {
        send_command_void(
            &self.inner.request_tx,
            "unset",
            serde_json::json!([key]),
            self.inner.query_timeout,
        )
        .await
    }

    // ============================================================
    // 查询 API
    // ============================================================

    /// 开始构建查询.
    ///
    /// 返回 `QueryBuilder`, 可通过 `.bind()` 绑定参数,
    /// 通过 `.one()`, `.all()`, `.raw()`, `.exec()` 执行.
    pub fn query(&self, sql: impl Into<String>) -> QueryBuilder<'_> {
        QueryBuilder {
            request_tx: self.inner.request_tx.clone(),
            sql: sql.into(),
            bindings: Default::default(),
            query_timeout: self.inner.query_timeout,
            bind_error: None,
            _phantom: std::marker::PhantomData,
        }
    }

    // ============================================================
    // 事务 API
    // ============================================================

    /// 在事务中执行多条 SurrealQL 语句.
    ///
    /// 所有语句拼接为单条多语句查询:
    /// `BEGIN TRANSACTION; stmt1; stmt2; ...; COMMIT TRANSACTION;`
    ///
    /// # 示例 (Token 分配)
    ///
    /// ```rust,ignore
    /// let results = client.transaction(&[
    ///     "LET $t = (SELECT * FROM product_alloc WHERE product_id = $pid AND status = 'free' LIMIT 1)",
    ///     "UPDATE $t.id SET status = 'allocated', allocated_at = time::now() RETURN AFTER",
    /// ]).bind("pid", product_id).await?;
    /// ```
    pub fn transaction(&self, statements: &[&str]) -> QueryBuilder<'_> {
        let mut sql = String::from("BEGIN TRANSACTION;");
        for stmt in statements {
            sql.push_str(stmt);
            if !stmt.ends_with(';') {
                sql.push(';');
            }
        }
        sql.push_str("COMMIT TRANSACTION;");

        self.query(sql)
    }

    // ============================================================
    // Bucket 文件操作
    // ============================================================

    /// 获取 Bucket 操作句柄.
    ///
    /// 需要 SurrealDB 服务端启用 `--allow-experimental files`.
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let bucket = client.bucket("firmware");
    /// bucket.put("path/to/file.bin", &data).await?;
    /// let data = bucket.get("path/to/file.bin").await?;
    /// ```
    pub fn bucket(&self, name: impl Into<String>) -> BucketOps<'_> {
        BucketOps {
            request_tx: self.inner.request_tx.clone(),
            bucket_name: name.into(),
            query_timeout: self.inner.query_timeout,
            _phantom: std::marker::PhantomData,
        }
    }

    // ============================================================
    // 便捷 CRUD 方法
    // ============================================================

    /// CREATE: 创建新记录.
    ///
    /// ```rust,ignore
    /// client.create("users", &user).await?;
    /// ```
    pub async fn create(&self, table: &str, data: &impl Serialize) -> SurrealResult<Value> {
        let json_data = serde_json::to_value(data).map_err(SurrealError::SerializationFailed)?;
        let sql = format!("CREATE {table} CONTENT $data");
        self.query(&sql)
            .bind("data", &json_data)
            .raw()
            .await
            .map(|mut r| {
                r.first_mut()
                    .map(|q| std::mem::take(&mut q.result))
                    .unwrap_or(Value::Null)
            })
    }

    /// SELECT: 按 ID 查询.
    ///
    /// ```rust,ignore
    /// let user: Option<User> = client.select("users", "id123").await?;
    /// ```
    pub async fn select<T: DeserializeOwned>(
        &self,
        table: &str,
        id: &str,
    ) -> SurrealResult<Option<T>> {
        let sql = format!("SELECT * FROM {table}:`{id}`");
        self.query(&sql).one().await
    }

    /// UPDATE: 按 ID 更新.
    ///
    /// ```rust,ignore
    /// client.update("users", "id123", &user).await?;
    /// ```
    pub async fn update(
        &self,
        table: &str,
        id: &str,
        data: &impl Serialize,
    ) -> SurrealResult<Option<Value>> {
        let json_data = serde_json::to_value(data).map_err(SurrealError::SerializationFailed)?;
        let sql = format!("UPDATE {table}:`{id}` MERGE $data RETURN AFTER");
        self.query(&sql)
            .bind("data", &json_data)
            .raw()
            .await
            .map(|mut r| {
                r.first_mut()
                    .map(|q| std::mem::take(&mut q.result))
                    .unwrap_or(Value::Null)
            })
            .map(Some)
    }

    /// UPSERT: 按 ID 创建或更新.
    ///
    /// ```rust,ignore
    /// client.upsert("users", "id123", &user).await?;
    /// ```
    pub async fn upsert(
        &self,
        table: &str,
        id: &str,
        data: &impl Serialize,
    ) -> SurrealResult<Value> {
        let json_data = serde_json::to_value(data).map_err(SurrealError::SerializationFailed)?;
        let sql = format!("UPSERT {table}:`{id}` CONTENT $data");
        self.query(&sql)
            .bind("data", &json_data)
            .raw()
            .await
            .map(|mut r| {
                r.first_mut()
                    .map(|q| std::mem::take(&mut q.result))
                    .unwrap_or(Value::Null)
            })
    }

    /// DELETE: 按 ID 删除.
    ///
    /// ```rust,ignore
    /// client.delete("users", "id123").await?;
    /// ```
    pub async fn delete(&self, table: &str, id: &str) -> SurrealResult<Option<Value>> {
        let sql = format!("DELETE {table}:`{id}` RETURN BEFORE");
        self.query(&sql)
            .raw()
            .await
            .map(|mut r| r.first_mut().map(|q| std::mem::take(&mut q.result)))
    }
}