Skip to content

Translation pending. This page is currently available in Chinese.

CL 线协议:v0 基础帧与 v1 会话事务

v0 编解码和金样保留兼容。可靠会话扩展使用协商后的 v1,不复用 v0 设计中未实现的 ACK 捎带载荷语义。frame.c 的严格 v0 入口用于旧金样对拍,运行时入口允许 v0/v1,传输适配器再检查对端协商版本。

1. 帧布局

所有多字节字段使用显式小端,不能直接序列化 C 结构体。

偏移 字段 字节数 约束
0 magic 2 0x4c43,线上字节 43 4c
2 ver 1 0 或协商后的 1
3 type 1 下表中的 1–11
4 flags 2 低 4 位已定义
6 frag 2 低 12 位片号,bit15 末片,bit12–14 保留
8 txid 4 CALL 事务号;0 保留;SEND 必须为 0
12 src_hash 4 完整 node_id 的 FNV-1a32
16 dst_hash 4 目标 node_id 的 FNV-1a32
20 dst_slot 4 服务槽;可靠 v1 的 0 为完成收据
24 seq 4 非 RELIABLE 必须为 0
28 payload_len 2 不包含帧头与 CRC
30 ttl 1 默认 8;转发逐跳减 1;耗尽拒绝
31 csum_kind 1 0=无尾部 CRC,1=CRC16-CCITT
32 payload 可变 精确等于 payload_len
后续 crc 0 或 2 按 csum_kind 决定

CRC16-CCITT-FALSE:多项式 0x1021,初值 0xffff,不反射,不做末异或。覆盖头与载荷;123456789 校验值为 0x29b1。单帧载荷预算始终按 MTU - 32 - 2 计算,即使未携带 CRC 也不增加预算。 UART 与当前 UDP 控制/数据发送均携带 CRC。

接收顺序为最小长度、magic、版本、type、校验种类、MTU、实收长度、CRC、 frag/flag 一致性、seq/flag 一致性、SEND 的 txid、固定载荷长度。层 1 格式错误计 malformed,TTL/未知身份/策略拒绝计 drops。保留位接收兼容策略与 v0 金样保持一致;发送者必须清零。

2. 消息类型

type 名称 载荷
1 HELLO 固定 32 B
2 HELLO_ACK 固定 32 B
3 PING 固定 8 B
4 PONG 原样回显 PING 的 8 B
5 SEND v1 会话前缀 + 单向业务;需 ONEWAY 能力
6 CALL v0 业务载荷,或 v1 会话前缀 + 业务载荷
7 CALL_REPLY v0 业务载荷,或 v1 回复前缀 + 业务载荷
8 CLOSE 空
9 ACK 固定 4 B;v1 为被接纳的单帧 seq
10 NACK 固定 4 B;当前不发送
11 ERROR 固定 8 B:u32 errno + u32 orig_txid

v0 caller 释放代理发 CLOSE,txid=0xffffffff 标识调用方关闭;接收方不能因此关闭同节点同 slot 的反向代理,也不能删除共享服务的 FIFO 配对。txid=0 保留历史服务关闭处理。可靠事务编号跳过 0 和 0xffffffff。

3. flags 与能力

位 名称 当前行为
0 RELIABLE v1 有界会话事务;双方版本/能力必须支持
1 FRAGMENTED v1 协商的可靠 CALL/REPLY/SEND 分片,详见第 8 节
2 BROADCAST 当前适配器拒绝
3 COMPRESSED 保留;发送拒绝,v0 层 1 接收兼容

v0 的 seq/累计 ACK/捎带 ACK 方案保留在历史参考语料中,当前运行时不把它当作可用可靠服务。旧 peer 只公布版本 0 时,可以继续非可靠 CALL,不能建立A20_CONNECT_RELIABLE 连接。

4. HELLO 与会话

HELLO 本身用 v0 基础帧,32 B 载荷:

偏移 字段
0 node_id[16]
16 proto_min u8
17 proto_max u8
18 resource_profile u8:½/3
19 caps u8:RELAY=1、RELIABLE=2、LEAF=4、FRAGMENT=8(v1 主机传输特性)、ONEWAY=16(可选单向业务)
20 short_addr u16
22 link_addr_len u8:UART=2、UDP=6
23 reserved u8
24 session_nonce u64

当前发布版本区间 0–1。身份不能全零、全 ff 或等于本机;完整 ID 和源哈希必须一致;版本区间必须有交集;LEAF 与 RELAY 不能同时声明。资源档不限制角色为某种处理器。FNV 哈希冲突由路由表拒绝。

nonce 在一个会话内保持稳定,重试 HELLO 不更换 nonce。启动 epoch 必须来自可靠熵或平台持久计数,不能把固定启动 tick 当作跨断电唯一性的证明。 UDP 主机使用内核 RNG;STM32 已接入两页持久 epoch journal,物理写入验证仍待完成。

