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。