Table of Contents

网络/传输层架构（三形态收发 × 寻址与准入 × 介质 × 身份安全）

本文回答：Core.Net 网络层怎么保证可靠性、顺序、身份与安全——三形态收发（数据报 / 请求回调 / 流式会话）的语义边界、寻址与准入、TCP/QUIC/UDS/InProcess 介质同构、线协议与 握手、身份与安全三档、以及活性/自愈保证。它是 raft-architecture.md 的网络层对偶（raft 讲共识，本文讲承载共识与业务的传输面）。

与 net.md 的关系：net.md 是使用面（怎么配传输、怎么调参、怎么选形态）； 本文是实现面——据本文判断"网络层在什么条件下不丢/不乱/可认证/可自愈"。 代码引用为仓库相对路径（Channels/…/Transport/… = src/KernLab.Tier.Core.Net/…）。

规格源：spec-12（网络核心设计——内部设计文档，语义已实施于 Core.Net，本文是其实施后的公开架构描述）。

1. 架构总览

                     IProtocolTransport（节点端点完整面 = IProtocol × ITransport）
        ┌──────────────────────────────┼──────────────────────────────┐
        │ 协议域面 IProtocol            │ 传输连接面 ITransport          │
        │  ┌─────────────────────────┐ │  ┌─────────────────────────┐ │
        │  │ 三形态收发（协议域分流）  │ │  │ 身份/生命周期/对端观测    │ │
        │  │ 数据报 · 请求回调 · 流式 │ │  │ PeerConnected/Gone      │ │
        │  │ 会话                     │ │  │ 故障注入 Faults         │ │
        │  └─────────────────────────┘ │  └─────────────────────────┘ │
        └──────────────────────────────┼──────────────────────────────┘
                                       │ 介质实现（装配期每节点一个统一枢纽）
        ┌───────────────┬──────────────┼──────────────┬───────────────┐
        │ TCP           │ QUIC         │ UDS          │ InProcess      │
        │ ClusterTransport│ QuicTransport│ 本地域套接字  │ 同构基准/语义参考│
        └───────────────┴──────────────┴──────────────┴───────────────┘
  • IProtocolTransport（Channels/IProtocolTransport.cs）= 协议域面 × 传输连接面合一， 消费方按需持半边或整面。介质无关：同一机制/产品代码不改一行换介质（InProcess = 同构 基准/语义参考实现）。
  • 统一传输枢纽 ClusterTransport（Transport/Tcp/ClusterTransport.cs）：装配期每节点一个， 协议域注册/数据报发送/节点观测/故障注入。成员制与地址制两制寻址、准入分层、每有序节点对 一条 TCP 长连接（详见 §3）。
  • 通道组件（Channels/ 形态组件——全介质单源）：DatagramDispatcher（数据报分发）、 RequestBroker（请求回调）、StreamBroker（流式会话，TCP 实现）、QosManager（限流）。

2. 协议域与三形态收发

2.1 协议域注册分流（spec-12 §3.5）

  • 公开口（IProtocol.RegisterProtocol 等）只放行注册区 0x60-0xAF——使用方自管号码； 同 ID 重复注册抛。
  • 内部核心区 0x00-0x4F 经程序集内 internal 挂载口 ICoreProtocolPort（机制面专用—— raft/HyParView/Gossip 等内建机制零特权，与使用方同一分发路径，号码来源分流）。
  • 消息分发即身份：帧分发随载荷提供来源 NodeId，发送方身份不上线（对端知道谁发的）。

2.2 数据报（尽力送达，spec-12 §5.1）

  • 对端未连 / 未注册协议 / 注入丢弃 = 静默丢弃——协议域定时器自愈；发送只对参数错误 （超帧上限/取消）抛。
  • handler 快进快出契约：回调异常不外泄、不杀链路（尽力语义）。
  • bearer 声明承载偏好（DatagramBearer.Udp/Tcp）；介质不支持时回落/直派——尽力语义不变。

