Table of Contents

KernLab.Tier.Core.Net 使用指南

网络与共识层:介质无关的节点通信三形态(数据报/请求回调/流式)× raft 共识引擎 × 对等机制(HyParView/Swarm),一个 NodeEndpoint 装配成型。

包:KernLab.Tier.Core.Net(依赖 KernLab.Tier.Core——执行/日志/可观测积木)。 深读积木拼装与反模式:../COORDINATION.md。 性能基线(loopback 形态面与 raft 引擎):perf/loopback-baseline.md。


1. 快速上手

1.1 集群节点(成员制)

using KernLab.Tier.Core.Net;
using KernLab.Tier.Core.Net.Hosting;

var nodeId = NodeId.NewRandom();   // 或 NodeId.Parse("hex32...") / 身份源(见 §7)
await using var endpoint = await ClusterBuilder.Create(nodeId)
    .ClusterTag(0x74696572)                 // 集群归属——错集群握手期拒绝(fail-fast)
    .Listen("0.0.0.0", 9400)
    .Peers(new Dictionary<NodeId, IPEndPoint> { [other] = new(IPAddress.Loopback, 9401) })
    .WithLogger(logger)
    .StartAsync(ct);

1.2 直连客户端(地址制)

await using var client = await NetClientBuilder.Create(myId)
    .Connect("node1.example.com", 9400)      // 身份从握手得知
    .ClusterTag(0x74696572)                  // 拨入带标签的集群必须匹配(缺省 0)
    .RegisterRequestHandler(MyProtocolId, new MyHandler())   // 注册可先于拨号
    .StartAsync(ct);

NodeId? remote = client.RemoteId;            // 握手学得的对端身份

1.3 收发一条消息

// 数据报(尽力送达——丢失静默,协议自愈)
await endpoint.SendDatagramAsync(target, MyProtocolId, payload, ct);

// 请求回调(关联应答 + 超时)
byte[] resp = await endpoint.SendRequestAsync(target, MyProtocolId, ask,
    new RequestOptions { Timeout = TimeSpan.FromSeconds(2) }, ct);

2. 概念

术语 含义
节点身份 NodeId 协议一等标识——16B 不透明字节串(NewRandom/NewSequential/Parse/hex32 文本;Empty 哨兵)
协议域 protocolId 端点多路复用的字节标识。核心区归机制面;注册区 0x60-0xAF 归使用方自管(ProtocolIds.IsUserRegistrable 校验,同号重复注册抛)
介质 消息的实际承载:InProcess(同进程直排——测试主场)/ TCP(生产跨进程)/ UDS(Unix domain socket——同机跨进程)/ UDP(数据报承载,握手通告端点)/ QUIC(TLS1.3 原生,stream 直映射)。消费面零差别——机制代码不改一行换介质
形态 消息交互模型三选一:数据报(尽力)/ 请求回调(关联应答)/ 流式(可靠有序+背压)
集群标签 ClusterTag 集群归属编号——握手期核对,错集群连接拒绝(拨入方与服务端必须一致)
成员制 ∥ 地址制 寻址两制:成员制 = 成员表路由(较小 NodeId 拨号防对拨);地址制 = 有地址者直连(身份握手得知)
leader ∥ follower raft 角色:leader 接受写入并复制给其他节点;follower 被动跟随——leader 掉线时由存余节点重新选出
多数派 ⌊N/2⌋+1(N=3 即 2 台)——一条写入拿到多数派落盘才算提交;选举同样要多数派投票

4. 三形态怎么选

你的需求 用 关键语义
心跳/探测/通告(丢了没关系) SendDatagramAsync 尽力送达——对端未连/未注册/注入丢弃全部静默
一问一答(RPC) SendRequestAsync CorrId 关联 + 超时;目标未连抛 NetIOException(快速失败,不白等超时窗)
要确认到达 + 可接受重发 请求回调 + RetryPolicy at-least-once——重发经传输端去重窗口缓存重放(不重复执行)
大块/持续传输(快照/备份) OpenStreamAsync 可靠有序 + 背压(写 await 整链传导);GB 级 O(单帧) 内存

4.1 请求回调

