DHT 消息格式

连接与消息分帧

DHT operation 运行在已经按中继连接与身份认证完成验证的合格公共中继之间。每个 stream 使用 libp2p protocol /meshline/kad/1.0.0，消息以 unsigned varint 长度前缀加 protobuf bytes 编码，单条消息最大 1 MiB。外层长度前缀遵循统一的消息长度前缀编码规则。

Protocol 1.0 不传输无法容纳在单条消息中的资源，不得把超限内容写入单个 Record。Peer 资格、连接身份和路由表维护见覆盖网络与节点维护。

Protobuf 消息

DHT stream 使用 libp2p Kademlia protobuf schema 的以下子集。Message 是一次 DHT 查询或写入及其返回消息的外层帧；Record 承载一个 DHT key 对应的资源 value；嵌套 Peer 是返回方向提供的、更接近目标 key 的候选中继 Peer。

message Record {
  optional bytes key = 1;
  optional bytes value = 2;
}

message Message {
  enum MessageType {
    PUT_VALUE = 0;
    GET_VALUE = 1;
    ADD_PROVIDER = 2;
    GET_PROVIDERS = 3;
    FIND_NODE = 4;
    PING = 5;
  }
  enum ConnectionType {
    NOT_CONNECTED = 0;
    CONNECTED = 1;
    CAN_CONNECT = 2;
    CANNOT_CONNECT = 3;
  }
  message Peer {
    optional bytes id = 1;
    repeated bytes addrs = 2;
    optional ConnectionType connection = 3;
  }
  optional MessageType type = 1;
  optional bytes key = 2;
  optional Record record = 3;
  repeated Peer closerPeers = 8;
}

字段语义

Message.key 携带本次操作的原始目标输入；Message.record.key 是按资源键派生规则得到的原始 32-byte 资源 key；
Message.record.value 承载资源内容，其编码和大小见账户路由资源规则；
Peer.id 是候选 Peer ID 的原始 multihash bytes；Peer.addrs 的每一项是一个 multiaddr 的二进制编码。候选处理遵循连接与身份认证；

各 operation 对 type、key、record 和 closerPeers 的出现规则见 DHT 操作。

扩展与兼容规则

providerPeers、clusterLevelRaw 和未使用消息类型不得影响资源查询结果；
未知 protobuf 字段按 protobuf 兼容规则忽略。

消息拒绝与失败处理

接收方必须拒绝 key 长度不符合相应操作要求的消息。消息携带 record 时，若 Message.record.key 与 Message.key 不一致，或 Message.record.value 不符合相应资源类型规则，也必须拒绝。

Kademlia 消息没有协议错误响应字段。非法长度前缀按连接与消息分帧规则终止 stream。因其他消息分帧错误、消息超过大小上限、限流、无效 key、无效 record 或不支持的资源类型拒绝消息时，必须关闭或 reset 对应 stream。

在取得有效返回消息前 stream 终止时，发起方必须将本次操作视为临时失败，并按本地退避策略处理，不得立即循环重试。