Namespace KernLab.Cell.Contracts
Classes
- ByeFrame
drain 令(宿主 → 容器):容器停止接新调用、在途跑完或窗口到期后退出(ExitCode 0)。
- CallbackFrame
回调(容器 → 宿主):按服务键分发到宿主侧使用方注册(requestId 多路复用)。
- CallbackResultFrame
回调回执(宿主 → 容器)。
- CancelFrame
取消(宿主 → 容器):无应答——结果以 Result 帧错误码 Cancelled 收场。
- CellCallException
调用域失败(关联域超时兜底/本地取消/对端回执错误码的本地投影——机制面,非线材)。
- CellCodecIds
载荷编解码标识(§3.1 数据面——词汇权归使用方)。
- CellConstants
契约常量表(总体设计 §8 全表入码——每条带理由,改动即 ADR)。
- CellDrainReasons
drain 原因(Reason——诊断语义,不构成行为分支)。
- CellExitCode
容器退出码契约(§8——运维归因单源)。
- CellFrame
Cell 帧族根——单一 tag 空间(总体设计 §3.1:帧体 =
[Tag 1B][字段声明序],小端基元; 六族共用一线内判别,接收侧按 tag 单点分发,未知 tag 即协议错误 §3.4)。★ 线编码由
[WireMessage]源生成(CellFrameCodec):Encode/EncodePooled/ Encode(IBufferWriter)/TryDecode 与 TagXxx 常量全部为生成物——畸形帧 TryDecode=false(D5 硬解析)。★ 族划分(§3.3+双向通知增补):Control(0x01–0x05)/Invoke(0x10–0x14)/Callback(0x20–0x21)/ Telemetry(0x30)/Abort(0x40)/Notify(0x50)——族是纪律与关联域的归属,不另占线内字节; 0x51–0x5F 为 Notify 族后续空档。
- CellFrameCodec
CellFrame 消息族线编码——[WireMessage] 派生。
- CellFrameFamilies
tag → 族归属(生成 CellFrameCodec 的 TagXxx 常量为单一事实源;未知 tag=协议错误)。
- CellFraming
分帧线材(§3.1——Cell 拥有:纯 span 线格式,零 IO,容器/宿主两侧共用单一事实源)。
★ 帧形态 =
[长度 4B 大端][帧体];帧体 =[Tag 1B][字段声明序](WireMessage 族编码)。★ 帧长上限校验在这里一次做完:超限=FrameTooLarge 非静默丢(§3.4)。
- CellInvocationErrors
调用错误码表(Result/CallbackResult 帧内——线内协议错误 ≠ 调用业务错误,§3.4; 业务错误语义投影归使用方;改动即 ADR)。
- CellJsonCodec<T>
canonical JSON 管道(Json——内建缺省,§3.5): 使用方自带 JsonTypeInfo<T>(JsonSerializerContext 产物)即 AOT 安全,Loom.Http 同款先例。
★ canonical=UTF-8、无缩进、无 BOM、属性名由使用方 context 冻结(声明序/原样名)——逐字可对拍; 缩进形态的 context 在此拒绝(canonical 破坏=配置错误,fail-fast 不自欺)。
- CellProtocol
协议版本与特征位(§3.2 握手协商)。
- CellProtocolErrorEventArgs
协议错误事件参数(结构化——事件携带码、细节与帧取证;畸形必报告,绝不静默丢,D5)。
- CellResourceDeclaration
资源档声明(§6.3——pack 声明期望资源档,供 spec 翻译 cgroup v2/JobObject;容器不做软件执法)。
- CellTelemetryKinds
遥测记录种类(Kind——log/metric/span,§6.4)。
- CellTransportException
载体层失败(连接建立失败/结构断开——公开面零网络语义词汇,D9)。
- ChunkBeginFrame
分块流首帧(宿主 → 容器,§3.3 分块流式——大体载荷;增补设计稿 §2.2): 调用元数据+首块载荷——关联域在此注册(deadline 跨全程,非逐块)。续块随 ChunkDataFrame。
- ChunkDataFlags
分块流标记位(Flags 线内 byte——位语义单点)。
- ChunkDataFrame
分块流数据帧(双向,§3.3 分块流式):请求续块(宿主 → 容器)与响应块(容器 → 宿主)共用—— 方向由会话语义定(请求完成前收响应分块=方向违约,协议错误事件+关联域 fault)。
- ChunkEndFrame
分块流收场帧(容器 → 宿主,§3.3 分块流式):错误码表+尾块——响应流的唯一合法终结 (错误时载荷可空;部分体+错误尾=使用方语义,容器不吞不补)。
- DrainFrame
drain 公告(双向):发送方声明已停止接新调用(宿主停止派发/容器停止接单,§5.3)。
- HelloAckFrame
握手第二步(宿主 → 容器):选定版本(交集最高)、选定特征位、观察标签、帧长上限。
- HelloFrame
握手第一步(容器 → 宿主):协议版本、特征位、实例标签、装载点自述。
- InvokeFrame
调用(宿主 → 容器):按装载点键分派(§6.3),deadline 到期容器侧弃算不回算力。
- NotifyFrame
通知(双向,双向通知设计稿):无 CallId、无应答、无序号——投递语义=尽力有序(单派发者 FIFO)、 有界丢最旧(NotifyQueueDepth/NotifyQueueBudgetBytes 双限); 业务不可丢事件禁走通知(丢不得的走 Invoke/Callback——超时即显式失败,设计稿 §0 负面清单)。
- ReadyFrame
握手第三步(容器 → 宿主):装载结果——pack 清单与启动耗时。
- ResultFrame
调用回执(容器 → 宿主):错误码表(CellInvocationErrors)+载荷。
- TelemetryBatchFrame
遥测批次(容器 → 宿主):无应答、无关联域——丢了就是丢了(观察面,不在可靠域)。
Structs
- CellEndpointDescriptor
端点描述符(§4/§8——
CELL_ENDPOINT=<载体>:<地址>;握手前 stdout 唯一合法输出)。★ 描述符形态:
tcp:127.0.0.1:52311/uds:/tmp/cell-x.sock/shm:cell-<世代>-<id>/np:cell-<pid>-<id>/inproc:<名字>。载体替换对协议与使用方零感知——上层只见本结构。★ 解析纪律:严格形态,不猜不修——失败即 false/抛(fail-fast 优于隐式降级,Tier 判例)。 载体段大小写不敏感(操作员友好),归一化输出小写;地址段逐字保真。
- PooledFrame
收帧载体——池化租借的一整帧体;用毕 Dispose() 归还(热路径零稳态分配)。
- TelemetryRecord
遥测记录行(定长二进制布局——小端;[BinaryLayout] 源生成
TelemetryRecordCodec)。内容载荷在 Payloads(变长部分不入定长行——嵌套布局只收定长字段)。
Interfaces
- ICellCallbackBridge
回调桥客户端(容器侧——§6.4 容器 → 宿主的反向调用原语): 使用方经服务键调用宿主侧注册的处理者(Callback 帧 requestId 多路复用,await 期间并发发起安全)。
- ICellCodec<T>
载荷编解码(§3.5 编解码挂载——数据面词汇权归使用方,容器不知 payload 里是什么)。
★ 挂载纪律(Tier 机制挂载同构):使用方自制裁入与内建同接口同路径,零特权。
★ 硬解析纪律(§3.6 同源):TryDecode 对畸形输入必须 false,绝不抛后吞。
- ICellNotificationEgress
通知出口(容器侧——双向通知设计稿 §2.1/§4:ICellTelemetryEgress 同型的 best-effort 面)。 通知按"可丢"定位:队列满丢最旧、drain/断连即丢——业务不可丢事件禁走通知(设计稿 §0 负面清单)。
- ICellPackBuilder
pack 装配面(容器侧引导器在 Configure(ICellPackBuilder) 时交付; 装载点键=Invoke 帧分派键,数据面词汇权归使用方——CodecId 随点声明,§3.1)。
- ICellPackStartup
pack 装载契约(总体设计 §6.3——使用方实现 ICellPackStartup,
--startup指向; 显式装配零扫描:注册装载点与回调服务、声明编解码与资源需求)。
- ICellTelemetryEgress
遥测出口(容器侧——§3.3/§6.4 best-effort:有界队列丢最旧,永不阻塞调用路径; 心跳档由出口按 HeartbeatMissLimit 配套节奏发出空批次兼做活性信号,§5.2)。
- ICellTransport
IPC 载体端口(总体设计 §4——唯一换向点:
Bind/Connect/Accept/Send/Receive/Close+端点描述符)。★ 上层(协议通道/池/装载)对载体零感知——载体阶梯(InProcess/环回 TCP/UDS/shm)可换, 协议语义零网络(无 URL/DNS/端口形 API、无 TLS 面——D9;同机信任=OS 进程边界)。
★ 阶梯终点=shm:Input 以 PipeReader 序列暴露=帧体原位可解(TryDecode 零拷贝), 通道 API 不暴露 stream/copy 语义(shm-ready 验收项,§4)。
- ICellTransportConnection
载体连接(§4 六操作之 Send/Receive/Close 的载体面):
★ Input=读半边(有序可靠字节流;分帧在协议通道层 §3.1——载体不识帧)。
★ Output=写半边——必须经
FrameWriter单点串行使用(§3.6:并发写一条流结构上禁止)。★ Close=结构断开——对端以流结束收场(通道断=fail-fast 事件),绝不静默挂起。
- ICellTransportListener
载体听点(Bind 产物——Accept 出连接;Dispose 即关闭听点)。
Enums
- CellEndpointScheme
端点载体类型(§4 载体阶梯+进程内档——载体限定描述符,公开面无裸 host:port,D9)。
- CellFrameFamily
帧族归属(§3.3 六族——纪律与关联域的归属单位;不占线内字节)。
- CellProtocolError
线内协议错误码表(帧层——畸形帧/超限帧/未知 tag/关联域溢出,§3.4; 计数递增+结构化协议错误事件+可配置断连阈值;改动即 ADR)。
- CellProtocolFeatures
握手协商特征位(初版两个;位集随版本演进,改动即 ADR §3.2)。