Skip to main content

Module exec_mount

Module exec_mount 

Source
Expand description

/exec/instances/ VFS mount — projects SandboxPool’s active sandboxes as a Plan9 /proc-style tree.

This is the P2 slice of epic #608 (“P9 Task/Instance Projection”); see epic #608 for the full /exec tree this is one branch of (/exec/instances/<id>/...).

Layout:

  • /exec/instances/ — dynamic dir: active sandbox/instance ids
  • /exec/instances/<id>/ctl — ctl file: write a verb to drive the instance’s lifecycle (see [Verb] for the grammar)
  • /exec/instances/<id>/status — read-only: current PodSandboxState, live/non-blocking poll of pool state
  • /exec/instances/<id>/exit — read-only: blocks until the instance is terminal, then returns the terminal status. A read that starts after the instance has already terminated returns immediately with the retained status (read-then-subscribe, no missed completions).
  • /exec/instances/<id>/ns — read-only: best-effort textual listing of the sandbox’s mount-prefixes/namespace, or an empty placeholder
  • /exec/instances/<id>/fd/1,2 — bounded terminal stdout/stderr streams

fd/ is a bounded task-local adapter over the existing MoQ stream substrate. It deliberately exposes no socket or host-path escape hatch. fd/0 stays absent until a backend task interface can consume it: accepting bytes into an unobserved buffer would violate the Plan 9 file contract.

§Ctl verb grammar

Writes to <id>/ctl are UTF-8, one verb per write (Plan9-style short text commands, not a structured protocol):

verbeffect
startno-op today — sandboxes are started by SandboxPool::acquire;
accepted for grammar completeness/forward-compat, returns ok
if the instance exists and is not already terminal.
stopcalls SandboxBackend::stop (graceful stop) on the instance.
killalias for stop today (no separate SIGKILL-style path exposed
by SandboxBackend yet); kept distinct in the grammar so a
future hard-kill primitive can be wired without a ctl-format
change.
destroycalls SandboxBackend::destroy, then removes the instance from
the pool’s active map and marks it terminal for exit/status.
execruns an argv-only task through this mount’s SandboxBackend
seam, then latches stdout/stderr in fd/1 and fd/2.

Unknown verbs return MountError::InvalidArgument. A verb may be followed by trailing whitespace, which is trimmed.

Structs§

DenyAllLifecycle
Fail-closed policy: denies every destructive verb for every subject. Installing this arms the mediation point to deny-by-default (e.g. during the #698 dependency window).
ExecMount
VFS mount that projects a SandboxPool’s active sandboxes as /exec/instances/<id>/{ctl,status,exit,ns}.
TaskExecResult
One completed task execution as observed by both the production CRI caller and the Plan 9 fd projection. Keeping this result adjacent to the adapter makes the single-owner contract explicit: neither caller needs to invoke a backend a second time or retain a competing output buffer.

Enums§

LifecycleVerb
The destructive lifecycle verbs a LifecyclePolicy mediates.

Traits§

LifecyclePolicy
Fail-closed authorization seam for destructive ctl lifecycle verbs (#1272, epic #1267 T3).