TT Lab
博客 开始
学习 学习路径 课程

改了字段编号,旧客户端悄悄读出了错误的值

亲手读写字节

在 TT Lab 中继续学习

目标

在既没有 protoc 也没有 protobuf 包的 Pod 里,只用 Python 标准库,亲手构建 protobuf wire format 的编码器和解码器。按 varint → tag → 有符号整数 → 字段 → 消息的顺序一层层搭起来,最后解码子消息和 packed repeated。 做出来的工具在下一个实验中还会用到。

为什么重要

gRPC 故障有一半是因为不知道“字节里没有名称”这件事。wire 上只携带字段编号和 wire type,名称和声明类型是由读取方的 .proto 补上的。亲手编码一遍,就能通过计算看出: 为什么不能改编号,为什么 int32 的负数要占 10 个字节, 为什么旧客户端能毫无错误地跳过新字段。亲手打开过库所隐藏的东西的人, 在 schema 评审时看到的是不一样的东西。

步骤

  1. 创建 /root/grpc/pb.py,实现 encode_varint(n) -> bytes 和 decode_varint(data, pos=0) -> (value, next_pos)。把 1、150、300、16384 编码后的十六进制,以 <value>=<hex>的格式逐行写入 /root/grpc/01-varint.txt。
  2. 加入 encode_tag(field, wire_type) -> bytes 和 decode_tag(data, pos=0) -> (field, wire_type, next_pos)。把 1:0、2:2、3:2、16:0 这四个 tag 的十六进制,以 <field>:<wire_type>=<hex>的格式写入 /root/grpc/02-tag.txt。
  3. 加入 zigzag_encode(n) -> int 和 zigzag_decode(u) -> int,实际编码 int32 -1、sint32 -1、int32 -150、sint32 -150,并以 <type> <value> = <hex> (<N> bytes)的格式写入 /root/grpc/03-signed.txt。int32 把 64 位补码作为 varint 发送,sint32 则把经过 ZigZag 的值作为 varint 发送。
  4. 加入 encode_field(field, kind, value) -> bytes。kind 为 int32 int64 uint32 uint64 sint32 sint64 bool string bytes。编写 /root/grpc/04-make.py,用这个函数生成 id(1)=4242, qty(2)=17, note(3)="한글 메모"(韩文,意为“韩文备注”)的订单,运行后留下 /root/grpc/04-order.bin。
  5. 加入 decode_message(data) -> [(field, wire_type, raw), ...]。VARINT 是 int,LEN 是 bytes,I32/I64 是原样的 4 字节、8 字节 bytes。解码 /opt/app/grpc/order_v1.bin,以 field=N wire=W value=V 的格式逐行写入 /root/grpc/05-decode.txt(LEN 的值用十六进制)。
  6. 加入 encode_records(records) -> bytes(decode_message 的逆函数)。解码 /opt/app/grpc/order_v2.bin,对每条记录判断它的编号是否为 v1 schema(/opt/app/grpc/order_v1.proto)所认识的,并以 field=N wire=W known 或 unknown 的格式写入 /root/grpc/06-unknown.txt。
  7. /opt/app/grpc/nested.bin 的字段 6 是 Customer 子消息。用 decode_message 把它的载荷再解码一遍,并在 /root/grpc/07-nested.txt 中写三行:customer.bytes=<hex>、customer.name=<name>、customer.tier=<number>。
  8. 加入 decode_packed_varints(raw) -> [int, ...],解开 /opt/app/grpc/packed.bin 的字段 7(packed repeated int32),并在 /root/grpc/08-packed.txt 中写三行:tags=<comma-list>、packed_record=<hex>、expanded_record=<hex>。

参考

构建并读取 varint

在 /root/grpc/pb.py 中实现 encode_varint(n) 和 decode_varint(data, pos=0),并把 1、150、300、16384 的十六进制,以 <value>=<hex>的格式写入 /root/grpc/01-varint.txt。

方向:把整数每 7 位切成一段,从低位开始输出;如果后面还有,就把该字节的最高位(0x80)置 1。读取时,在这一位为 0 的字节处停止。

工具:位运算 & 0x7F、>>= 7、| 0x80,以及一个同时返回读取位置的循环。

具体:150 的二进制是 10010110 → 在低 7 位上加上“后面还有”标记得到 0x96,剩下的 1 是 0x01,所以是 96 01(300 是 ac02)。decode_varint 必须从 pos 开始读取并返回 (value, next_pos)(值与下一个位置)——评分器也会从中间位置调用它。

让 tag 携带编号和 wire type

在 /root/grpc/pb.py 中加入 encode_tag(field, wire_type) 和 decode_tag(data, pos=0),并把 1:0、2:2、3:2、16:0 的十六进制,以 <field>:<wire_type>=<hex>的格式写入 /root/grpc/02-tag.txt。

方向:tag 也是一个 varint——把字段编号和 wire type 装进一个整数。

工具:(field << 3) | wire_type 及其逆运算(低 3 位用 & 0x7,其余用 >> 3),以及第 1 步的 encode_varint 和 decode_varint。

