Documentation
¶
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.
const ( // MountSourceNamedVolume is a docker-managed named volume, e.g. // "boid-ws-home-01234567-default". The workspace HOME mount's Source is // 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. MountSourceNamedVolume MountSourceKind = iota // MountSourceHostPath is a host absolute path bind. 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, 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) 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`) 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 — a container backend needs the real values on
// `docker create`'s Env.
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): 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 to consume from Spec directly, unchanged):
- spec.Files / spec.Symlinks: already backend-neutral (sandbox-internal path + content/target, no host dependency) — the container entrypoint applies these directly from Spec, no translation needed.
- spec.ProxyPort: container egress is an L3 network-topology concern (internal network + egress proxy), not a per-mount/env translation.
- spec.RootDir / spec.CleanupPaths / spec.Profile: rootfs + cleanup are the container runtime's job once the container is removed.
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 the container backend (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. Both are 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. 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 — 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 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).