Table of Contents

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

遥测批次(容器 → 宿主):无应答、无关联域——丢了就是丢了(观察面,不在可靠域)。

TelemetryRecordCodec

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)。