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

小A检查并封装包裹,将完整包裹送过分段传送带;破损包裹被挡下,老Z与小A在断开的通道间接起新传送带。

本章导读: 源码路线第 ⑧ 站(远程层)。切到基础层的 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 验证。”

text
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:

ts
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 则这样收尾:

ts
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 组装。整个写入路径画出来是这样。”

text
对象值 ──Check──> 命中联合类型成员? ──isJsonValue──> 整体是 JSON 值?
   │                            │                      │
   │ 否(额外字段/类型错)       │ 否(环/Map/Date/class)│ 是
   ▼                            ▼                      ▼
ProtocolValidationError    ProtocolValidationError   encodeCbor ──累计超限?──> CborError → ProtocolValidationError
                                                       │ 未超限
                                                       ▼
                                                  encodeFrame ──> frame

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。