realization

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 3 Imported by: 0

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

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