2.3 请求回调（单请求 → 关联应答 → 超时，spec-12 §5.2）

  • RequestBroker：CorrId 生成（随机起始 + 递增——本端在途集合唯一）+ pending 关联表 有界（容量满抛 fail-fast——并发失控立即暴露而非静默排队）+ 等待/超时/取消。
  • 投递语义缺省 at-most-once（单发 + 超时）；重传/确认 = 显式选择（RetryPolicy—— at-least-once，配合 ResponseDedupWindow 去重窗口——重复应答被吸收）。
  • 防泄漏不变量：每个 BeginRequest 必有终态清理（应答完成 / Abandon 发送失败 / 超时或取消后 Abandon）——关联表无孤儿。
  • 目标未连 = 抛 NetIOException（调用方有应答期待，不静默浪费超时窗）。

2.4 流式会话（可靠有序 + 背压，spec-12 §5.3）

  • IWireStream：StreamOpen/Accept/Data/End/Reset 帧族承载，会话号 1..254，不跨重连恢复 （上层重开）。可靠有序；GB 级流 O(单帧) 不驻留（读一帧处理一帧）。
  • 背压 = 写 await 传导：接收侧会话缓冲有界 → 满 → 介质读循环 await → 对端 socket 写 await → 本端 WriteAsync await——整链传导。
  • 生命周期：正常收尾 CompleteAsync（End 帧）；异常中止 DisposeAsync（Reset 帧——双方 读写立即终止）。未注册 acceptor 的协议域 = 拒绝开流。

3. 传输连接面（寻址 / 准入 / 连接模型）

3.1 寻址两制（spec-12 §4.1）

制 驱动 语义
成员制 装配期静态地址表（NodeId → 端点） 自动拨号与集群路由；断线自动重连（指数退避，封顶 = raft 消费方按 ElectionTimeoutMin/2 覆盖——选举协议不被重连节奏劫持）
地址制 ConnectAsync 直连 对端身份握手得知——不在地址表也可建立；链路仅承载该连接上的定向通信，断开不自动重连

3.2 准入分层（spec-12 §4.3）

  • 连接准入：任何完成合法握手（帧/版本/ClusterTag/安全形态）的连接可建立——成员与直连 共用同一监听口。
  • 成员准入：地址表成员——拨号归属违规检查（成员制较小方拨号——入站来自较大成员 = 握手期违规；地址制有地址者拨号，大小无关）。

3.3 连接模型与保活

  • 每有序节点对一条 TCP 长连接：NodeId 较小方主动拨号并独占重连退避（较大方只监听）； 所有协议域共享该连接；断线重连指数退避（初值 ×倍率）。
  • 保活计票（Transport/Tcp/KeepaliveTracker.cs）：周期发送 Keepalive，连续无入站保活达 上限即断连（半开死链检测）——"连续"语义 = 收到即归零（TCP 帧流不丢帧，丢帧形态 = 半开死链）。
  • 故障注入面常设（ITransportFaultInjector）：延迟/分区/丢包/乱序，任一介质等价复跑。

4. 介质（TCP / QUIC / UDS / InProcess）

介质 实现 要点
TCP Transport/Tcp/ClusterTransport.cs 统一枢纽：两制寻址 + 三形态 + UDP 回落；握手期协调节点大小/安全档/ClusterTag
QUIC Transport/Quic/QuicTransport.cs 三形态 stream 直映射 + 对称握手 + at-least-once 去重窗口 + 同构矩阵三介质复跑
UDS Transport/Uds/ 本地域套接字（macOS/同机 IPC）
InProcess Transport/InProcess/ 同构基准/语义参考实现——测试与嵌入
UDP 数据报端点 TransportOptions.UdpListenEndPoint 绑定 UDP 并经握手通告（Negotiate 帧承载）；bearer 声明 UDP 的协议域在对端端点已知且单报预算内（1200B）走 UDP，其余回落 TCP 帧流承载——尽力语义不变

介质无关性：同一机制代码（raft/复制 lane/请求回调）换介质零改动——IProtocolTransport 是装配缝，介质实现差异在 Start()/连接生命周期内部吸收。

5. 线协议与帧

5.1 帧头（spec-12 §3.1，16B 定长、全部小端、介质无关）

