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 广播 | 可观测与故障注入