Run Protocol
Run Protocol 是建立在 OCI 标准对象之上的程序执行协议。它只回答一个问题:给定一份明确的执行输入,执行引擎应当如何运行程序,并返回哪些执行结果。
本文及后续协议页中的“必须”“不得”和“可以”是规范性要求。示例只用于解释要求,不能替代规范本身。
协议模型
RunInput是一次执行所需的完整输入。RunEngine::run负责验证输入、确认自身能力、执行所有 Program,并尽力收集结果。RunOutput保存这次调用已经取得的执行事实与结果。EngineError表示引擎没有产出一份符合协议的RunOutput。
调用方负责提供完整的 RunInput,并消费本次调用返回的 Result。协议对象的语义不依赖某种传输或存储实现。
协议目标
一次程序执行可以抽象为:
Run Protocol 使这条边界足够明确。输入完整描述受控的执行条件,执行引擎忠实实施这些条件,输出保存引擎能够在执行边界上直接观察到或取得的事实。协议不解释被执行程序的内部领域语义。
初始环境由 OCI Image 表达,进程及其运行条件由 OCI Runtime Configuration 表达。协议只补充 OCI 没有覆盖、但一次可比较的执行需要的少量语义:长度有限的标准输入、敏感环境变量与文件、输出捕获、执行超时、网络控制、停止流程、可选的最终环境捕获和多个 Program 的协调。
核心对象
RunOutput 与 EngineError 的边界
Program 的非零退出、终止信号、执行超时、取消、OCI create 或 start 失败、标准流传输错误、输出截断、停止错误和最终环境不可用,都是一次执行可能产生的结果。即使第一个 Program 没有成功启动,只要引擎能够形成符合协议的事实集合,就必须返回 Ok(RunOutput),不能仅因为这些结果“不成功”而返回 EngineError。
下列情况属于 EngineError:
RunInput不符合协议,所引用的必要 OCI 内容无法取得,或者引擎在开始执行操作前已经知道自己无法忠实执行它。- 引擎自身失败,以至于无法形成一份结构完整、事实可信的
RunOutput。
一旦有 Program 开始执行,引擎必须尽力停止其余进程、排空标准流,并按 RunControls 决定是否捕获最终环境,然后返回 RunOutput。如果引擎进程意外终止或宿主机停止运行,这次调用可能没有返回值。Result 只表示调用实际返回的协议结果。
协议不变量
所有实现都必须满足以下要求:
RunInput必须是确定的执行对象,不能包含需要执行引擎临时解析的名称、tag或产品默认值。- 引擎必须在启动任何 Program 前验证输入,并确认自身能够忠实执行。已知不支持的条件必须返回
EngineError,不能静默忽略、改写或降级。 - 调用开始后,引擎不得修改
RunInput。执行时生成的bundle、rootfs绝对路径、Runtime 对象名和其他临时资源不属于输入。 - 引擎只能记录自己直接观察或能够证明的事实。无法取得的结果必须明确标记为不可用,不能猜测、补齐或用空值冒充。
- Program 的进程结果、引擎执行操作时发生的错误和外部系统作出的评价必须分开表达。
- 每次调用必须有且只有一个主程序,可以有零个或多个受控依赖程序。
- OCI 已经定义的字段、默认值和
options继续由相应 OCI 标准及所用 Runtime 解释。Run Protocol 只规定它们与本协议对象相接的语义。 - OCI Runtime Configuration 显式引用的宿主资源属于输入。被引用资源的实际状态不因此成为受控环境,也不由引擎推断内容身份。
协议文档结构
协议按以下顺序展开:
- Run Input:输入结构、OCI Runtime Configuration、标准流限制和执行控制。
- Run Engine:
run的执行顺序、验证边界、计时、终结和结果收集。 - Run Output 与 EngineError:输出结构、事实分类,以及执行结果与引擎错误的边界。
- Run 的初始环境与最终环境:OCI Image 如何表达执行前后的受控文件系统。
- 受控依赖程序的执行语义:多个 Program 的启动关系和生命周期协调。
与调用方组合
采用本协议的系统负责构造 RunInput、调用 RunEngine,并消费返回结果。系统可以把结果传给后续处理,也可以组织多次调用进行比较。无论采用哪种方式,同一次 run 的协议语义保持不变。
Program 自行决定把哪些内部信息写入 stdout、stderr 或受控文件系统。RunEngine 保存执行边界上可取得的原始结果,不解释工具调用、消息、Trace 或任务阶段等领域内容。