realization

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 3 Imported by: 0

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.

sandbox.Spec is role-neutral but not backend-neutral: Mount.Guard/DetectType are shell-idiom escape hatches, 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.

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). 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.

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.
  • spec.Clone: consumed directly by the container entrypoint's in-container clone step, not part of the docker create call this package targets.

type TmpfsMount

type TmpfsMount struct {
	Target   string
	ReadOnly bool
	Guard    string
}

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL