OpenPencil 无传输协作内核 op-collab:确定性哈希、精确原子编辑与纯状态机设计解析

原创2026-10-11 17:14:211,736 阅读

OpenPencil 无传输协作内核 op-collab:确定性哈希、精确原子编辑与纯状态机设计解析

op-collab 是 OpenPencil 的"无传输协作基础库"(transport-free collaboration foundation):它拥有版本化的 wire 数据传输对象(DTO)、确定性文档哈希,以及针对标准 PenDocument 模式的精确原子操作。本指南将围绕 op-collab 的 README 展开,结合源码剖析其协议、哈希、apply、diff 与 owner/guest 双状态机的设计与实现,帮助你理解一个"把信任边界画在传输层之外"的协作内核是如何被构造出来的,并掌握它的消息模型、限制参数与集成方式。

一、设计动机:为什么需要一个"无传输"协作内核

多人在线设计工具通常把网络、加密、票据与文档编辑耦合在同一个服务里,导致协议、身份和编辑逻辑难以独立演进。op-collab 的定位恰恰相反:这个 crate 刻意不包含任何 socket、async 运行时、票据解析器、签名验证器或密钥材料。它只负责协作语义本身,把网络与身份交给宿主(native host)去提供。

从 lib.rs 的模块声明 可以看出其职责边界:

  • protocol、codec、frame_direction:版本化 wire 数据与有界校验;
  • hash:规范哈希(canonical hashing);
  • snapshot:快照验证;
  • apply、apply_context、apply_budget、apply_tree:原子精确 apply;
  • diff、diff_fields、diff_index、diff_structure:支持编辑的差异计算;
  • session、guest、session_state、session_submit、session_sync、session_roster、session_undo、undo_ledger:纯 owner/guest 会话状态机;
  • id_high_water、profile_validation、ticket_json、typed_images、serde_context、finite:配套的验证与安全工具。

该 crate 被设计为平台中立、可以安全地进入 wasm 依赖图(Cargo.toml 的依赖仅包括 jian-ops-schema、op-util、serde、serde_json、blake3、thiserror 与 zeroize),这正是它能同时服务于桌面宿主与浏览器宿主的前提。

二、信任边界:宿主负责什么,内核负责什么

协作会话的身份信任全部来自宿主注入的已验证身份元数据。内核不解析票据、不校验签名,只消费宿主跨过协作边界传入的结果。这在 protocol.rs 中体现为两个关键类型:

  • VerifiedAuthMetadata:仅包含 issuer、subject、device_id、proof_binding、expires_at_unix_ms 以及可选的 display_name / avatar_url。注意它没有 serde 实现,Debug 对 subject、device、binding 一律输出 [REDACTED]——身份元数据永远不能由 wire 上的帧自证。
  • ConnectionPrincipal:由 from_verified 构造,把已认证元数据绑定到 participant_id、peer_id 和 role,同样刻意不实现 serde——入站帧无法自我声称 subject、设备、参与者 ID 或角色。它的 Debug 同样对所有敏感字段脱敏。

相应地,owner 在 OwnerSessionCore::new 中只接受 AdmissionGrant(ConnectionPrincipal + PeerNamespace),guest 只接受经过验证的 Welcome。ticket 的解析、签名验证、密钥轮换与信道绑定都留在开放的宿主认证桥接层(op-auth-bridge)中,公开仓库只保留签发方/提供方的私密凭据需求作为独立部署要求。

三、版本化 wire 协议:FrameEnvelope 与 CollabMessage

所有协作消息都装在一个统一信封里。FrameEnvelope(protocol.rs)携带三个字段:

  • protocol_version: u16——当前为 COLLAB_PROTOCOL_VERSION = 1;
  • session_id: SessionId——共享的会话标识;
  • epoch: Epoch——u64 递增纪元,用于隔离"替换纪元"(replacement-epoch quarantine);
  • body: CollabMessage——消息体。

CollabMessage 是一个带标签枚举(type + payload,snake_case),覆盖 14 种消息:Welcome、Submit、Commit、Reject、CatchUp、Snapshot、Applied、RenewTicket、UndoRequest、UndoResult、PresenceUpdate、PresenceChanged、ParticipantJoined、ParticipantLeft、Bye。值得注意的是:

  • CollabMessage::try_clone_non_sensitive 会显式拒绝克隆 RenewTicket(携带凭证),把"意外扇出续期票据"变成编译期错误;
  • 每个消息的 kind() 返回固定字符串,供方向校验与日志使用。

方向强制(direction enforcement) 由 frame_direction.rs 实现:message_direction 把每种消息归类为 GuestToOwner、OwnerToGuest 或 Bidirectional。owner 与 guest 的 accept_frame 入口都会先做方向校验(WrongDirection 错误),未认证的入站方向由 InboundFrameDirection::from_remote_role 从已认证的远端角色推导,绝不使用攻击者声明的 wire 字段。

四、确定性规范哈希:BLAKE3 + 域分离

协作的"精确性"建立在 hash.rs 提供的规范哈希之上:

  • 算法冻结为 CANONICAL_HASH_ALGORITHM = "blake3",版本 CANONICAL_HASH_VERSION = 1;
  • 三个域分离前缀(domain prefix)分别用于完整文档、节点/子树、协作事务:
    • DOCUMENT_HASH_DOMAIN = "openpencil-collab/document/v1"
    • NODE_HASH_DOMAIN = "openpencil-collab/node/v1"
    • TXN_HASH_DOMAIN = "openpencil-collab/txn/v1"
  • 哈希流程:先 validate_finite(拒绝 NaN/Infinity),再做 typed_canonical_value(隔离图片字段内联),最后 write_canonical_value 输出对象键按字典序排序、数组保持作者顺序、无空白的规范 JSON,交给 BLAKE3 以 domain || 0x00 || encoded 形式计算,得到 32 字节的 CanonicalHash(十六进制 64 字符,FromStr 只接受小写 hex)。

三个入口函数分别为 canonical_document_hash、canonical_node_hash 与 canonical_txn_hash,并且都会先拒绝携带外部图片引用的内容(ExternalImageReference)——确保哈希结果在所有端点上可复现。

五、精确原子编辑:四种 Exact 操作与命名空间 ID 语法

5.1 操作类型

协作事务(CollabTxn)由一组 CollabOp 组成,共四种(protocol.rs),每种都携带"期望值"以便做精确匹配:

操作 关键字段 语义
InsertExact page、parent_id、index、node 在指定父节点下、指定索引处插入整棵子树
ReplaceExact page、node_id、expected_hash、node 仅当现节点哈希等于 expected_hash 时整体替换
DeleteExact page、node_id、expected_hash 仅当现节点哈希匹配时删除子树
MoveExact page、node_id、expected_parent、expected_index、new_parent、new_index 校验当前位置后移动子树

PageRef 是 DocumentRoot | PageId(String),deny_unknown_fields 保证反序列化时多余字段直接失败。

5.2 原子 apply

apply.rs 提供 apply_txn(返回克隆文档)、apply_txn_tracked(额外返回命名空间计数器)与 apply_txn_in_place。流程上:

  1. 用 ValidationBudget 校验初始文档与事务的资源形状(空事务、超限、标识符超长都会拒绝);
  2. 逐操作 apply,每个操作观察同事务中前面操作的结果;
  3. 任何一步失败都丢弃整个工作副本——这正是"原子精确 apply"的含义;
  4. 每次操作后重新校验文档不变量,最终返回新文档与 next_id_counter。

replace_exact 会校验 expected_hash 与当前节点的 canonical_node_hash 完全一致(HashMismatch),并拒绝替换后节点 ID 变化(ReplacementIdChanged);move_exact 会拒绝把节点移入自己的子树(MoveWouldCycle)。

5.3 命名空间 ID 语法与高水位计数器

协作文档中的 ID 并非自由生成,而是遵循共享语法 c_<namespace>_<counter>,定义在 op-util 的 collab_id.rs:

  • PeerNamespace:仅允许 ASCII 字母、数字与 -,最长 64 字节(MAX_PEER_NAMESPACE_LEN);
  • NamespacedId:c_ 前缀 + 命名空间 + _ + 无前导零的十进制 u64 计数器;
  • 解析器拒绝空命名空间、非法字符、非规范计数器(如 c_peer_00、c_peer_01、负数、超 u64)。

在会话内,ApplyContext::for_peer_namespace_at 设置 InsertPolicy::RequireNamespace { namespace, next_counter },新作者 ID 必须属于本 peer 命名空间且推进保留的单调计数器;越界、落后或耗尽都会映射为 PermissionDenied 类拒绝。测试 collab_id.rs 内的单元测试 覆盖了语法边界与全部非法形式。

六、支持编辑的 diff:从"作者意图"到"精确事务"

直接手写 CollabOp 很容易出错,因此内核提供 diff.rs 的 diff_supported(before, after, context):把一次受支持的文档编辑自动转换为确定性的协作事务。核心策略:

  1. 先校验 before/after 文档合法,且除 children/pages 外的文档字段与页面结构未变(UnsupportedDocumentField / UnsupportedPageChange);
  2. 构建树索引,计算新增、删除、移动节点集合与属性变更集合(diff_types.rs 定义了 EditChanges::Property | EditChanges::Structure);
  3. 结构变更与属性变更不允许混合(MixedPropertyAndStructure,M1 编辑矩阵的刻意收窄);
  4. 属性编辑限定在 SupportedNodeField 白名单的 22 个字段内(如 x、y、rotation、opacity、width、layout、gap、padding、cornerRadius、fill、stroke、content、x2、y2 等),替换操作带 expected_hash;
  5. 生成的 CollabTxn 会从 before 以 peer 命名空间策略重放一遍,并强制要求重放结果与 after 的规范文档哈希一致(ReplayHashMismatch),否则不返回事务——即"生成的 txn 必须精确复现作者意图"。

七、Owner 会话核心:两阶段安装契约与有界状态

OwnerSessionCore(session.rs)是纯 owner 侧的排序与名册状态机:

  • 两阶段 document-install 契约:一次成功的 Submit 首先产出 OwnerEffect::PrepareInstall(PreparedCommit);全局序号、commit-log、去重状态只在宿主确认安装之后通过 finalize_install 推进。PreparedCommit 刻意不实现 Clone,宿主要么 abort_prepare 要么恰好确认一次安装(InstalledHashMismatch 会使会话直接 ended)。
  • 方向与身份强制:accept_frame 校验 session/epoch 匹配、方向合法,ClientOpPeerMismatch 保证 client op id 的 peer 与活动连接一致;任何错误对该输入连接都是致命的,内核立即标记 closing。
  • 去重与结果窗口:session_submit.rs 的 handle_submit 用 classify_counter 把计数器分为 Retained/Expired/Gap/Current:重放的 Submit 若事务哈希一致则直接回放缓存结果(ReplyCommit/Reject),过期拒绝 ExpiredClientOpId,出现空洞拒绝 CounterGap 并关闭连接(协议错误)。
  • CatchUp 与 commit-log:session_sync.rs 的 handle_catch_up 优先从有界 commit-log 回放遗漏的 Commit 批次,若日志已被裁剪则退化为直接下发 Snapshot;Applied 确认会推进该 peer 的 applied_through 并据此裁剪 commit-log(所有远端都确认过的前缀可释放)。
  • 选择性撤销(selective undo):owner 维护 undo_ledger,可针对某个已提交的属性编辑生成补偿 Commit,UndoCommitted 效果先向请求者回结果再广播补偿提交。

八、Guest 会话核心:确认态 + 待定态重建与断线重连

GuestSessionCore(guest.rs)维护 guest 侧的确认/待定协作状态:

  • 状态机:AwaitingSnapshot → Active → Disconnected / Ended。document_mutation_allowed() 只有在 Active、非 Viewer、无 pending 编辑/撤销/安装且计数器未耗尽时才为真。
  • confirmed + pending 双文档模型:confirmed_document 是权威已确认文档,pending 记录一条乐观本地编辑(PendingEdit:before/desired 文档、提交的 txn、变更集、状态、延迟的拒绝)。当自己的乐观编辑输给权威历史时,产出 PendingCancelled 效果,并携带被丢弃的本地意图 changes,供宿主暂存给用户驱动重放——而不是静默丢失。
  • 重连重放:resume 只在 session/epoch 与自身绑定完全一致时允许同纪元恢复;恢复后若有未确认的 pending 提交,通过 replay_pending_submit_after_resume 以精确相同的 client_op_id 重发 Submit(owner 端靠去重窗口幂等处理)。纪元不同则内核直接 Ended,防止待定编辑泄漏进替代会话。
  • 安装契约对称:Snapshot、远端/自己的 Commit、撤销补偿、拒绝回滚都会触发 PreparedGuestInstall(GuestInstallReason 五类),宿主同步安装后用 finalize_install 以实际哈希确认;InstalledHashMismatch 同样使会话终结。

九、资源限制:从 wire 到会话的层层有界

协作系统的攻击面来自无界输入,op-collab 的每层都配了上限常量(protocol.rs、session_types.rs、guest_types.rs):

Wire 层(WireLimits,随 Welcome 下发并在编解码时校验):

参数 默认值 含义
max_envelope_bytes 64 MiB 单帧上限(owner→guest Snapshot 需要大信封)
max_txn_bytes 4 MiB 单事务 JSON 编码上限
max_ops_per_txn 1 024 事务内操作数
max_processed_subtree_nodes_per_op 4 096 单操作可处理的子树节点数
max_document_nodes 100 000 文档节点总数
max_tree_depth 16 保守的树深度(PenNode 反序列化器是递归的)
max_identifier_bytes 1 024 各类 ID 字节上限
max_presence_bytes 64 KiB presence 编码上限
max_validation_node_visits_per_txn 2 000 000 单事务验证访问预算

