surmux 0.2.0

极简 SurrealDB WebSocket 客户端 — 单连接 JSON-RPC 多路复用, 极简依赖
Documentation
//! BucketOps: SurrealDB Bucket 文件存储操作.
//!
//! 对应 SurrealDB 的 `DEFINE BUCKET` + `file::*` 函数.
//! 要求 SurrealDB 服务端启动时启用 `--allow-experimental files`.
//!
//! ## CBOR 高效传输
//!
//! 本模块利用 CBOR 协议原生 byte string (major type 2) 传输二进制文件数据:
//! - **写入**: `$cbor_bytes` 标记 → CBOR byte string → 零膨胀
//! - **读取**: `extract_query_result_bytes` → 直接从 CBOR 提取 bytes → 无需 base64 往返
//!
//! JSON 协议下 `Value::Bytes` 会变成 `[byte, byte, ...]` 整数数组 (~4x 膨胀),
//! 因此本客户端默认使用 CBOR 协议.

use serde_json::Value;
use std::time::Duration;
use tokio::sync::mpsc::UnboundedSender;

use crate::error::{SurrealError, SurrealResult};
use crate::query::{send_command, send_command_void};
use crate::router::RouterCommand;

/// Bucket 文件操作句柄.
///
/// 通过 `SurrealClient::bucket(name)` 创建.
pub struct BucketOps<'c> {
    pub(crate) request_tx: UnboundedSender<RouterCommand>,
    pub(crate) bucket_name: String,
    pub(crate) query_timeout: Duration,
    pub(crate) _phantom: std::marker::PhantomData<&'c ()>,
}

impl<'c> BucketOps<'c> {
    /// 文件指针字面量: `f"{bucket}:/{key}"`.
    /// SurrealDB v3 要求 key 以 `/` 开头, 自动补全.
    fn file_ptr(&self, path: &str) -> String {
        let key = path.strip_prefix('/').unwrap_or(path);
        format!("f\"{}:/{}\"", self.bucket_name, key)
    }

    /// 下载文件并返回原始字节.
    ///
    /// 使用 CBOR 协议直接从响应中提取 byte string, 无需 base64 编解码.
    /// 内存开销: 仅文件本身大小 (无编码膨胀).
    pub async fn get_bytes(&self, path: &str) -> SurrealResult<Vec<u8>> {
        let sql = format!("{}.get()", self.file_ptr(path));
        let result = send_command(
            &self.request_tx,
            "query",
            crate::protocol::query_params(&sql, None),
            self.query_timeout,
        )
        .await?;

        // result 是 `[{time, status, result}]` 数组, 取第一条的 result 字段
        let results: Vec<crate::protocol::SurrealQueryResult> =
            serde_json::from_value(result).map_err(SurrealError::SerializationFailed)?;
        let first = results.first().ok_or(SurrealError::NoResult)?;
        if !first.is_ok() {
            return Err(SurrealError::QueryFailed {
                code: -1,
                message: format!("Bucket get 失败: {}", first.status),
            });
        }

        // CBOR 路径下, bytes 在 codec 里已被转 base64 字符串;
        // 兜底: 整数数组 (JSON 路径).
        match &first.result {
            Value::String(b64) => {
                use base64::Engine;
                base64::engine::general_purpose::STANDARD
                    .decode(b64)
                    .map_err(|e| SurrealError::QueryFailed {
                        code: -1,
                        message: format!("base64 解码失败: {e}"),
                    })
            }
            Value::Array(_) => {
                let bytes: Vec<u8> = serde_json::from_value(first.result.clone())
                    .map_err(SurrealError::SerializationFailed)?;
                Ok(bytes)
            }
            _ => Err(SurrealError::QueryFailed {
                code: -1,
                message: "Bucket get 返回类型非预期".into(),
            }),
        }
    }

    /// 上传文件 (原始字节).
    ///
    /// 使用 `$cbor_bytes` 标记将二进制数据作为 CBOR byte string 直接传输,
    /// 避免 JSON 整数数组的 ~4x 膨胀.
    pub async fn put_bytes(&self, path: &str, data: &[u8]) -> SurrealResult<()> {
        use base64::Engine;
        let b64 = base64::engine::general_purpose::STANDARD.encode(data);

        // $cbor_bytes 标记: codec 检测到后编码为原生 CBOR byte string
        let bindings = serde_json::json!({
            "data": {"$cbor_bytes": b64}
        });

        let sql = format!("{}.put($data)", self.file_ptr(path));
        let params = crate::protocol::query_params(&sql, Some(&bindings));

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

    /// 删除文件.
    pub async fn delete(&self, path: &str) -> SurrealResult<()> {
        let sql = format!("{}.delete()", self.file_ptr(path));
        send_command_void(
            &self.request_tx,
            "query",
            crate::protocol::query_params(&sql, None),
            self.query_timeout,
        )
        .await
    }

    /// 列出 Bucket 中的文件 (支持可选前缀过滤).
    ///
    /// 返回 `Vec<Value>`, 每个元素是 `{ bucket, key }` 对象 (来自 `file::list`).
    pub async fn list(&self, prefix: Option<&str>) -> SurrealResult<Vec<Value>> {
        // list 的 prefix 必须以 `/` 开头, 自动补全
        let prefix_filter = match prefix {
            Some(p) if p.starts_with('/') => p.to_string(),
            Some(p) => format!("/{p}"),
            None => "/".to_string(),
        };
        let sql = format!(
            "file::list('{}', {{ prefix: '{}' }})",
            self.bucket_name, prefix_filter
        );

        let result = send_command(
            &self.request_tx,
            "query",
            crate::protocol::query_params(&sql, None),
            self.query_timeout,
        )
        .await?;

        let results: Vec<crate::protocol::SurrealQueryResult> =
            serde_json::from_value(result).map_err(SurrealError::SerializationFailed)?;

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

        if !first.is_ok() {
            return Err(SurrealError::QueryFailed {
                code: -1,
                message: format!("Bucket list 失败: {}", first.status),
            });
        }

        Ok(first.result.as_array().cloned().unwrap_or_default())
    }
}