Run Engine
RunEngine 是 Run Protocol 的执行边界。它接收 RunInput,管理一次完整的程序执行,并返回 Result<RunOutput, EngineError>。
本页规定 run 内部必须完成的顺序和可观察语义。实现可以选择自己的代码结构和进程模型,但必须提供相同的协议行为。
内部验证不是协议阶段
run 必须在启动任何 Program 前完成两类检查:
- 输入验证:确认输入结构、OCI 对象、跨字段约束和固定限制符合协议。
- 能力验证:确认当前引擎能够忠实实施输入中的每项条件。
失败时返回 EngineError,并指出字段或能力原因。产品可以在调用前提供建议性的输入检查,但真正执行仍必须在 run 内验证,因为内容、宿主资源和引擎能力可能已经变化。
执行顺序
一次调用按以下顺序进行:
准备包括验证并物化 OCI Image、创建 OCI bundle、建立标准流和执行所需资源。引擎必须为每个 Program 使用独立的可写 rootfs。
执行区间与超时
执行区间从第一个 Program 即将执行 OCI start 时开始,到调用进入终结阶段时停止。计时必须使用单调时钟。
execution_timeout_ms 省略时没有执行期限。显式期限到达后,引擎停止启动新的 Program,并立即进入终结阶段。准备和结果捕获不计入执行区间,但仍然必须有界,不能让一次调用因内部操作而永久无法返回。
进入终结
下列任一条件使执行进入终结阶段:
primary退出。primary无法创建或启动。- 执行期限到达。
- 调用方取消当前
run调用。 - 引擎发生导致已启动 Program 必须停止的操作错误。
取消针对正在进行的 run 调用。具体使用同步调用、取消令牌、进程信号还是其他控制句柄,属于引擎接口设计。实现方式不能改变输出中事实的含义。
受控依赖程序在 primary 运行期间自行退出,不会单独触发终结,也不会被重启。具体语义参见受控依赖程序的执行语义。
有界停止
进入终结后,引擎必须停止继续传递尚未写完的 stdin,关闭输入写端,并对所有仍在运行的 Program 执行有界停止:
- 发送
SIGTERM。 - 继续排空
stdout和stderr,并等待进程结束。 - 从首次尝试发送
SIGTERM起,全体 Program 共享 10 秒宽限期。 - 宽限期结束后,对仍在运行的 Program 发送
SIGKILL。 - 在实现声明的有限确认期限内等待,并取得能够证明的进程结果。
对于已经自然退出或确认没有启动的 Program,引擎不得伪造停止动作。信号发送失败、等待失败和确认期限届满都必须作为事实返回。确认期限届满后,进程结果标记为未知。请求捕获最终环境时,如果无法证明所有写入进程已经停止,最终环境必须标记为不可取得;未请求时仍返回 not_requested。
内部操作期限
10 秒停止宽限期是所有实现共同的协议常量。除此之外,每个 RunEngine 还必须公开以下操作使用的有限期限:准备、Runtime create 与 start、发送 SIGTERM 与 SIGKILL、等待进程、强制终止后确认、标准流排空、运行时文件系统移除、最终环境捕获和清理。这些期限是实现能力,不是 RunInput 字段。同一实现不得针对单次调用静默改变这些期限。
内部期限届满时,引擎根据执行操作是否已经开始,以及能否形成可信输出,按以下规则处理:
- 执行操作尚未开始时,返回
EngineError。 - 执行操作已经开始且仍能形成可信输出时,在
RunOutput中记录超时、未知或不可取得事实,并继续完成其他有界收集。 - 无法形成结构完整、来源可信的输出时,返回
EngineError。
因此,没有 execution_timeout_ms 只表示 Program 执行区间没有期限,不表示 RunEngine 的准备、停止、捕获或清理操作可以永久阻塞。
结果收集
所有 Program 都已结束、确认没有启动,或者强制终止后的确认期限已经届满时,引擎进入有界结果收集:
- 完成标准流排空并记录 EOF、截断或读取错误。
- 记录每个 Program 实际接收的
stdin字节数,以及输入写端是否成功关闭。 - 只在能够证明不会再有进程使用相应文件系统时,移除
bind mount、proc、tmpfs等运行时文件系统。 capture_final_environment为真时,从稳定的受控rootfs构造每个 Program 的最终 OCI Image,或记录无法取得的原因;为假时不执行捕获并记录not_requested。- 清理本次调用创建的
bundle、Runtime 对象、进程、网络和其他临时资源。
捕获或清理失败不能抹去已经取得的进程和标准流事实。只要仍能形成符合协议的输出,引擎就返回 Ok(RunOutput),并在相应位置记录错误或不可用结果。
何时返回 EngineError
启动任何 Program 前发现输入无效或能力不足,直接返回 EngineError,此时没有 RunOutput。
执行已经开始后,引擎应优先返回包含失败事实的 RunOutput。只有引擎无法构造结构完整、来源可信的输出时,才返回 EngineError。如果引擎进程意外终止或宿主机停止运行,调用可能没有机会返回任何值。Result 只表示实际返回的协议结果。