协议与契约
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.*命名空间——帧族与常量全量清单。