[0..4)  4B  PayloadLength   载荷长度（≤ 16MB）
[4]     1B  Kind            帧种类（FrameKind）
[5]     1B  ChannelId       通道标识
[6]     1B  ProtocolId      协议域 ID
[7]     1B  Version         线协议头版本（=1）
[8..12) 4B  HeaderCrc       CRC32C（覆盖此前全部头字节——防半帧/错位）
[12..16)4B  PayloadCrc      CRC32C（覆盖载荷）
  • 头版本 1 的字段永不再解释——演进走版本协商 + 新 FrameKind（spec-12 §3.2）。
  • [BinaryLayout] 声明即代码：字段位置/读写/偏移常量由生成的 Codec 产出——零手写偏移 （TCSG001 锁 Size 与偏移和一致），加字段 = 加一行声明。

5.2 握手（HandshakeInit/HandshakeAck）

握手帧承载：版本协商 + ClusterTag（防串集群）+ 安全形态（明文/KeyPair/mTLS）+ 成员制 大小协调 + UDP 端点通告（Negotiate 特性位）。握手失败 = Error + 断连（防降级）。

6. 身份与安全（三档，spec-12 §3.4）

档 机制 信任锚 适用
明文 Plaintext 零开销 — 可信域内网
KeyPair（推荐缺省） 签名（身份）+ ECDH（前向保密）+ 帧 AEAD/MAC 公钥配置钉扎（KeyPairPinned）或 TOFU（SSH known_hosts 式，首连有中间人窗口） 无证书部署——信任强度与 mTLS 等价
mTLS TLS1.3 证书体系 CA（SAN nid: 绑定 + 短期证书轮换） CA/合规场景
  • 防降级：装配期一次给全、运行期不可变——本端配置档与对端到达帧安全档不匹配即 Error + 断连，永不机会主义升降级。
  • 帧保护粒度（KeyPair 档）：MacOnly（仅完整性——防冒充/伪造/篡改，不加密）/ Aead （完整性 + 机密性，推荐缺省——与 mTLS 强度等价）。
  • 身份：NodeId 全局唯一；CertificateNodeId（mTLS 证书 → 节点 ID 绑定）；握手期 密钥派生后经 SecureRecordCodec/SecureSession 逐帧保护。

7. 可靠性 / 活性 / 有界性保证

保证 机制
尽力送达自愈 数据报静默丢弃 → 协议域定时器自愈（raft 心跳/选举重试）
半开死链检测 KeepaliveTracker 连续未答上限断连 + 重连指数退避
重连不劫持协议 退避封顶 = raft ElectionTimeoutMin/2（选举窗不被重连节奏劫持）
请求不泄漏 RequestBroker pending 有界 + 终态清理不变量
响应去重 ResponseDedupWindow（at-least-once 重传的重复应答吸收）
并发失控暴露 pending 容量满 fail-fast（不静默排队）
限流/审计/授权 QosManager（每协议/每来源限流）、NodeAuthorizer（入站准入钩子）、审计 sink
握手冷却 同源 IP 握手失败冷却（防恶意重试风暴）+ 拒绝计数诊断
观测 ObservabilityHub.Net 视图（连接/消息/错误——唯一接入点）

8. 与上层的接线

上层 用传输的什么 关键语义
raft 请求回调（AppendEntries 直排 + Vote 事件化）、数据报（可选） 心跳直排（收到即续约）依赖请求回调 at-most-once + 在途超时重试；复制 lane 每批一发
P2P/gossip 数据报（HyParView 0x02 / Gossip 0x05） 尽力送达 + 协议域定时器自愈；见 p2p-architecture.md
Swarm/多源 流式会话（GB 级块流）+ 请求回调（块清单/应答） 可靠有序 + 背压传导

9. 相关文档

  • 使用面（传输配置/调参/三形态选型）：net.md
  • 共识层架构（raft 在传输上的语义）：raft-architecture.md
  • P2P/gossip 架构：p2p-architecture.md
  • 全系列二进制格式手册（Wire 帧 / Raft RPC 消息族 / Gossip / 存储与产品帧的字节布局）： binary-format-spec.md
  • 规格源：spec-12（内部设计文档，不随包发布——本页为实施后公开描述）。
  • 产品装配（内建 TCP 传输组装）：raft-node.md
Edit this page