具体:1:0 是 8,所以是 08;2:2 是 18,所以是 12。编号 1–15 的 tag 占一个字节,从 16 开始占两个字节——“给常用字段分配小编号”的建议就来源于此。

负的 int32 是 10 个字节,sint32 是一两个字节

加入 zigzag_encode(n) 和 zigzag_decode(u),实际编码 int32 -1、sint32 -1、int32 -150、sint32 -150,并以 <type> <value> = <hex> (<N> bytes)的格式写入 /root/grpc/03-signed.txt。

方向:同样的 -1,用 int32 是 10 个字节,用 sint32 是 1 个字节。前者把 64 位补码作为 varint 发送,后者把经过 ZigZag 的值作为 varint 发送。

工具:64 位掩码 n & 0xFFFFFFFFFFFFFFFF、文档中的 ZigZag 公式 (n << 1) ^ (n >> 31) 和还原公式 (u >> 1) ^ -(u & 1)(Python 的 >> 是算术移位)。

具体:ZigZag 交替映射为 0→0、-1→1、1→2、-2→3。行格式像 sint32 -1 = 01 (1 bytes) 这样,同时写出十六进制和字节数。

把一个字段做成记录

加入 encode_field(field, kind, value)(kind:int32 int64 uint32 uint64 sint32 sint64 bool string bytes)。在 /root/grpc/04-make.py 中用这个函数,把 id(1)=4242, qty(2)=17, note(3)="한글 메모"(韩文,意为“韩文备注”)接在一起,保存为 /root/grpc/04-order.bin。

方向:记录就是 tag + 值,消息只是把记录接在一起(既没有头部,也没有分隔符)。

工具:第 2 步的 encode_tag、第 1 步的 encode_varint、第 3 步的掩码和 ZigZag(64 位用 n >> 63),字符串用 .encode("utf-8")。

具体:数字类的 wire type 是 0,string 和 bytes 是 2,而 2 会在值前面加上一个长度 varint。长度不是字符数,而是 UTF-8 字节数——"한글 메모" 虽然是 5 个字符,按 UTF-8 却有 13 个字节(这个字符串不翻译)。

把字节还原成记录列表

加入 decode_message(data),使其返回 [(field, wire_type, raw), ...]。解码 /opt/app/grpc/order_v1.bin,并以 field=N wire=W value=V 的格式写入 /root/grpc/05-decode.txt(LEN 的值用十六进制)。

方向:一直循环到结尾——读出 tag,再按 wire type 指示的长度读出值。这一步既不知道名称,也不知道声明类型,所以不解释值。

工具:decode_tag、decode_varint 和字节切片。wire type 0 是 varint,2 是先读长度 varint 再读相应长度,5 是 4 个字节,1 是 8 个字节。

具体:如果位置(pos)没有准确移动,就会在错误的地方读取下一个 tag——评分器会用 12 条随机消息来测试。LEN 值用十六进制写出。

跳过不认识的字段,但不能丢掉它们

加入 encode_records(records)(decode_message 的逆函数)。解码 /opt/app/grpc/order_v2.bin,对每条记录判断它的编号是否为 v1 schema(/opt/app/grpc/order_v1.proto)所认识的,并以 field=N wire=W known 或 unknown 的格式写入 /root/grpc/06-unknown.txt。

方向:旧解析器能毫无错误地跳过新字段,是因为 wire type 告诉了它长度;而 proto3 解析器不会丢弃这些未知字段,重新序列化时会把它们输出。

工具:decode_message 的逆过程——为每条记录重新写出 tag,再按 wire type 接上值。v1 schema 是 /opt/app/grpc/order_v1.proto。

具体:评分器会让随机消息经过 decode_message → encode_records 往返一次,检查是否与原始数据逐字节相同。只有 v1 声明过的编号才算 known。

子消息就是 LEN 里面的另一条消息

把 /opt/app/grpc/nested.bin 的字段 6(Customer 子消息)的载荷再用 decode_message 解码,并在 /root/grpc/07-nested.txt 中写三行:customer.bytes=<hex>、customer.name=<name>、customer.tier=<number>。

方向:子消息和 string 一样是 LEN 记录——只不过它的 bytes 又是一条消息,所以要用同一个函数再解码一次。

工具:两次 decode_message,以及 /opt/app/grpc/nested.proto 中写明的 Customer 的编号。

具体:customer.bytes 是字段 6 的原始值,也就是去掉 tag 和长度后的负载的十六进制。

解开 packed repeated

加入 decode_packed_varints(raw),解开 /opt/app/grpc/packed.bin 的字段 7(packed repeated int32),并在 /root/grpc/08-packed.txt 中写三行:tags=<comma-list>、packed_record=<hex>、expanded_record=<hex>。

方向:packed 就是在只有一个 tag 的 LEN 记录中把多个 varint 接在一起。

工具:反复调用 decode_varint 直到负载结束的循环,以及用于比较的 encode_records 和 encode_field。

具体:packed_record 是字段 7 的整条记录(tag + 长度 + 负载),expanded_record 是把同一个列表的每个元素都加上 tag 后接在一起的结果。比较两者的长度,就能看出 tag 的开销。