源码篇第9章 发货与报关——pi-protocol ​

本章导读: 源码路线第 ⑧ 站(远程层)。切到基础层的
pi-protocol包,读codec.ts、framing.ts和protocol.ts。这一站要拆开小A那句“对象转 JSON 丢过去不就完了”为什么行不通:字节流没有消息边界,得靠 schema、CBOR、frame 四层把它一层层兜住。
小A写了一个远程工具,第一步就是把消息发给对方。他敲下 socket.write(JSON.stringify(msg)),得意地回头:“这样不行吗?对象转成 JSON 丢过去不就完了?”
“字节流里没有‘一条消息’的边界。”老Z摇头,“对端收到的是一串字节,它怎么知道你的 JSON 在哪结束?如果消息中途被拆成两个 chunk,它又怎么知道还没收完?远程会话不能直接把 TypeScript 对象交给 socket。我们从 pi-protocol 的 schema 开始跟读,直到增量字节成为已验证的消息。”
本章不讨论传输监听器或业务命令如何执行。源码证据均来自上游 pi 标签 v1.0.0(提交 a13d35a7,packages/protocol/src/,包版本 1.0.0)。
四层链路 ​
“packages/protocol/src/codec.ts 的写入路径是:schema 验证 → CBOR 编码 → 长度帧;读取路径反过来:FrameDecoder 切出完整 payload,decodeCbor 解码,parseClientMessage 或 parseServerMessage 以 TypeBox Check 验证。”
schema → encodeCbor → 4 字节长度 frame
网络 chunk → FrameDecoder → decodeCbor → schema 校验 → 消息比喻:发货与报关
发消息像发货:先验货(schema),再装箱(CBOR),再贴长度标签(frame);收货方先看标签切包,再拆箱,最后验货。任何一步不对,本次解码或
push()不返回部分结果。先前调用已经交付的消息,协议层无法回滚;连接是否重建由上层恢复策略决定。
“protocol.ts 的严格对象禁用额外字段,PROTOCOL_VERSION 是 8。v1.0.0 的协议只定义信封,不再定义业务命令:客户端发 hello、request、cancel,服务端回 hello、hello_error、response、service_update 和 attachment。request 带一个 target,要么只有 serverId,要么再加 sessionId 和 attachmentId;真正的业务内容放在 call、result、update 里,schema 对它们只写 Type.Unknown()。codec.ts 还要求整条消息是合法 JSON 值,拒绝循环引用、非普通对象等输入,所以 CBOR 能解出来,不代表协议会接受。”
小A:“业务内容不验了?”
“协议层只保证它是 JSON 值,业务字段的含义由上层的服务自己验证。”老Z说,“上游提交 48dd1e2f 把实验性的 client/server 移植到了 pi-durable,协议因此退成一层通用 RPC 信封。这一章只读信封和字节,不读业务。”
小A追问:“四层为什么不能合成一层?schema 直接拒绝不就完了?”
“因为每一层挡的是不同类别的坏输入,合并就会留下空隙。”老Z逐层点,“schema(TypeBox Check)挡的是‘结构对但字段错’,比如 type 拼错、serverId 不是 UUID 格式;chord 的 isJsonValue 挡的是‘运行时值形状不对’,循环引用、Map/Date 这类非普通对象,TypeBox 在序列化前看不到这些;CBOR 层挡的是‘字节编码畸形’,截断的 payload、非法 UTF-8、超深嵌套;frame 层挡的是‘边界丢失’,半帧、超长声明。如果只剩 schema,一个含循环引用的对象会在 CBOR 编码时炸掉,错误发生在字节生成阶段而非验证阶段,定位困难。”
“反过来,四层也各有代价。”老Z说,“每条消息要过两次验证(写入端 parse、读取端 parse)、一次 CBOR 编解码、一次 frame 读写。但跨进程/网络的输入本来就不可信,这套代价换来的是:畸形字节绝不会变成一条被业务代码执行的消息。”
“四层也不是唯一的分法,它是在两组对立需求之间取的位置。”老Z把几种省法摆成一张表,“省任何一层,都会把某一类错误推迟到更晚的阶段才暴露,只是省下的开销不一样。”
| 替代方案 | 省下的开销 | 换来的新风险 | 失败定位 |
|---|---|---|---|
| 只留 schema | CBOR 编解码、frame 读写 | 循环引用等运行时形状错误延后到编码才暴露;字节流仍无消息边界 | 编码阶段,晚且不准 |
| schema + CBOR,无 frame | frame 前缀读写 | 对端只能“读完一条才知道结束”,半帧无法安全恢复 | 读取端,跨 chunk 不可判定 |
| schema + frame,无 CBOR | CBOR 层 | 超深嵌套、超长单串直接进 parse,解码资源可能被畸形输入耗尽 | 读取端 parse |
| 四层全留(当前) | 无 | 每条消息过两次验证、一次编解码、一次 frame 读写 | 统一 ProtocolValidationError 边界 |
“配合调用链看,每个交接点只认自己上一层的产物。”老Z又画了一张交接表,“上游给什么、下游要什么,写死在这张表里。”
| 交接点 | 输入 | 输出 | 失败形态 |
|---|---|---|---|
| 业务对象 → parse | unknown 值 | 已验证的联合类型消息 | ProtocolValidationError |
| 消息 → encodeCbor | 已验证消息 | 无长度前缀的 payload | 超限时 CborError,再被包装 |
| payload → encodeFrame | Uint8Array | 4 字节前缀 + payload | 超 uint32 或非 Uint8Array |
| chunk → FrameDecoder | 任意字节块 | 零到多个 payload | 超限、半帧、failed 状态 |
| payload → decodeCbor | payload | unknown 值 | CborError(截断、超深、非法编码) |
| unknown → parse | 解码值 | 联合类型消息 | schema/结构失败 |
先验证对象,再把它编码 ​
小A抢答:“我猜是边编码边验,一趟过?”
“不对。先验证,后编码。”老Z打开 codec.ts 的 parseClientMessage:
export function parseClientMessage(value: unknown): ClientMessage {
if (!Check(ClientMessageSchema, value) || !isJsonValue(value)) {
throw new ProtocolValidationError("Invalid client protocol message");
}
return value;
}“TypeBox Check 先验证联合类型、字段范围和 additionalProperties: false;isJsonValue 来自 @earendil-works/chord,递归接受 JSON 标量、数组和普通对象,拒绝循环引用、非普通对象和非有限数。两步不能互相替代:信封里的 call、result、update 在 schema 里是 Unknown,只有 isJsonValue 会往里检查;反过来,isJsonValue 不知道这是不是某一种 client message。”
写入端 encodeProtocolMessage 则这样收尾:
const validated = parse(value);
try {
const maxFrameLength = options?.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;
return encodeFrame(encodeCbor(validated, { maxByteLength: maxFrameLength }));
} catch (error) { /* 包装成 ProtocolValidationError */ }“先拒绝无效对象,再限制 CBOR 输出,最后追加 frame。异常会包装成 ProtocolValidationError,错误文本由 boundedErrorMessage 截断,避免对端构造超长错误污染日志。”
小A盯住 encodeCbor 那行:“frame 长度上限是配置出来的,可 CBOR 的实际输出长度要编码完才知道,超了怎么办?”
“encodeCbor 收到的 maxByteLength 按 maxFrameLength 配置,约束 CBOR payload 字节;完整 frame 还要加上 4 字节长度头。它不只查单个字符串。”老Z说,“cbor/encoder.ts 的 writer 每次扩容前都检查累计需要的字节数,超过上限就抛 CborError。所以一条由很多小字段拼成、总量超限的消息,也在生成字节时就失败。旧版本在成帧后还有一道 assertCompleteFrame 复查,v1.0.0 把它从 framing.ts 删掉了;由此可以推断,写入侧的长度契约已经完全由 CBOR writer 承担。”
小A又抓到一个细节:“错误文本截到 500 字符,栈信息不全被截掉了吗?”
“会,但这是刻意的。”老Z说,“错误文本会通过协议回传或写日志,对端是不可信的,如果它构造一条让 schema 报错的超长输入,不截断的话,错误文本本身就成了放大攻击的载体。500 字符足够定位‘哪个字段、什么类型错误’,栈信息应该在本地日志里看,不该跟着错误 envelope 走。”
小A往回翻:“isJsonValue 里那个 ancestors Set 是干嘛的?不是查循环引用的吗?”
“它是循环检测。”老Z打开 packages/chord/src/json.ts,“check 带着一个 ancestors 集合递归下钻:进入数组或对象前 add,退出时在 finally 里 delete。同一对象如果在递归栈里再次出现,ancestors.has(value) 直接判假:既挡了 a.self = a 这种直接自引用,也挡了 a.x = b; b.y = a 这种间接环。还有几行容易被忽略:原型不是 Object.prototype 或 null 的对象判假,Date、Map、Set、class 实例都过不去;带 symbol 键、带 getter 的属性判假;数字必须是有限数;数组还要求没有空洞和额外属性。值为 undefined 的属性也会判假,所以‘可选字段’只能真的缺省,不能写成 undefined。”
“写端读端走的是同一对检查,方向相反:读端多一道 CBOR 解码,写端多一道 frame 组装。整个写入路径画出来是这样。”
对象值 ──Check──> 命中联合类型成员? ──isJsonValue──> 整体是 JSON 值?
│ │ │
│ 否(额外字段/类型错) │ 否(环/Map/Date/class)│ 是
▼ ▼ ▼
ProtocolValidationError ProtocolValidationError encodeCbor ──累计超限?──> CborError → ProtocolValidationError
│ 未超限
▼
encodeFrame ──> frame本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。