CubSync 0.1.0

中文

CubSync 0.1.0 是第一个能跑通的最小切片：自己的局域网协议、同步引擎、两个后端，以及一个命令行。

能做什么

• 自有协议：24 字节帧走两条 TCP，命令与文件数据分开，大文件传输不会卡住元数据；能力位协商，对端不认识的命令按名字回应而不是让流错位。
• 同步引擎：双向 / 镜像 / 仅更新；按时间+大小、按内容哈希或只看大小比较；过滤器支持逐对覆盖；快照区分「被删除」与「新文件」；冲突策略可选；一对失败不影响其它对。
• 断点续传：写入先落到目标旁的 .cubtmp，中断后从已确认的位置继续。提交顺序是数据 → 原子改名 → 时间戳。
• 删除可恢复：默认策略把文件移进它所属根目录下的 .cub_trash，而不是直接 unlink。
• 后端 SPI：引擎只认接口，从不认协议。今天是本地文件系统与局域网；WebDAV、SMB、SFTP、FTP 是「加一个」而不是「改一处」。

实测，不是说说
两个 JVM 进程走真实协议在回环上传输 1 GiB：MD5 一致、约 150 MiB/s（含校验）、无暂存残留、二次运行 0 个操作、0 字节。

193 项测试覆盖协议编解码与畸形输入、过滤器语法、比较与计划矩阵、分块乱序、配置编解码、两个后端对真实 socket 与真实文件，以及引擎驱动一个与本地后端不共享任何代码的内存后端。

已知限制

• 没有界面，也没有安卓或桌面构建。
• SyncDirection.CUSTOM 未实现；规划阶段直接拒绝，而不是猜。
• 没有定时，还不能无人值守运行。
• 一个会话一条数据连接；多链路聚合未实现。
• 协议未加密、未鉴权：在鉴权设计出来之前，只适用于可信网络。不要把 serve 的端口开到公网上。

升级
没有可升级的来源，这是第一个版本。

---

CubSync 0.1.0

The first working slice: the protocol the project owns, the synchronisation engine,
two backends and a command line interface.

Nothing here is stable yet — the wire format and the engine's public API can still
change between minor versions. See docs/VERSIONING.md for what that means in
practice.

What works

cubsync serve --root /srv/photos --port 43817 --name nas
cubsync ls nas.local:43817
cubsync push --to nas.local:43817 --remote /srv/photos --from ./photos \
             --direction mirror-to --compare hash --parallel 4

• Its own LAN protocol — 24-byte frames over two TCP connections, commands on
  one and file payloads on the other, so a large transfer cannot stall the
  metadata. Capability bits are negotiated; a command a peer does not implement is
  answered by name instead of desynchronising the stream.
• A synchronisation engine — two-way, mirror and update-only directions,
  timestamp/size, content-hash or size-only comparison, filters with per-pair
  overrides, per-pair snapshots so a deletion is told apart from a new file,
  conflict policies, and a failure in one pair does not stop the others.
• Resume — a write stages into a deterministic .cubtmp file next to the
  target, and the next attempt continues from where it stopped. The commit order is
  data, then atomic rename, then timestamp.
• Recoverable deletions — the default policy moves a file into .cub_trash
  inside the root it came from rather than unlinking it.
• A backend SPI — the engine talks to an interface, never to a protocol. Local
  filesystem and LAN today; WebDAV, SMB, SFTP and FTP are additions rather than
  changes.

Measured, not claimed

One gibibyte between two JVM processes over the real protocol, on loopback:

sender   md5=b6fe82679bf3e9ab2127afd0efb5039e
receiver md5=b6fe82679bf3e9ab2127afd0efb5039e
MD5 MATCH
engine time 6819 ms       (~150 MiB/s including the verification pass)
staging leftovers 0
second run: 0 copied, 0 B, 0 deleted

193 tests cover the protocol codec and its malformed inputs, the filter dialect,
the comparison and planning matrices, chunk reordering, configuration codecs, both
backends against real sockets and real files, and the engine driving an in-memory
backend that shares no code with the local one.

Known limitations

• No GUI, and no Android or desktop build. The engine is platform-neutral and the
  modules are laid out for it, but only the JVM target exists.
• SyncDirection.CUSTOM is not implemented; planning refuses it rather than
  guessing.
• No scheduling, so nothing runs unattended yet.
• One data connection per session: parallel transfers share one TCP stream, and
  multi-channel aggregation is not implemented.
• The protocol is unencrypted and unauthenticated. It is intended for a trusted
  network until authentication is designed. Do not expose a serve port to the
  internet.

Upgrading

Nothing to upgrade from. This is the first release.