OpenPencil 无传输协作内核 op-collab:确定性哈希、精确原子编辑与纯状态机设计解析
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。流程上:
- 用
ValidationBudget校验初始文档与事务的资源形状(空事务、超限、标识符超长都会拒绝); - 逐操作 apply,每个操作观察同事务中前面操作的结果;
- 任何一步失败都丢弃整个工作副本——这正是"原子精确 apply"的含义;
- 每次操作后重新校验文档不变量,最终返回新文档与
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):把一次受支持的文档编辑自动转换为确定性的协作事务。核心策略:
- 先校验 before/after 文档合法,且除
children/pages外的文档字段与页面结构未变(UnsupportedDocumentField/UnsupportedPageChange); - 构建树索引,计算新增、删除、移动节点集合与属性变更集合(diff_types.rs 定义了
EditChanges::Property | EditChanges::Structure); - 结构变更与属性变更不允许混合(
MixedPropertyAndStructure,M1 编辑矩阵的刻意收窄); - 属性编辑限定在 SupportedNodeField 白名单的 22 个字段内(如
x、y、rotation、opacity、width、layout、gap、padding、cornerRadius、fill、stroke、content、x2、y2等),替换操作带expected_hash; - 生成的
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 自带归属与单调性。这带来三点收益:
- 可审计:任何
c_<ns>_<n>ID 都能追溯到作者与序号; - 可强制:
InsertPolicy::RequireNamespace在 apply 阶段拒绝越权 ID; - 可重放: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 恰好一次确认)。在这个骨架之上,传输、身份与生产发布各自归位,协作内核本身则保持纯净、有界、可审计。