UDP 使用 HELLO.txid 作为本方 challenge,HELLO_ACK.txid 回显它。只有当前 challenge 的应答才能更新对端 epoch,旧 ACK 不得使会话回退。UART 使用双向 challenge,收到 HELLO 先应答,再用本方 HELLO 确认当前对端;只有匹配当前 challenge 的 ACK 能更新会话。v0 兼容连接不能替换已经建立的 v1 会话。实现和掉电/重放测试参见 MCU 共享内存内核规范 及 传输层适配规范。

5. v1 可靠 CALL

ver=1, flags.RELIABLE=1, seq=txid,单帧 CALL 载荷:

u64 caller_session
u64 server_session
byte application_payload[]

接收方先校验双方会话,然后预留事务记录和最大单帧回复缓存;成功后才提交序号窗口并注入服务。缓存/队列不足时返回带会话的错误回复,不执行请求。事务键为来源身份、双方会话和 txid。相同 key 的重复 CALL:正在执行则确认接纳,已经完成则重发原回复,不能重新执行。

v1 ACK 的 payload 是本次 CALL 的 seq。它只证明请求已接纳,不能结束业务等待。当前单帧实现不需要累计 ACK,也不捎带 ACK。

6. v1 回复与完成收据

CALL_REPLY 载荷:

u64 server_session
u64 caller_session
u32 status                 // 0=业务回复;非零=A20 错误码
byte application_reply[]   // status 非零时为空

前缀由代理剥离,正常服务和调用者仍看到原业务消息。业务自己的状态码可继续放在业务载荷里,与这里的数据面错误区分。

调用者接收回复,或关闭仍在途的 endpoint 放弃结果时,发送收据:v1 RELIABLE CALL,dst_slot=0, seq=txid,载荷仅 16 B 原会话对。语义是调用者不再需要结果,不是取消远端业务。主机若仍在执行,保留其预留记录直至 worker 完成才允许复用;放弃通知先于原请求到达时,把该序号提交到去重窗口,迟到请求不能再执行。服务方可复用已完成且已获收据的回复存储;独立序号窗口保留去重信息。已经退休或过旧的请求明确拒绝,不能为了腾空间再次执行。

主机有 64 项有界回复表;MCU 单回复缓存。MCU 没收到完成收据且缓存仍在保留期内时,拒绝新请求为 NO_SPACE。应用必须按协商容量分配并发。发送代理对 LEAF 的所有可靠连接合计只允许一个在途;未接纳 NO_SPACE 会重发最近一个绑定会话的退休收据,以恢复收据丢失造成的单槽占用。对声明 ONEWAY 的新实现,发送方还约束同一对端所有代理的未完成编号跨度小于 64。新编号前进至少 64 时,接收方可复用该来源已经完成的旧缓存,即使显式退休收据丢失;运行中的记录和其他来源记录不按此规则回收。

7. 重试、期限与保证范围

发送方保留完整请求副本。初始重试间隔 250 ms,指数增加到 2 s,每次调用最多重试 8 次,且固定期限不超过 30 s。任一上限触发即取消代理并唤醒所有等待者。ACK 不停止业务恢复重试,丢回复会触发缓存重放。

服务缓存保留期为 35 s,大于调用期限。采用 64 位序号位图及 32 位 serial 比较,允许窗口内乱序,拒绝过旧未见请求。调用编号回绕跳过保留值与在途号。序号比较要求保留期内不能跨越半个 32 位序号空间。

普通业务单向 SEND 扩展保持 wire txid=0,以非零 seq 共享可靠窗口。成功完成回执没有业务回复体,只确认接纳;格式、能力协商和队列背压参见 运维指南。默认未启用的部署不增加 HELLO 能力位。

保证仅覆盖当前会话与有界保留/序号窗口,不是跨断电 exactly-once。作业层仍须对 (job_id, shard_id) 去重,并显式声明是否允许重派。

8. 分片、转发与错误

v0 格式金样保持不变;v1 主机 UDP 已接入协商分片、有界重组和首片期限。跨不同 MTU 网关的重分片仍未实现,出口容纳不下原片时明确丢弃。 RELAY 转发已实现 TTL 递减和 CRC 更新;CS/1 双向挑战确认间接目的身份、 boot epoch 和路径 MTU。完整 UDP 路径可协商多跳分片;经过 UART 或未协商分片的路径使用单帧预算(参见 传输层适配规范)。

v0 ERROR 保留固定 errno/orig_txid 布局。v1 接纳后的错误通过带会话的 CALL_REPLY.status 返回。旧/错误会话数据丢弃,不能唤醒或完成新会话事务。现有 Native channel 将远程失败统一表现为 CANCELED;精确错误接口待扩展。

9. 可复现协议证据

python3 tools/cluster/check-cluster-unit.py
python3 tools/cluster/check-cluster-udp.py --faults --restart

前者运行生产编解码、UART/MCU 配对、序号回绕测试及原 v0 金样;后者在两套独立内核之间丢请求/回复/ACK/完成收据、重复/延迟帧、全丢包直到重试耗尽,重启一端再注入旧 HELLO_ACK 与旧 CALL。测试验证与运行详情参见 10-operator-guide.md。