executor

type Cmd struct {
	// Args is the full argument vector; Args[0] is the program. There is no
	// shell in between: a caller that wants shell semantics asks for a shell.
	Args []string
	// Env adds to, and overrides, the sandbox environment for this command.
	Env map[string]string
	// Dir is relative to the sandbox working directory. Empty means that
	// directory itself.
	Dir string
	// Stdin, Stdout and Stderr are optional. A nil Stdin reads EOF; nil
	// outputs are discarded.
	Stdin          io.Reader
	Stdout, Stderr io.Writer
}

type Executor interface {
	// Acquire returns a sandbox matching spec, ready to run commands.
	Acquire(ctx context.Context, spec Spec) (Sandbox, error)
	// Capabilities is what this backend can honestly grant. A backend that
	// cannot enforce a capability must not advertise it.
	Capabilities() []dholev1.Capability
	// Kind is the backend's stable identifier, as configuration names it.
	Kind() string
	// EnvironmentIdentity is the digest of the environment a sandbox acquired
	// with an EMPTY Spec would run in — this backend's own default, and
	// nothing about any particular step. A backend with no reproducible
	// environment returns ErrNoStableIdentity and an empty string.
	//
	// It is what an engine announces on registration and what its tier's cache
	// keys are hashed against (ADR 0021): the plane needs one identity per
	// tier before it dispatches anything, and it cannot acquire a sandbox on
	// another machine to ask. A step that names its OWN image is a different
	// environment from this one, and cache.StepEnvironment keys it against
	// what the step named instead.
	EnvironmentIdentity() (string, error)
}

type LeaseScope string

type Requirements struct {
	// OS and Arch name the target platform, in Go's GOOS/GOARCH vocabulary.
	// Empty means the step does not care.
	OS   string
	Arch string
	// Capabilities the step needs the sandbox to grant. An executor that does
	// not advertise one cannot be given the step.
	Capabilities []dholev1.Capability
	// EngineType is the executor KIND the step must run on — "process",
	// "kubernetes", "containerd" — matched against the kinds an engine
	// registered. Empty means the step does not care.
	//
	// Placement had no other lever than capability before this: a pipeline
	// that needed a pod asked for NETWORK and hoped, and a step that had to be
	// a host process could not be expressed at all.
	EngineType string
}

type Sandbox interface {
	// Exec runs a command to completion and returns its exit code. A command
	// that runs and exits non-zero is not an error: err is reserved for the
	// sandbox failing to run it at all.
	Exec(ctx context.Context, cmd Cmd) (exitCode int32, err error)
	// Put writes a file into the sandbox under name, a path relative to the
	// sandbox root. It never escapes that root.
	Put(ctx context.Context, name string, r io.Reader) error
	// Get reads a file back out. The caller closes the reader.
	Get(ctx context.Context, name string) (io.ReadCloser, error)
	// Mkdir creates a directory in the sandbox under name, a path relative to
	// the sandbox root, together with any parent it needs. It never escapes
	// that root, and creating one that already exists is not an error.
	//
	// It exists because a step's output ports live under outputs/ (see
	// docs/wire-contract.md, "Port layout on disk") and nothing else creates
	// that directory: a step whose command is `... > outputs/copy` failed
	// with "No such file or directory" on every backend, which reads as a
	// broken pipeline rather than as a missing sandbox convention. Put
	// creates the parents of a FILE it is given, and an output port has no
	// file until the step writes one.
	Mkdir(ctx context.Context, name string) error
	// Signal delivers sig to everything the sandbox is currently running. It
	// is not an error to signal an idle sandbox.
	Signal(ctx context.Context, sig Signal) error
	// Release tears the sandbox down. It is idempotent: releasing an already
	// released sandbox is not an error, so cleanup paths can be unconditional.
	Release(ctx context.Context) error
	// EnvironmentIdentity is a digest of the environment THIS sandbox runs
	// commands in — the resolved digest of the image it was acquired with, a
	// VM snapshot id — used as a cache key input. A sandbox with no
	// reproducible environment returns ErrNoStableIdentity and an empty
	// string.
	//
	// It lives here because this is where the environment is. Identity used to
	// be a property of the executor alone, and for a container backend it is
	// not: the image comes off the Spec, so one Kubernetes executor asked
	// about two steps running two different images answered with the digest of
	// its configured pod template both times. The two steps then hashed to one
	// cache key, and a content-addressed cache that collides hands one step's
	// outputs back as another step's result.
	EnvironmentIdentity() (string, error)
}

type Signal string

type Spec struct {
	// Image is a hint. Backends that have a notion of an image resolve it;
	// those that do not — the process backend, a bare VM — ignore it. It is
	// never an error to ask for one a backend cannot use.
	Image string
	// Env is the base environment every command in the sandbox inherits. A
	// Cmd may add to or override it.
	Env map[string]string
	// WorkDir is the directory commands start in, interpreted by the backend.
	// Empty means the sandbox root.
	WorkDir string
	// Lease is how long the sandbox lives. The zero value means LeaseStep.
	Lease LeaseScope
	// Requirements the sandbox must satisfy.
	Requirements Requirements
}