Documentation
¶
Overview ¶
Package realization translates a backend-neutral sandbox.Spec into the intermediate representation a container backend needs to build a `docker create` call: volumes/binds, tmpfs mounts, environment, working directory and argv (docs/plans/phase6-container-backend.md §PR3).
sandbox.Spec is role-neutral but not backend-neutral (see the plan doc's 現状棚卸し section: "`sandbox.Spec` は role 非依存だが backend 非依存でない"): Mount.Source is always a host path in the current (userns) callers, Mount.Guard/DetectType are shell-idiom escape hatches the userns runner's generated shell script understands, and `/workspace/<name>` is bound to a host runtime directory (`internal/dispatcher/sandbox_builder.go`'s cloneMounts). Realize narrows the translation to what a container backend actually needs and classifies every Mount's Source into one of three kinds (MountSource) so a docker-out-of-docker (DooD) sibling `docker create` call can tell a host bind apart from a container-local directory apart from a named volume (決定 4's DooD path 境界).
Realize is a pure function (no docker API calls, no filesystem access, no process execution) and this package imports no docker SDK type, but it is not scaffolding: containerBackend.Launch calls it on every dispatch (internal/dispatcher/container_backend.go), and the userns backend this package was originally written alongside no longer exists — PR-4 of docs/plans/volume-only-daemon.md (§論点e) removed it, leaving the container backend as boid's only one. The purity is a property worth keeping rather than a sign nothing uses it: it is what lets this package's unit tests pin the whole translation contract without an engine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MountSource ¶
type MountSource struct {
Kind MountSourceKind
Value string
}
MountSource is the classified form of a sandbox.Mount's Source field: Kind says which of the three shapes it is, Value carries the volume name / host absolute path / container-local path accordingly.
type MountSourceKind ¶
type MountSourceKind int
MountSourceKind classifies where a translated mount's content actually comes from — the three shapes a container backend's bind source can take (決定 4, DooD path 境界).
const ( // MountSourceNamedVolume is a docker-managed named volume, e.g. // "boid-ws-home-01234567-default". // // The kind was added ahead of any producer (Phase 6 決定 4 kept workspace // HOME a host bind, and the #813 draft's "named volume 化" call was // reverted as a correction on 2026-07-22), specifically so that a later // change could opt a mount into it without touching this package. PR6 of // docs/plans/workspace-home-volume-persistence.md collected on that: the // workspace HOME mount's Source is now // dockerres.WorkspaceHomeVolumeName(installID, slug) — a name, not a path // — and dispatcher.homeMounts is the producer. It is still spelled as an // ordinary sandbox.MountBind; classifySource's "does not start with /" // rule below is the whole of the opt-in (論点 e option (i)). MountSourceNamedVolume MountSourceKind = iota // MountSourceHostPath is a host absolute path bind. Per the DooD path // 境界 (決定 4, codex Blocker 2): the sibling `docker create` bind // source is resolved by the *host* docker daemon, not the daemon // container's own mount namespace, so this must be a path that resolves // identically inside the daemon container and on the host (the daemon // container's persistent volumes — workspace HOME, clone reference // `.git` dirs — are deliberately laid out at matching absolute paths for // exactly this reason; see 決定 4's "起動時に検証" note, enforced // elsewhere, not by this package). MountSourceHostPath // MountSourceContainerLocal has no host-side counterpart at all: either // it is created fresh inside the container (the `/workspace/<name>` // clone target — 決定 4/10) or the caller supplied a mount with no // Source to back it. MountSourceContainerLocal )
func (MountSourceKind) String ¶
func (k MountSourceKind) String() string
String renders k for diagnostics and test failure messages.
type Realization ¶
type Realization struct {
// ID mirrors sandbox.Spec.ID (the job id), carried through unchanged so
// callers can label the eventual container/volume/network resources
// (`boid.job_id`, 決定 6/9) without re-threading the Spec.
ID string
Volumes []VolumeMount
Tmpfs []TmpfsMount
// Env is spec.Env carried through verbatim — including secrets such as
// BOID_BROKER_TOKEN. This intentionally does NOT apply the
// allowlist-redact pattern internal/sandbox/runner/state.go's redactEnv
// uses for the diagnostic runner-state.json dump: that redaction exists
// only for a diagnostic artifact, never for the value actually handed to
// the running process. The userns backend hands spec.Env to the runner
// unredacted for the same reason (it needs the real broker token to
// register); a container backend needs the same real values on `docker
// create`'s Env. A future container-backend diagnostic dump (PR7 territory,
// 決定 8) should apply the same allowlist-redact convention as
// state.go's redactEnv — but that is a separate, not-yet-existing
// artifact, not this field.
Env map[string]string
// Workdir is spec.WorkDir carried through unchanged (docker create's
// WorkingDir).
Workdir string
// Argv is spec.Argv carried through unchanged (docker create's Cmd).
Argv []string
// TTY mirrors spec.TTY (docker create's Tty).
TTY bool
}
Realization is the container-backend-neutral intermediate representation Realize produces from a sandbox.Spec. It is deliberately not a docker SDK type (no docker/docker/client import in this package — that wiring is PR5's job): a future containerBackend converts a Realization into the concrete docker create/start call.
func Realize ¶
func Realize(spec sandbox.Spec) (Realization, error)
Realize translates spec into a Realization. It is a pure function: no docker API calls, no filesystem access, no side effects. Returns an error if spec contains a Mount with an empty Target — every other field on Spec this package reads is copied through as-is.
Deliberately out of scope (left for the container entrypoint / PR5 to consume from Spec directly, unchanged, or for a later PR — see the plan doc's 決定 section for where each lives):
- spec.Files / spec.Symlinks: already backend-neutral (sandbox-internal path + content/target, no host dependency) — 決定 2 has the container entrypoint apply these directly from Spec, no translation needed.
- spec.ProxyPort: userns-specific (nft + pasta). Container egress is an L3 network-topology concern (internal network + egress proxy, 決定 5), not a per-mount/env translation.
- spec.RootDir / spec.CleanupPaths / spec.Profile: userns runner bookkeeping with no container-backend equivalent (rootfs + cleanup are the container runtime's job once the container is removed).
- spec.Clone: consumed directly by the container entrypoint's in-container clone step (決定 2/10), not part of the docker create call this package targets.
type TmpfsMount ¶
TmpfsMount is a tmpfs mount translated for a container backend (docker --tmpfs / Mounts entry with Type: "tmpfs"). sandbox.Mount never sets Source for a tmpfs entry (see sandbox.Mount's doc comment: "host path (empty for tmpfs)"), so there is no MountSource to classify here.
Guard is carried through from sandbox.Mount unchanged (same fixed contract as VolumeMount.Guard — see below): userns evaluates it before every mount, tmpfs or bind alike, so a tmpfs entry whose Guard is non-empty is skipped when the guard expression is false. Losing Guard here would let the container backend materialize a tmpfs mount that userns would have suppressed, silently diverging behavior.
type VolumeMount ¶
type VolumeMount struct {
Source MountSource
Target string // absolute path inside the container
ReadOnly bool
// IsFile carries sandbox.Mount.IsFile through unchanged — docker infers
// file-vs-directory from the host path itself for a bind mount, so this
// is informational for PR5 (e.g. to decide whether a container-local
// target needs `touch` instead of `mkdir -p` before use), not consumed
// by Realize.
IsFile bool
// Guard and DetectType are carried through from sandbox.Mount unchanged
// but are not evaluated by Realize (決定 the PR3 plan text asks to
// "固定": Guard/DetectType の扱いを固定). Both are userns-runner shell
// idioms — Guard renders a `[ <expr> ]`-gated shell block, DetectType
// picks bind-vs-rbind and file-vs-dir at runtime via test(1) — that make
// sense for a generated mount shell script but not for a `docker
// create` Binds/Mounts list, which either mounts a path or doesn't.
// Fixed contract for PR5: a mount with a non-empty Guard needs the guard
// condition evaluated by the container backend itself, on the host side,
// before deciding whether to include the entry in the docker create call
// at all (docker does not skip missing bind sources the way the userns
// runner's generated `if`-guard does) — Realize does not perform host
// filesystem checks, so it leaves Guard on the struct rather than
// silently dropping or silently applying it. DetectType similarly stays
// informational: docker bind mounts do not distinguish file vs directory
// the way the userns rbind+remount idiom needs to.
Guard string
DetectType bool
}
VolumeMount is a single bind-style mount translated for a container backend's `docker create` call (docker Binds / Mounts entry).