// 服务端
public sealed class MyHandler : IRequestHandler
{
    // 同步回调——快进快出(重活自排队);应答经 reply(零次调用 = 对端超时)
    public void OnRequest(NodeId from, ReadOnlyMemory<byte> payload, IReplyContext reply)
        => _ = reply.ReplyAsync(Process(payload));
}
endpoint.RegisterRequestHandler(MyProtocolId, new MyHandler());

4.2 流式会话

// 发起端
await using (var stream = await endpoint.OpenStreamAsync(target, MyProtocolId, ct: ct))
{
    foreach (var chunk in chunks)
        await stream.WriteAsync(chunk, ct);      // await = 背压(对端慢则本端等待)
    await stream.CompleteAsync(ct);              // 正常收尾——对端枚举自然结束
}

// 接受端(OnStream 回调里起消费循环——循环任务由使用方管理,如经 Core TaskSink 受控提交)
public sealed class MyAcceptor : IStreamAcceptor
{
    public void OnStream(NodeId from, IWireStream stream, ReadOnlyMemory<byte> openPayload)
        => ConsumeAsync(stream);             // 你的消费循环入口(openPayload = 开流载荷)
    private async Task ConsumeAsync(IWireStream s)
    {
        await using (s)
            await foreach (var frame in s.ReadAllAsync())
                Process(frame);                        // 逐帧——不要攒全量
    }
}
endpoint.RegisterStreamAcceptor(MyProtocolId, new MyAcceptor());

会话不跨重连恢复——链路断即 Reset,上层重开。


11. 反模式

  • ❌ 绕三形态直造 socket——丢掉同构验收/超时关联/背压/故障注入/帧协议,全部重造必漂移。 一切收发经 IProtocolTransport。
  • ❌ raft IStateMachine.ApplyAsync 的 command 跨调用持有——仅调用期间有效(存储读取 视图),保留必须 ToArray()。(传输 handler 载荷相反——每帧独立缓冲可持有。)
  • ❌ catch NetIOException 当静默成功——它是"不可达快速失败",该立即重路由/上报; 静默吞 = 白等超时窗。
  • ❌ 协议号用注册区外——使用方一律 0x60-0xAF;核心区号经 internal 挂载口(公开口放行即抛)。
  • ❌ 流式读侧攒全量——ReadAllAsync 逐帧交付是契约(GB 级 O(单帧)),消费方攒 List 违约。
  • ❌ _ = SendRequestAsync(...) 丢弃任务——异常静默吞 + 无超时治理;await 它或交 TaskSink 受控提交。
  • ❌ gossip 广播当可靠通道——最终一致语义(不保序不保达,TTL 到期即弃);要可靠确认 走 raft 复制(§6.1)或请求回调(§4.1)。
  • ❌ 偶数节点当容错——N=2/N=4 的容错与 N=1/N=3 相同(多数派 = ⌊N/2⌋+1,见 §3.5); 偶数只是多付一台成本。

12. 想深入

  • 积木拼装全景与决策树:../COORDINATION.md
  • 网络/传输层架构(三形态收发 × 寻址/准入 × 介质 × 身份安全——本文的使用面对偶): transport-architecture.md
  • P2P/gossip 架构(HyParView 会员收敛/φ 故障检测/广播有界——§8 的使用面对偶): p2p-architecture.md
  • 性能基线(形态面 loopback RTT/吞吐、raft 引擎三节点吞吐):perf/loopback-baseline.md
  • raft 完整产品节点(TierWAL 存储 + 快照压缩 + 多源反熵): ../products/raft-node.html
  • Core 层积木(TaskSink/日志/可观测):../../KernLab.Tier.Core/COORDINATION.md
  • 线格式生成器(WireMessage/BinaryLayout):KernLab.Loom(Layout/Wire 组织包——Tier 为消费者;KernLab.Tier.CodeGen 仅域专属四生成器)

分册导航:net.md | net-topology.md | net-transport.md | [net-raft.md](raft 接入) | net-identity-security.md | net-p2p.md | net-observability.md | 运行拓扑与一致性 | 传输配置与调参 | raft 共识接入 | 身份与安全档 | P2P 会员与 gossip 广播 | 可观测与故障注入