Table of Contents

WireMessage 线格式规格

validation-program-design §4(批 5)配套件——[WireMessage]/[WireArray] 生成 codec 的 线字节面契约。字节序与黄金快照纪律的完整论述见 Layout 面《BinaryLayout 字节序与对齐规格》 (src/KernLab.Loom.Layout/docs/binary-layout-spec.md §2/§5,同样约束本面);本页只写 Wire 特有裁定。

★ 单一格式(v0.4 拍板,#128 收口):[WireMessage] 只有本页所述 tag 流格式—— 无历史双格式,Evolvable 选项不存在。未发布无兼容包袱,格式演进纪律见 §6。

§1 字节序裁定:声明点单一,全族继承

  • Wire 两生成器(WireMessage/WireArray)的全部多字节读写收口 BinaryPrimitives.{Read|Write}{Primitive}{Little|Big}Endian——端序由 [WireMessage]/ [WireArray] 的 Endianness 声明(缺省 LittleEndian),子类继承族根声明。
  • 单一端序保证跨节点互操作可推理:一个族内不混端序;需要异端序的载荷走 Layout 面 (Endianness = BigEndian)再以定长嵌套成员进入消息。
  • 因此 Wire 的跨平台主张与 Layout 相同:产物与 host 字节序解耦,三平台黄金逐字节一致。

§2 消息帧布局(WireMessage)

[0]      tag       1B    族内消息类型([WireMessageTag(n)] 显式声明,byte;发布后冻结)
[1-4]    totalLen  4B    totalLen 字段之后到报文尾的字节数(端序跟随族声明)——传输层分帧用
[5..]    field 序列       字段 tag 流(编码见下)
[末]     EOS       1B    fieldId = 0x00 结束标记——编码恒写,解码强制(缺 EOS 帧 = 畸形 Reject,#189)
  • 未知 tag → TryDecode 返回 false(向前兼容丢弃);totalLen 精确匹配(EOS 后多余字节 = false)。
  • 字段编码(tag 流内每字段——统一带 varint len,保证"未知字段按 len 跳过"对定长字段也成立):
成员形态 线字节面
定长(bool/基元/浮点/enum/标准值类型/[BinaryLayout] struct) [fieldId 1B][len varint][value 定长];标准值类型定长载荷 Guid 16B / DateTime·TimeSpan 8B / DateTimeOffset 10B / decimal 13B(#130)
string [fieldId][len varint][UTF8 载荷]——len 即 UTF8 字节数(无 4B 前缀)
blob(byte[]/ReadOnlyMemory) [fieldId][len varint][载荷]
集合(bool/基元/enum/标准值类型/[BinaryLayout] 元素) [fieldId][len varint][count 4B][逐元素定长]
集合(string/blob 元素) [fieldId][len varint][count 4B][逐元素 4B len + 载荷]
Dictionary/IReadOnlyDictionary(#131) [fieldId][len varint][count 4B][逐项 键载荷 + 值载荷]——键重复解码 Reject
两层锯齿(#133) [fieldId][len varint][count 4B][逐行 4B rowLen + 行载荷]
嵌套消息([WireMessage] 族根,#132) [fieldId][len varint][内层完整帧]——len 载荷 = 内层帧(自定界),深度上限 MaxDepth = 8 双侧执法
消息集合(#188) [fieldId][len varint][count 4B][逐项内层完整帧]——项自定界,多态 tag 判别还原具体子类
Nullable<T> 标量(#133) 有值 = 常规字段;null = 省略该 fieldId(presence 语义)
  • varint = LEB128(LE 族 1-4B 域,值 ≤ 2^28−1——超域 = 上限声明过松,编码侧 ArgumentException)。
  • 集合声明形态(T[]/List<T>/IReadOnlyList<T>/IReadOnlyCollection<T>/IList<T>/ICollection<T>/ ISet<T>/HashSet<T>/ImmutableArray<T>)不影响线格式——同为 count 前缀 + 元素序; 解码按声明形态物化。
  • 防御契约(编解码对称):截断、count/len 超 MaxCount、string 超 MaxCount(UTF8 字节)、 重复 fieldId、字典键重复、载荷消费 ≠ len、EOS 后多余字节、嵌套超 MaxDepth——解码一律 TryDecode = false(零异常);编码侧对称抛 ArgumentException。畸形报文拦截在生成物内。

§3 字段 ID 纪律(#77/#186)

  • fieldId:[WireField(Id = N)] 显式分配,缺省 = 声明序自增(首字段=1;根成员与子类成员 拼接后全族唯一——跨子类各自独立编码,同 ID 跨子类合法)。ID 永不回收——删除字段 = 该 ID 不再发送,但解码器保留"已知 ID 但忽略"槽位。
  • 合法域 1–254(0 为 EOS 保留,255 预留):显式 ID 越界 = 编译期诊断 KLSG261(此前直写 生成物出 CS0031);显式 ID 族内冲突 = 编译期诊断 KLSG260(静默重编号 = 静默改线格式,#186)。
  • 未知 fieldId:按 len 跳过(向前兼容:旧客户端读新报文);缺已知 fieldId:字段 = 缺省值 (值类型 default、引用类型/string/集合 = null)——向后兼容。可空变长成员 null = 省略该字段 tag。

§4 API 面(生成 <族名>Codec 静态类)

API 用途
Encode(message) 编码为新数组
Encode(IBufferWriter<byte>, message) 零拷贝直写(PipeWriter 汇)
EncodePooled(message, out rented) ArrayPool 租借(返回写入长度;异常自动归还租约)
ComputeLength(message) 精确线长(含 tag/totalLen/EOS——与实际产物一致)
EncodeInto(Span, message) 就地编码
TryGetFrameLength(ReadOnlySpan, out frameLength) 分帧探测:frameLength = 5 + totalLen;缓冲不足 5B = false;totalLen 越界 = false(MaxFrameLength = 64MB,不可信输入防御,#190)
TryDecode(ReadOnlySpan, out message) 单帧解码(totalLen 精确匹配;ROM 成员 ToArray)
TryDecodeFromMemory(ReadOnlyMemory, out message) 全族生成:ROM blob 成员 __mem.Slice 零拷贝(与源共享底层缓冲)、嵌套消息经内层 TryDecodeFromMemory 透传(#187);byte[] 成员保持拷贝(所有权语义)

§5 数组布局(WireArray)

[前缀字段声明序(定长/嵌套同 §2)][4B 元素数(端序跟随声明)][逐元素]

独立数组 codec([WireArray] struct)元素支持基元整型与 [BinaryLayout] struct (变长 string 请用 [WireMessage] 字段——[WireArray] 的定长前缀布局不承载); 嵌套元素的 {Element}Codec 由 BinaryLayoutGenerator 生成——消费方必须同时引用 Layout 生成器 (单接 Wire 生成器时嵌套形态编译失败,源码级 golden 只比文本不编译、不暴露此依赖)。

§6 演进规则(发布纪律)

操作 规则
加字段 新 ID(>当前最大),旧客户端跳过、新客户端读旧报文 = 缺省值 ✅
删字段 ID 保留不再发;解码器留忽略槽位 ✅(旧报文含该 ID 时跳过)
改字段类型 ❌ 禁止(破坏线格式,ID 语义变更)——换新 ID 新字段
重排/重命名字段 ✅ 线格式不受影响(ID 不变)——以显式 [WireField(Id)] 为前提(声明序自增的 ID 重排即变)
改集合元素类型 ❌ 禁止(同改类型)
改 MaxCount ⚠️ 收紧会拒收旧报文(解码侧按新上限)——放宽安全;收紧需同步升级

§7 null / MaxCount 语义(#78 对称)

  • 可空变长成员(? 标注):null = 不发该字段 tag(解码 = 缺省值),天然可选。
  • 非可空变长成员:null → Encode 抛 ArgumentException(明确异常,非 NRE)。
  • 编码侧集合/string/blob 超 MaxCount 同抛——与解码 Reject 防御对称(修"自产自解 false")。
  • Nullable<T> 标量:null = 省略字段(§2 表 presence 语义)。

§8 黄金快照

消息族(8 成员形态 + 扩展类型 string/enum/float/double/集合形态 + 空子类)与数组两形态的运行时 逐字节 golden 在 tests/KernLab.Loom.Wire.Tests/Golden/Bytes/*.hex;Encode↔TryDecode 幂等闭环、 畸形拦截(含 string 超 MaxCount)、ComputeLength == 产物长度 一并入测。纪律同 Layout 规格 §5。