方向化的入站上限:guest_to_owner_envelope_limit(frame_direction.rs)说明了一个精妙的安全细节——max_envelope_bytes 之所以是 64 MiB,是因为 owner→guest 的 Snapshot 携带整个文档;如果双向共用这个上限,一个已入场的 guest 就能迫使 owner 为每一帧解析 64 MiB 的 serde_json::Value。因此 guest→owner 方向的上限由 max_txn_bytes 与 max_presence_bytes 推导(加上有界的结构/标识符余量),且该上限来自已认证的本地连接方向,而非帧内容。

会话层(SessionLimits):max_participants(默认 16、上限 64)、每 peer 结果窗口(默认 128 条 / 8 MiB,上限 4 096 条 / 64 MiB)、commit-log(默认 64 条 / 64 MiB,上限 4 096 条 / 256 MiB)、undo ledger(默认 512 条 / 64 MiB,上限 4 096 条 / 256 MiB),且结果窗口有全局 256 MiB 的总量约束。

Guest 层(GuestSessionConfig):commit 缓冲默认 64 条 / 64 MiB,undo 索引默认 256 条。validate_config 会拒绝 0 或超上限的配置(错误信息精确给出字段、实际值与合法区间)。

凭证专属编解码:携带 OpaqueTicket 的 RenewTicket 帧不走通用 JSON 树——codec.rs 用 encode_renew_ticket_frame_to_zeroizing_json 直接序列化进 Zeroizing 存储,ticket_json.rs 用 RawValue 借用解码、手写转义与代理对处理,避免任何普通 scratch buffer 接触票据明文;OpaqueTicket 的 PartialEq 也手写成常数时间比较,避免把 == 变成计时侧信道。

十、协作 ID 语法与"共享 grammar"的价值

README 特别提到"shared collaboration-id grammar"由本 crate 拥有。它在 op-util 的 collab_id.rs 中落地,让所有开源调用方共用同一个解析器与格式化器:owner 负责为每个入场 peer 分配唯一、不可预测的命名空间,NamespacedId 则让文档 ID 自带归属与单调性。这带来三点收益:

  1. 可审计:任何 c_<ns>_<n> ID 都能追溯到作者与序号;
  2. 可强制:InsertPolicy::RequireNamespace 在 apply 阶段拒绝越权 ID;
  3. 可重放:guest 重连后用同一 client_op_id 重发,owner 依赖 ID 去重。

十一、集成边界:它与哪些 crate 分工

README 明确了整套协作能力的拼图:

  • op-collab-transport:native 传输(TCP、mDNS 发现、Noise、密钥存储等),负责把已认证帧送进 op-collab;
  • op-editor-host-core 与 op-host-desktop:编辑器/桌面宿主集成,执行"宿主安装文档"这一侧;
  • op-auth-bridge:公开的票据验证/签发桥接;
  • 私有生产组件:README 明确声明,仅靠上述开源组件并不能构成完整的生产会话——私有的生产票据签发方/提供方,以及真实平台/双机发布验证,仍然是独立需求。

换句话说:op-collab 提供"大脑"(协议、哈希、状态机),传输与身份是它的"感官",而生产级发行还需要仓库之外的一环。

十二、测试与可靠性证据

仓库为该内核提供了扎实的测试支撑:

  • tests/session.rs 以 owner/editor/viewer 三角色的完整会话为背景,覆盖 OwnerSessionCore::new、activate_peer、Submit 提交流程等端到端行为;
  • 单元测试(如 session.rs 内的 final_client_counter_commits_once_then_enters_exhausted_state)验证计数器耗尽后的精确一次提交语义与重放幂等;
  • collab_id.rs 单元测试 覆盖命名空间语法边界与非法 ID 全集;
  • 其余模块(codec_properties、hash、apply、protocol、session_admission、undo_owner、undo_guest、simulation、guest、diff 等,见 crates/op-collab/tests)分别验证编解码属性、哈希、精确 apply、协议校验、准入、选择性撤销与故障模拟。

这些测试既验证了"精确性"(哈希、expected_hash、重放一致),也验证了"有界性"(资源上限、方向上限、计数器单调)。

总结

op-collab 用一个刻意"无传输"的纯 Rust 内核,把 OpenPencil 多人在线设计协作的核心难点——版本化 wire 数据、确定性规范哈希、精确原子编辑、共享 ID 语法、owner/guest 纯状态机——一次性收拢到可测试、可复用、可进入 wasm 依赖图的边界之内。理解它的关键,是记住两条红线:信任只能由宿主注入(VerifiedAuthMetadata / ConnectionPrincipal 不可自证),状态只能通过两阶段安装契约推进(PreparedCommit / PreparedGuestInstall 恰好一次确认)。在这个骨架之上,传输、身份与生产发布各自归位,协作内核本身则保持纯净、有界、可审计。

登录后查看全文
openpencil