Documentation
¶
Overview ¶
Package docker is the container capability: the Docker Engine reached over its API socket, granted to the code that runs containers.
It wraps the upstream Docker Engine SDK client (github.com/moby/moby/client) rather than the docker CLI run through ipc/proc. The SDK is already the client CSF's local simulations consume, it is typed end to end (no parsing of CLI output), and it gives the owner of a container its whole lifecycle — create, wait, start, kill, logs, remove — as separate calls, which is what cleanup on cancellation needs. Talking to the Engine socket is a kernel I/O crossing, so the client is constructed here, under ipc, and nowhere else.
A binary constructs one ContainerHost and passes it to whatever runs containers. Consumers that need only part of the Engine API declare their own narrow interface, which ContainerHost satisfies; ContainerHost.RunSandboxed is the bounded, isolated run-to-completion that sandboxed evaluation and the node executor are built on.
Index ¶
Constants ¶
const ( // DefaultOutputBytes bounds each captured output stream of a sandboxed run. DefaultOutputBytes = 1 << 20 // DefaultPidsLimit bounds the processes a sandboxed container may create. DefaultPidsLimit = 256 // RemoveTimeout bounds the cleanup that removes a finished or canceled // sandbox, which runs even after the caller's context has ended. RemoveTimeout = 30 * time.Second )
Variables ¶
var ( // ErrImageRequired is returned for a sandbox spec without an image. ErrImageRequired = errors.New("ipc/docker: sandbox image is required") // ErrInvalidOption is returned by NewContainerHost for a nil, empty or // conflicting option. ErrInvalidOption = errors.New("ipc/docker: invalid container host option") )
Functions ¶
This section is empty.
Types ¶
type ContainerHost ¶
type ContainerHost struct {
IContainerAPI
// contains filtered or unexported fields
}
ContainerHost is the Docker Engine granted as a capability. Its Engine API methods are promoted from the client it wraps, so it satisfies a consumer's narrow interface directly.
func NewContainerHost ¶
func NewContainerHost(options ...ContainerHostOption) (*ContainerHost, error)
NewContainerHost connects the container capability. Construction does not contact the Engine; the first call does.
func (*ContainerHost) RunSandboxed ¶
func (host *ContainerHost) RunSandboxed(ctx context.Context, spec SandboxSpec) (result SandboxResult, err error)
RunSandboxed creates the container, starts it, waits for it to exit and collects its output, then removes it. The container is removed on every path — success, failure, and cancellation, which kills it first — so a sandbox never outlives the call. A nonzero exit returns the result together with an *ExitError.
type ContainerHostOption ¶
type ContainerHostOption func(settings *containerHostSettings) error
ContainerHostOption configures a ContainerHost.
func WithContainerAPI ¶
func WithContainerAPI(api IContainerAPI) ContainerHostOption
WithContainerAPI supplies an already-constructed Engine client, which the host then owns and closes.
func WithDockerHost ¶
func WithDockerHost(host string) ContainerHostOption
WithDockerHost names the Engine endpoint, such as unix:///var/run/docker.sock. The default is the SDK's platform default; the environment is never read.
func WithOutputBytes ¶
func WithOutputBytes(limit int64) ContainerHostOption
WithOutputBytes bounds each captured output stream of a sandboxed run.
type IContainerAPI ¶
type IContainerAPI interface {
ContainerCreate(ctx context.Context, options client.ContainerCreateOptions) (client.ContainerCreateResult, error)
ContainerInspect(ctx context.Context, id string, options client.ContainerInspectOptions) (client.ContainerInspectResult, error)
ContainerStart(ctx context.Context, id string, options client.ContainerStartOptions) (client.ContainerStartResult, error)
ContainerStop(ctx context.Context, id string, options client.ContainerStopOptions) (client.ContainerStopResult, error)
ContainerKill(ctx context.Context, id string, options client.ContainerKillOptions) (client.ContainerKillResult, error)
ContainerWait(ctx context.Context, id string, options client.ContainerWaitOptions) client.ContainerWaitResult
ContainerRemove(ctx context.Context, id string, options client.ContainerRemoveOptions) (client.ContainerRemoveResult, error)
ContainerLogs(ctx context.Context, id string, options client.ContainerLogsOptions) (client.ContainerLogsResult, error)
ContainerList(ctx context.Context, options client.ContainerListOptions) (client.ContainerListResult, error)
ImageList(ctx context.Context, options client.ImageListOptions) (client.ImageListResult, error)
ImagePrune(ctx context.Context, options client.ImagePruneOptions) (client.ImagePruneResult, error)
BuildCachePrune(ctx context.Context, options client.BuildCachePruneOptions) (client.BuildCachePruneResult, error)
DiskUsage(ctx context.Context, options client.DiskUsageOptions) (client.DiskUsageResult, error)
Close() error
}
IContainerAPI is the part of the Docker Engine API client this capability uses and hands on. *client.Client satisfies it; a test substitutes a double.
type SandboxResult ¶
type SandboxResult struct {
ContainerID string
ExitCode int64
Stdout []byte
Stderr []byte
StdoutTruncated bool
StderrTruncated bool
}
SandboxResult is what a finished sandbox left behind.
type SandboxSpec ¶
type SandboxSpec struct {
Image string
Command []string
Environment []string
WorkingDirectory string
User string
Mounts []Mount
Labels map[string]string
// Network is a Docker network mode; empty means no network at all.
Network string
// MemoryBytes and NanoCPUs are resource limits; zero means unlimited.
MemoryBytes int64
NanoCPUs int64
// PidsLimit bounds process creation; zero means [DefaultPidsLimit].
PidsLimit int64
// WritableRoot leaves the root filesystem writable.
WritableRoot bool
}
SandboxSpec is one isolated run to completion. Unset limits fall back to the sandbox defaults: no network, every capability dropped, no privilege escalation, a read-only root filesystem with a small /tmp, an init process, and DefaultPidsLimit.
Source Files