Table of Contents

协议与契约

KernLab.Cell.Contracts:Cell 的稳定契约面——两侧(宿主内核与容器)与使用方共持。 控制面是源生成二进制(运行期零反射),数据面的词汇权归使用方。

定位

  • 控制面:帧族标注一次,编译期生成整套二进制线编码——tag 判别、字段序、字节序全是生成物。
  • 数据面:载荷是什么、怎么序列化,容器一概不知;装载点声明编解码 id,使用方注入自己的编解码器。
  • 公开面零网络语义:端点是载体限定描述符(tcp: / uds: / inproc:;shm: 为保留段位), 无 URL、无 DNS、无端口形 API。

握手三步

宿主与容器建立连接后按固定顺序互通三条控制帧,任一步不符即断连(防误连):

容器 ── Hello(协议版本 + 实例标签 + 装载点清单)──► 宿主
容器 ◄─ HelloAck(选定版本 + 回显标签)────────── 宿主
容器 ── Ready(pack 清单 + 启动耗时)────────────► 宿主
  • 宿主校验 Hello 的实例标签与期望一致(InstanceLabel),容器校验 HelloAck 的回显标签—— 两端各自核对,串连到别的容器立即断开。
  • 握手完成前宿主不并发读通道;握手完成后服务泵才启动。

帧族

帧 方向 用途
Hello / HelloAck / Ready 双向 握手三步
Invoke 宿主 → 容器 发起调用(callId、装载点键、deadline、codecId、载荷)
Result 容器 → 宿主 调用回执(错误码 + 载荷)
Callback / CallbackResult 双向 容器回调宿主服务(requestId 多路复用)
Cancel 宿主 → 容器 取消在途调用(容器侧向处理委托传递取消)
TelemetryBatch 容器 → 宿主 遥测批次(best-effort,兼做心跳活性信号)
Drain / Bye 双向 有序收场协商

分帧形态:[4B 大端长度][帧体],帧体上限 4MB(防御上限,超限=协议错误事件,绝不静默丢)。 帧体 TryDecode(ReadOnlySpan<byte>) 原位可解——零拷贝解码是协议验收项,不是某个载体的特权。

调用错误码

错误码 含义
Success 成功
PackNotFound 装载点键未注册(含 drain 中拒新调用)
DeadlineExceeded deadline 到期(宿主侧兜底失败)
Cancelled 调用被取消
InvocationThrew 处理委托抛出(细节走 stderr 取证,不进线内)
ContainerFaulted 容器消亡——在途结果未知,诚实边界
ContainerDraining 容器排水中,拒收新调用

编解码挂载

装载点声明 codecId;缺省 canonical JSON 管道由使用方注入 JsonSerializerContext(源生成, AOT 安全),非缩进 UTF-8 逐字可对拍:

public sealed class MyJsonContext : JsonSerializerContext { }   // [JsonSerializable] 标注你的 DTO

var codec = new CellJsonCodec<MyDto>(MyJsonContext.Default.MyDto);
codec.Encode(dto, bufferWriter);                       // 编码到零拷贝汇
codec.TryDecode(span, out var value);                  // 畸形输入=false,绝不抛后吞

自定义编解码器实现 ICellCodec<T> 同接口同路径挂载,与内建零特权。

反模式

症状 为什么错 正确形态
把业务词汇塞进帧族或错误码 协议是传输契约——业务语义归载荷 业务信息放 payload,编解码归使用方
解码失败静默吞掉 协议错误被伪装成时序问题,排查成本最高 TryDecode 返回 false 必须可见、必报告
在公开 API 上暴露 host:port 形态端点 网络语义外泄即向 RPC 漂移 端点一律载体限定描述符

想深入

  • 快速开始——最小闭环。
  • API 参考中 KernLab.Cell.Contracts.* 命名空间——帧族与常量全量清单。