From aacf0754009e841168468632d79748ebfeeab18b Mon Sep 17 00:00:00 2001 From: eust-w Date: Tue, 28 Jul 2026 17:23:15 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Define=20Rust=20sync=20client=20?= =?UTF-8?q?architecture?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../02-architecture-design.md | 3 + .../06-client-config-and-operations.md | 2 + .../07-delivery-and-acceptance-plan.md | 7 +- .../08-owner-decisions.md | 12 +- .../09-rust-implementation-design.md | 242 ++++++++++++++++++ .../object-storage-sync-uploader/README.md | 4 +- 6 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 docs/tool-assistants/object-storage-sync-uploader/09-rust-implementation-design.md diff --git a/docs/tool-assistants/object-storage-sync-uploader/02-architecture-design.md b/docs/tool-assistants/object-storage-sync-uploader/02-architecture-design.md index 5fa2d8b4..21424ad6 100644 --- a/docs/tool-assistants/object-storage-sync-uploader/02-architecture-design.md +++ b/docs/tool-assistants/object-storage-sync-uploader/02-architecture-design.md @@ -225,6 +225,7 @@ incoming/customer-a/dataset-x/camera-01/000001.mcap ### 客户端 +- 客户端使用 Rust workspace 实现; - CLI、daemon 与托盘 GUI 同期交付; - 三种入口共享同一个同步核心库; - CLI/daemon 优先提供单一静态二进制,GUI 作为薄交互壳; @@ -232,3 +233,5 @@ incoming/customer-a/dataset-x/camera-01/000001.mcap - 配置与状态分离; - 支持无管理员权限安装或便携模式; - 制品签名、SHA-256、SBOM 和版本升级通道纳入交付。 + +具体 crate 和并发边界见 [09-rust-implementation-design.md](09-rust-implementation-design.md)。 diff --git a/docs/tool-assistants/object-storage-sync-uploader/06-client-config-and-operations.md b/docs/tool-assistants/object-storage-sync-uploader/06-client-config-and-operations.md index aaf74207..29fe80ae 100644 --- a/docs/tool-assistants/object-storage-sync-uploader/06-client-config-and-operations.md +++ b/docs/tool-assistants/object-storage-sync-uploader/06-client-config-and-operations.md @@ -1,5 +1,7 @@ # 客户端配置与运维 +客户端使用 Rust 实现。CLI、daemon、托盘 GUI、本地状态和传输逻辑位于同一个 Rust workspace;GUI 是共享核心的薄交互壳。详见 [09-rust-implementation-design.md](09-rust-implementation-design.md)。 + ## 1. 建议命令 ```text diff --git a/docs/tool-assistants/object-storage-sync-uploader/07-delivery-and-acceptance-plan.md b/docs/tool-assistants/object-storage-sync-uploader/07-delivery-and-acceptance-plan.md index 14d1ce28..eb96d460 100644 --- a/docs/tool-assistants/object-storage-sync-uploader/07-delivery-and-acceptance-plan.md +++ b/docs/tool-assistants/object-storage-sync-uploader/07-delivery-and-acceptance-plan.md @@ -6,7 +6,7 @@ 输出: -- 固化已完成的 D-01~D-07 决策,并补齐 D-08; +- 固化已完成的 D-01~D-07、D-16 决策,并补齐 D-08; - 确认 BOS 对条件写、版本控制、multipart ETag 和 server-side copy 的实际语义; - 用两个并发客户端验证 lease + version check 原型; - 确认客户目标 OS、规模、网络和是否有平台外写入者; @@ -176,7 +176,10 @@ ### 代码 - Go 单元/集成测试; -- 客户端单元/集成测试; +- `cargo fmt --all -- --check`; +- `cargo clippy --workspace --all-targets -- -D warnings`; +- `cargo test --workspace` 和 Rust 客户端集成测试; +- Rust/Go protocol JSON fixture 合同测试; - race detector 覆盖 lease/并发核心; - lint、format、build; - API schema/contract test; diff --git a/docs/tool-assistants/object-storage-sync-uploader/08-owner-decisions.md b/docs/tool-assistants/object-storage-sync-uploader/08-owner-decisions.md index def27b2e..8e17b895 100644 --- a/docs/tool-assistants/object-storage-sync-uploader/08-owner-decisions.md +++ b/docs/tool-assistants/object-storage-sync-uploader/08-owner-decisions.md @@ -1,6 +1,6 @@ # 负责人决策记录与待确认清单 -> D-01~D-07 已由负责人于 2026-07-28 决定。D-08 未提供事实,保持待确认;空白不解释为“否”。 +> D-01~D-07、D-16 已于 2026-07-28 决定。D-08 未提供事实,保持待确认;空白不解释为“否”。 ## 1. 第一轮决策结果 @@ -14,6 +14,7 @@ | D-06 | A:集中权限管理 | | D-07 | B:发生冲突时自动 keep-both | | D-08 | **待确认**:BOS 直写者、版本控制和条件写事实未提供 | +| D-16 | Rust:本地助手使用 Rust;现有 Droboticflow 服务端保持 Go | ### D-01 首期同步方向 @@ -180,6 +181,15 @@ - 指定中文名; - 指定英文名和命令名。 +### D-16 实现语言 + +> **已选择 Rust。** + +- Rust 实现本地同步核心、CLI、daemon、托盘 GUI、SQLite 状态和传输。 +- 现有 Droboticflow API/控制面继续在当前 Go 服务内扩展。 +- 不在首期新建独立 Rust 服务端,避免复制 organization、role、storage connection 和审计能力。 +- 如果负责人希望“客户端和服务端全部 Rust”,需要重新决策服务拆分与迁移边界。 + ## 3. 待确认项答复模板 可直接复制填写: diff --git a/docs/tool-assistants/object-storage-sync-uploader/09-rust-implementation-design.md b/docs/tool-assistants/object-storage-sync-uploader/09-rust-implementation-design.md new file mode 100644 index 00000000..055ec9b6 --- /dev/null +++ b/docs/tool-assistants/object-storage-sync-uploader/09-rust-implementation-design.md @@ -0,0 +1,242 @@ +# Rust 实现设计 + +> 决策:本地同步助手采用 Rust。现有 Droboticflow API/控制面继续在当前 Go 服务内扩展,不在首期拆出第二套 Rust 服务。 + +## 1. 选择边界 + +Rust 覆盖: + +- 同步核心; +- CLI; +- 后台 daemon/service; +- 托盘 GUI; +- 本地 SQLite 状态; +- 文件扫描、hash、目录监听; +- direct/multipart 传输; +- session、lease、重试和 `keep-both` 客户端状态机; +- 客户端安装包和升级工具。 + +Go 继续覆盖: + +- sync space/token 管理; +- 外部 Object Sync API; +- organization/role/scope 校验; +- server-side plan、lease、fencing token; +- 预签名 URL; +- commit、version、audit; +- staging/multipart 清理和 reconcile。 + +这样保留现有控制面中的租户、权限和 storage connection 复用,同时让单独分发给客户的工具使用 Rust。 + +## 2. Rust workspace + +建议未来代码目录: + +```text +tools/drosync/ +├── Cargo.toml +├── crates/ +│ ├── drosync-core/ +│ ├── drosync-protocol/ +│ ├── drosync-state/ +│ ├── drosync-transfer/ +│ ├── drosync-platform/ +│ ├── drosync-cli/ +│ ├── drosync-daemon/ +│ └── drosync-gui/ +├── packaging/ +├── tests/ +└── README.md +``` + +### `drosync-core` + +- mapping 和 policy; +- 文件规范化与 ignore; +- 扫描、稳定文件判断和 SHA-256; +- manifest 生成; +- plan/item/session 状态机; +- 冲突决策; +- 与 UI、CLI 无关的领域错误。 + +核心不能依赖托盘窗口或命令行输出,避免三种入口产生不同语义。 + +### `drosync-protocol` + +- API DTO; +- protocol/schema version; +- 稳定错误码; +- 幂等 key; +- session/item/lease/version 类型; +- JSON 序列化合同测试。 + +服务端 Go DTO 与 Rust DTO 通过 OpenAPI/固定 fixture 做双向合同测试,不能只依赖人工保持一致。 + +### `drosync-state` + +- SQLite schema 与 migration; +- mapping、local file、session、item、multipart 和 part; +- WAL、事务和恢复; +- 单实例写入约束; +- 不保存 token、BOS AK/SK 或预签名 URL。 + +### `drosync-transfer` + +- TLS HTTP client; +- 控制面请求; +- direct PUT; +- multipart initiate/part/complete/abort; +- 并发、限速、重试和进度; +- URL 过期续签; +- commit 超时后的状态查询与幂等恢复。 + +### `drosync-platform` + +- OS 凭据库; +- 文件监听; +- 系统服务注册; +- 进程锁; +- 路径、大小写和 Unicode 平台差异; +- 系统代理、证书和诊断信息。 + +### `drosync-cli` + +- `configure/plan/sync/status/conflicts/retry/abort/doctor/version`; +- 人类可读和 `--json` 输出; +- 稳定退出码; +- 无人值守模式。 + +### `drosync-daemon` + +- 定时扫描和 watcher 纠偏; +- 断网恢复; +- mapping 调度; +- 与 GUI/CLI 的本地 IPC; +- 优雅停止和升级协调。 + +### `drosync-gui` + +- Rust 原生托盘和窗口; +- 配置、dry-run、开始/暂停、进度; +- 冲突副本与失败重试; +- 登录状态和 doctor; +- 只调用共享核心/daemon IPC,不复制同步算法。 + +## 3. 建议技术组件 + +不在 RFC 阶段固定具体版本。建议方向: + +| 能力 | Rust 组件方向 | +| --- | --- | +| async/runtime | Tokio | +| HTTP/TLS | Reqwest + rustls | +| JSON/schema | Serde | +| CLI | Clap | +| SQLite | rusqlite 或 SQLx SQLite,原型后选定一个 | +| hash | sha2 | +| 文件监听 | notify | +| 日志 | tracing | +| secret | keyring/平台凭据库适配 | +| GUI | egui/eframe + tray-icon,先验证目标 OS | +| 错误 | thiserror;应用边界可用 anyhow | + +GUI 不采用 Electron。若目标 OS 的托盘、安装器、企业签名或无障碍要求无法由当前 Rust 原生组合满足,再单独评审 GUI 框架,不改变同步核心。 + +## 4. 并发模型 + +- Tokio 管理网络、heartbeat、进度和调度。 +- 文件 hash 使用受限 blocking worker pool,不能占满 async runtime。 +- 每个 mapping 同时只有一个调度 owner。 +- 文件并发与 multipart part 并发分别限流。 +- SQLite 写入集中串行化或使用短事务。 +- 取消通过显式 cancellation token 传播。 +- GUI 关闭不取消 daemon 中的上传。 +- 进程重启后从 SQLite 和服务端状态共同恢复,不能只信任本地 `uploading` 标志。 + +## 5. 类型与安全约束 + +新类型避免混用: + +- `SessionId` +- `ItemId` +- `LeaseId` +- `FencingToken` +- `LogicalTargetKey` +- `ServerGeneratedTargetKey` +- `RemoteETag` +- `PlatformVersion` +- `Sha256Digest` +- `RelativePath` + +要求: + +- 最终 key 不接受普通 `String` 直接构造; +- 只有服务端响应能产生 `ServerGeneratedTargetKey`; +- secret 类型禁止 `Debug/Display/Serialize`; +- 字节数使用有界整数并检查转换; +- 所有路径规范化结果显式区分本地路径与远端相对路径; +- `unsafe` 默认禁止;确需使用必须集中、说明不变量并单独评审。 + +## 6. 本地 IPC + +CLI、GUI 和 daemon 同期交付时,推荐 daemon 持有 mapping 调度和 SQLite 主要写权限: + +- GUI/CLI 通过本地 IPC 查询和发命令; +- IPC 只监听本机; +- 使用当前用户权限或随机本地认证 secret; +- 命令带 request ID 和幂等语义; +- daemon 未运行时,CLI 可选择启动它或在明确的单次模式取得本地锁; +- IPC schema 同样带版本。 + +具体使用 Unix domain socket、Windows named pipe 或跨平台抽象,取决于 D-09 目标系统。 + +## 7. 构建与测试 + +基础门禁: + +```text +cargo fmt --all -- --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace +cargo test --workspace --doc +``` + +还应包括: + +- protocol JSON fixture 与 Go API 合同测试; +- SQLite migration/recovery; +- 属性测试:路径规范化、状态机和幂等 key; +- 并发竞态:同 mapping 多入口、取消、重试; +- 模糊测试:路径和 manifest 解析; +- 依赖许可证、漏洞、供应链策略; +- 目标 OS 安装、服务、托盘、凭据库与升级测试; +- 真实 BOS direct/multipart/断点恢复。 + +## 8. 制品 + +每个目标 OS/架构输出: + +- CLI/daemon; +- 托盘 GUI; +- 安装包; +- SHA-256; +- 签名信息; +- SBOM; +- license notice; +- protocol compatibility; +- 安装、升级、回滚和卸载说明。 + +具体 target triple、签名方式和安装包格式等待 D-09 确认。 + +## 9. 首个代码里程碑 + +在 D-08、D-09 和最小规模参数确认后: + +1. 创建 `tools/drosync` Rust workspace。 +2. 先实现 protocol/core/state 的可测试骨架。 +3. 用 fake API 完成 plan → staging upload → commit → keep-both 状态机。 +4. 与 Go API 建立合同 fixture。 +5. 再接真实 BOS POC。 +6. 最后接 daemon、CLI 和 GUI,三者复用同一核心。 + +当前文档决定了语言与边界,但尚未创建 Rust 代码或声称工具可运行。 diff --git a/docs/tool-assistants/object-storage-sync-uploader/README.md b/docs/tool-assistants/object-storage-sync-uploader/README.md index 66fcaad0..b7f59cac 100644 --- a/docs/tool-assistants/object-storage-sync-uploader/README.md +++ b/docs/tool-assistants/object-storage-sync-uploader/README.md @@ -1,6 +1,6 @@ # 对象存储同步上传助手 -> 状态:RFC 草案。D-01~D-07 已于 2026-07-28 决定;D-08 和第二轮实施参数仍待确认。 +> 状态:RFC 草案。D-01~D-07、D-16 已于 2026-07-28 决定;D-08 和第二轮实施参数仍待确认。 > > 暂定产品名:`Drobodata LocalSync`。名称本身也是待确认项。 @@ -32,6 +32,7 @@ | [06-client-config-and-operations.md](06-client-config-and-operations.md) | CLI、守护进程、托盘 GUI、配置、运维与故障处理 | | [07-delivery-and-acceptance-plan.md](07-delivery-and-acceptance-plan.md) | 分阶段实施、测试矩阵、验收证据与上线策略 | | [08-owner-decisions.md](08-owner-decisions.md) | 已确认的决定、待确认事实和后续答复模板 | +| [09-rust-implementation-design.md](09-rust-implementation-design.md) | Rust workspace、crate 边界、并发、GUI、构建与测试设计 | ## 3. 已确认的首期产品基线 @@ -44,6 +45,7 @@ 7. 发生远端版本或活跃写入冲突时默认自动 `keep-both`:原对象不被覆盖,冲突副本 key 由服务端生成。 8. 文件数据通过短期预签名 URL 直传 staging;控制面负责鉴权、计划、租约、提交和审计。 9. 本地用 SQLite 保存文件指纹、上传分片和上次远端版本,支持断点续传与幂等重试。 +10. 本地同步助手使用 Rust;现有 Droboticflow 服务端同步 API 继续使用 Go 扩展。 ## 4. 当前结论边界