使用 sd-client 连接 Spacedrive DaemonRust 客户端库的查询、执行与缩略图构建实战【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrivesd-client是 Spacedrive 仓库中面向 Rust 开发者的 daemon 客户端库负责通过 Unix socket 与 Spacedrive Core 通信并以类型安全的方式执行查询Query与动作Action同时提供媒体文件列取与缩略图 URL 构建等高频能力。读完本文你将掌握SpacedriveClient的完整 API 用法、SdPath地址模型与缩略图变体选择算法并能基于仓库内的示例程序快速搭建自己的连接代码。库定位与功能总览根据 crates/sd-client/README.mdsd-client是一个用于连接 Spacedrive daemon 的 Rust 客户端库核心特性如下Unix socket 通信通过本地 socket 与 Spacedrive Core 交互避免网络开销类型安全的查询与动作执行execute方法按query:/action:前缀区分请求类型并借助 serde 完成强类型序列化/反序列化媒体文件列取查询内置media_listing查询直接返回File领域模型列表缩略图 URL 构造根据内容 UUID、变体与格式拼接 HTTP 缩略图地址智能缩略图变体选择select_best_thumbnail依据目标尺寸自动挑选最合适的已就绪缩略图。从 crates/sd-client/Cargo.toml 可以看到该库基于tokionet、io-util、rt特性、serde/serde_json与anyhow构建并直接依赖同仓库的sd-corepath ../../core类型层面复用了 Core 的领域模型。快速开始最小可用示例创建客户端并设置库上下文SpacedriveClient::new接受两个参数daemon 的 socket 地址与 HTTP 服务基础 URL用于缩略图等资源访问。随后通过set_library设定当前库上下文use sd_client::{SpacedriveClient, SdPath}; #[tokio::main] async fn main() - anyhow::Result() { // Create client let mut client SpacedriveClient::new( /path/to/daemon.sock.into(), http://localhost:54321.into(), ); // Set library context client.set_library(library-uuid.to_string()); // Query media files let files client.media_listing( SdPath::Physical { device_id: local.to_string(), path: /Users/you/Photos.to_string(), }, Some(1000), ).await?; // Get thumbnail URLs for file in files { if let Some(content_id) file.content_identity { if let Some(thumb) client.select_best_thumbnail(file.sidecars, 256.0) { let url client.thumbnail_url( content_id.uuid, thumb.variant, thumb.format, ); println!({}: {}, file.name, url); } } } Ok(()) }需要说明的是该示例来自 README 本身其中SdPath::Physical的字段命名device_id与仓库当前实现存在差异实际定义在 core/src/domain/addressing.rs 中字段名为device_slug与path。因此可运行版本应写作SdPath::Physical { device_slug: local.to_string(), path: /Users/you/Photos.into(), }SdPath::local()便捷构造器addressing.rs会自动填入当前设备的 slug也可直接使用。运行官方示例程序仓库提供了test_connection示例通过环境变量配置连接参数并打印媒体文件及缩略图 URLexport SD_LIBRARY_IDyour-library-uuid export SD_SOCKET_PATH$HOME/.spacedrive/daemon.sock # optional export SD_HTTP_URLhttp://127.0.0.1:54321 # optional cargo run --example test_connection其中只有SD_LIBRARY_ID是必填项。从 crates/sd-client/examples/test_connection.rs 的源码可见其默认值逻辑SD_SOCKET_PATH缺省时在 macOS 上回退到$HOME/Library/Application Support/spacedrive/daemon/daemon.sockSD_HTTP_URL缺省为http://127.0.0.1:54321。示例运行时会依次打印socket / HTTP / library 连接信息media_listing查询到的文件总数以及每个文件取前 10 个的 ID、大小、内容类型、Content UUID 和全部可用缩略图 URL最后还会针对 200px 目标尺寸调用select_best_thumbnail给出推荐变体。API 详解SpacedriveClient 全方法剖析new与库上下文管理pub fn new(socket_addr: String, http_base_url: String) - Self pub fn set_library(mut self, library_id: String) pub fn get_library_id(self) - Optionstr对应实现位于 crates/sd-client/src/client.rs。library_id以OptionString存储在执行请求时会随请求体一起发送见下文execute。此外客户端还暴露了get_http_url()异步方法但目前实现返回“HTTP URL query not implemented in daemon yet”错误client.rs从源码结构看属于预留接口实际使用中直接传入的http_base_url才是生效来源。execute统一的查询与动作入口pub async fn executeI, O(self, wire_method: str, input: I) - ResultO where I: Serialize, O: serde::de::DeserializeOwned,实现client.rs的关键逻辑是根据wire_method是否以query:开头决定请求包装为{ Query: ... }还是{ Action: ... }构造QueryRequest { method, library_id, payload }其中payload由输入serde_json::to_value得到交由TcpTransport::send_request发送。因此任何 daemon 支持的 query 或 action 都可以用execute(query:xxx, input)/execute(action:xxx, input)调用media_listing只是其中一个封装好的便捷方法。传输层换行分隔 JSON 协议TcpTransportcrates/sd-client/src/transport.rs负责真实的 socket 通信使用TcpStream::connect连接 daemon将请求序列化为 JSON 后附加\n作为一条消息发送读取一行作为响应read_line因此请求与响应均为newline-delimited JSON响应解析兼容多种格式优先取json字段其次JsonOk字段遇到Error/error字段则抛出Daemon error最后兜底尝试把整段 JSON 直接反序列化为目标类型如Pong这类原始值。该设计意味着 daemon 端协议演进时客户端可通过新增字段分支保持兼容。media_listing媒体文件列取pub async fn media_listing(self, path: SdPath, limit: Optionusize) - ResultVecFile内部构造client.rs的输入结构包含以下字段字段取值说明path调用方传入起始路径SdPathinclude_descendantstrue固定递归包含子目录media_typesNone为空时默认仅含 Image Videolimit调用方传入返回数量上限sort_bydatetaken固定按拍摄时间排序请求方法为query:files.media_listing响应结构MediaListingResponse { files, has_more, total_count }最终只返回files向量。若解析失败会打印Failed to deserialize media_listing response日志。缩略图体系URL 构造与变体选择thumbnail_urlURL 拼接规则pub fn thumbnail_url(self, content_uuid: str, variant: str, format: str) - String实现client.rs生成的格式为{http_base_url}/sidecar/{library_id}/{content_uuid}/thumb/{variant}.{format}其中library_id在未设置时输出None占位符。这一点在 crates/sd-client/src/lib.rs 的单元测试中得到验证——测试断言http://localhost:54321/sidecar/None/0cc0b48f-a475-53ec-a580-bc7d47b486a9/thumb/grid1x.webp说明库上下文必须先用set_library设置否则生成的 URL 中库 ID 为None。select_best_thumbnail智能变体选择算法pub fn select_best_thumbnaila(self, sidecars: a [Sidecar], target_size: f32) - Optiona Sidecar算法client.rs步骤如下过滤出kind thumb且status ready的 sidecar解析每个变体的标称尺寸与倍率parse_variant_sizeclient.rsicon→ 128、grid→ 256、detail→ 1024其余返回Noneparse_variant_scaleclient.rs解析后缀数字如grid2x→ 2计算目标尺寸target_size 400.0时取target_size * 0.6否则取target_size避免过大缩略图浪费带宽打分|size - preferred_size| (scale - 1) * 100高倍率会被重罚每高 1 倍罚 100 分以保证渲染性能取分数最小的 sidecar 返回。这一设计意味着在 256px 网格场景下会优先选择grid1x256px无惩罚而不是grid2x256px 100 分惩罚除非确实没有 1x 变体。数据类型与领域模型sd-client通过 crates/sd-client/src/types.rs 直接再导出sd_core的领域类型File、Sidecar来自 core/src/domain/file.rsSdPath来自 core/src/domain/addressing.rsContentIdentity来自 core/src/domain/content_identity.rsImageMediaData/VideoMediaData/AudioMediaData来自 core/src/domain/media_data.rs。SdPath与位置无关的文件引用SdPath是 VDFS 地址系统的核心抽象addressing.rs共四种变体变体字段用途Physicaldevice_slug、path指向某设备上的具体路径Cloudservice、identifier、path云存储地址S3、GoogleDrive 等Contentcontent_id按内容寻址、可跨设备解析的句柄Sidecarcontent_id、kind、variant、format指向派生数据缩略图、OCR、嵌入等它还提供了display()输出local://...、content://...等统一 URI、from_uri()解析、is_local()、resolve()解析到最优物理位置等能力。SdPath::local()会自动填入当前设备 slug是构造本机路径最便捷的入口。File聚合领域模型Filecore/src/domain/file.rs聚合了 Entry、ContentIdentity、Sidecar、Tag 与媒体元数据主要字段包括id、sd_path、kind、name、extension、size、content_identity、alternate_paths重复内容的其他路径、tags、sidecars、image_media_data、video_media_data、audio_media_data以及时间戳和content_kind。它还提供了has_content_identity()、sidecars_by_kind()、ready_sidecars()、has_duplicates()、is_media()等实用方法便于客户端快速判断。Sidecar与ContentIdentitySidecarfile.rs描述派生数据字段为content_uuid、kind如thumb、variant如grid1x、format如webp、status如ready等——这正是select_best_thumbnail筛选所依赖的字段。ContentIdentitycontent_identity.rs包含uuid、kind、content_hash、integrity_hash、total_size、entry_count等是去重与内容寻址的基础。content_hash由 Core 侧基于 BLAKE3 生成小于 100KB 的文件全量哈希大文件采用 8KB 头 4 段 10KB 采样 8KB 尾部的采样哈希策略见 content_identity.rs 的常量定义。适用前提与限制sd-client依赖本仓库的sd-core类型与 daemon 协议使用前需确保 daemon 正在运行且 socket 路径可达SdPath::Physical当前字段为device_slugREADME 示例中的device_id是旧命名编译时以仓库源码为准缩略图 URL 中的库 ID 依赖set_library调用未设置时输出Noneget_http_url()尚未在 daemon 端实现HTTP 基础地址需在new时显式传入示例默认 socket 路径面向 macOS~/Library/Application Support/spacedrive/daemon/daemon.sockLinux 下建议显式设置SD_SOCKET_PATH。延伸阅读客户端实现crates/sd-client/src/client.rs、crates/sd-client/src/transport.rs、crates/sd-client/src/types.rs示例程序crates/sd-client/examples/test_connection.rs核心领域模型core/src/domain/file.rs、core/src/domain/addressing.rs、core/src/domain/content_identity.rs仓库根 READMEREADME.md【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrive创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考