Executor

Execution capabilities run commands with explicit streams and process status. An Executor additionally manages immutable images and isolated sessions; Process is the narrower command capability. Callers select the backend and supply execution policy.

Source and concrete API: executor.go.

Properties

Process: synchronous command execution and cancellation without requiring image management.
Image: immutable ID, architecture and operating system.
Spec: selected image, network policy, lifetime-process arguments and mounts.
Mount: an existing host path, an execution path and read-only policy. The caller owns the host path for the session lifetime.
Command: literal arguments, working directory, environment additions and stdin.
Streams: caller-owned output writers. Result: process exit status, separate from launch or transport failure.

Behavior

Process.Run executes a literal command, waits for completion and releases its launched process on cancellation. Nonzero status is a Result; launch, transport and cancellation failures are errors. Each backend defines its base environment and filesystem policy.

InspectImage returns the resolved local identity or ErrImageUnavailable. A daemon or transport failure is not evidence that an image is absent. PullImage acquires the selected platform image while preserving process output.

Open creates a session with exactly the supplied process and filesystem policy. No shell, working paths or distribution conventions are implied.

Session.Run executes a command and distinguishes nonzero process status from a failure to launch it. Explicit environment entries augment the container environment; a caller needing a clean environment must request it explicitly.

Session.Snapshot captures the writable image layer. Mounted contents remain external. Session.Close stops owned processes and releases resources even after the original context has been cancelled.

Lifetime and concurrency

Implementations permit independent sessions to run concurrently; calls on the same session remain serial. Shared mounts and output sinks require caller-supplied coordination. Writers are neither closed nor retained by the implementation. Output delivery is serialized within each run or pull; callers sharing writers across concurrent sessions must synchronize them. The session owns execution resources, while mounts and stream lifetimes remain caller-owned.

Backend

The Docker backend implements image and session operations. The host backend implements Process using the controlling machine. A host process is not presented as a container with fake image or snapshot operations.