dockerclient

package
v0.16.2 Latest Latest
Warning

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

Go to latest
Published: Apr 24, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package dockerclient wraps the moby Go SDK (github.com/moby/moby/client) to manage sandbox containers for the docker sandbox backend. The client is configured from the process environment (DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH, DOCKER_API_VERSION) via client.FromEnv; DOCKER_CONTEXT is intentionally not supported — it's a CLI-only concept.

Index

Constants

View Source
const (
	LabelSessionID = "anna.sandbox.session_id"
	LabelAnnaHome  = "anna.sandbox.anna_home"
	LabelCreatedAt = "anna.sandbox.created_at" // RFC3339
	LabelOwnerPID  = "anna.sandbox.owner_pid"  // PID of the creating anna process
)

Variables

This section is empty.

Functions

func CleanupOrphanedContainers

func CleanupOrphanedContainers(ctx context.Context, c *Client, annaHome string)

CleanupOrphanedContainers force-removes anna-labeled containers whose owning process is clearly gone:

  • dead-state containers (exited, dead, created) are always removed
  • running / paused containers are removed only when their owner_pid label points to a process that no longer exists on this host — this keeps peer anna processes with live sessions safe from another anna startup
  • transitional states (restarting, …) fall back to an age cutoff so truly-hung containers eventually clear

Best-effort: errors are logged, not returned.

Types

type API

type API interface {
	ServerVersion(ctx context.Context, opts mobyclient.ServerVersionOptions) (mobyclient.ServerVersionResult, error)
	ImageInspect(ctx context.Context, image string, opts ...mobyclient.ImageInspectOption) (mobyclient.ImageInspectResult, error)
	ImagePull(ctx context.Context, ref string, opts mobyclient.ImagePullOptions) (mobyclient.ImagePullResponse, error)

	ContainerCreate(ctx context.Context, opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error)
	ContainerStart(ctx context.Context, container string, opts mobyclient.ContainerStartOptions) (mobyclient.ContainerStartResult, error)
	ContainerStop(ctx context.Context, container string, opts mobyclient.ContainerStopOptions) (mobyclient.ContainerStopResult, error)
	ContainerRemove(ctx context.Context, container string, opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error)
	ContainerInspect(ctx context.Context, container string, opts mobyclient.ContainerInspectOptions) (mobyclient.ContainerInspectResult, error)
	ContainerList(ctx context.Context, opts mobyclient.ContainerListOptions) (mobyclient.ContainerListResult, error)

	ExecCreate(ctx context.Context, container string, opts mobyclient.ExecCreateOptions) (mobyclient.ExecCreateResult, error)
	ExecAttach(ctx context.Context, execID string, opts mobyclient.ExecAttachOptions) (mobyclient.ExecAttachResult, error)
	ExecInspect(ctx context.Context, execID string, opts mobyclient.ExecInspectOptions) (mobyclient.ExecInspectResult, error)

	Close() error
}

API is the subset of moby/moby/client.APIClient this package uses. Kept narrow so tests can substitute a fake without pulling the full SDK surface.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps a moby SDK client. Constructed from environment (DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY); see the moby client docs for the full list.

func New

func New() (*Client, error)

New returns a Client configured from the process environment. API-version negotiation is enabled by default in the moby SDK.

func NewWithAPI

func NewWithAPI(api API) *Client

NewWithAPI constructs a Client with an injected API implementation. The moby SDK's *client.Client already satisfies API; callers typically use New() instead. Exported for tests and advanced callers that want to override the SDK client (e.g. to inject a TLS-wrapped instance).

func (*Client) Close

func (c *Client) Close() error

Close releases any resources held by the client (HTTP connections, etc.).

func (*Client) ContainerAlive

func (c *Client) ContainerAlive(ctx context.Context, containerID string) (bool, error)

ContainerAlive reports whether the container is running. Returns (false, nil) when the container no longer exists.

func (*Client) CreateAndStart

func (c *Client) CreateAndStart(ctx context.Context, opts CreateOptions) (string, error)

CreateAndStart creates a container with an always-up sentinel entrypoint (`sh -c 'tail -f /dev/null'`), starts it, and returns the container ID. If the image is not present locally it is pulled automatically.

func (*Client) Exec

func (c *Client) Exec(ctx context.Context, opts ExecOptions) (*ExecResult, error)

Exec runs a blocking exec, collecting stdout/stderr into memory.

func (*Client) ImageExists

func (c *Client) ImageExists(ctx context.Context, image string) (bool, error)

ImageExists reports whether the image exists locally. Returns false (no error) when the daemon reports not-found; any other error surfaces.

func (*Client) PullImage

func (c *Client) PullImage(ctx context.Context, image string) error

PullImage pulls an image, draining the JSON progress stream into slog.Info.

func (*Client) StartExec

func (c *Client) StartExec(ctx context.Context, opts ExecOptions) (*ExecHandle, error)

StartExec is the streaming variant: returns stdout/stderr pipes and a Wait() that blocks until the exec finishes and returns its exit code.

func (*Client) Stop

func (c *Client) Stop(ctx context.Context, containerID string) error

Stop sends SIGTERM with a 2-second grace period, then removes the container. Missing-container errors are swallowed so Close is idempotent.

func (*Client) Version

func (c *Client) Version(ctx context.Context) (*VersionInfo, error)

Version queries the daemon for server + client version info. Used by preflight to confirm daemon reachability.

type CreateOptions

type CreateOptions struct {
	Image          string
	WorkspaceHost  string      // absolute host path (daemon-side)
	WorkspaceMount string      // absolute in-container path (e.g. "/home/anna/workspace")
	ReadOnlyMounts []Mount     // host -> container, read-only
	NetworkMode    NetworkMode // disabled | allow_all
	Env            map[string]string
	Labels         map[string]string // must include LabelSessionID + LabelAnnaHome + LabelCreatedAt
	Name           string            // optional; caller builds "anna-sandbox-<session-id>"
}

CreateOptions configures a new sandbox container.

type ExecHandle

type ExecHandle struct {
	// Stdin is non-nil only when opts.Stdin was nil (i.e. we opened a pipe for the caller).
	Stdin  io.WriteCloser
	Stdout io.ReadCloser
	Stderr io.ReadCloser
	// Wait blocks until the exec finishes and returns the exit code.
	Wait func() (int, error)
	// Kill terminates the underlying exec attach.
	Kill func() error
}

ExecHandle is the streaming variant returned by StartExec.

type ExecOptions

type ExecOptions struct {
	ContainerID string
	Command     []string // argv — not a shell string
	Cwd         string   // absolute in-container path
	Env         map[string]string
	User        string    // optional override
	Stdin       io.Reader // optional
	Tty         bool      // default false
}

ExecOptions configures a docker exec call.

type ExecResult

type ExecResult struct {
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

ExecResult holds the result of a blocking Exec call.

type Mount

type Mount struct {
	HostPath      string
	ContainerPath string
	ReadOnly      bool
}

Mount represents a bind-mount from host to container. Source is interpreted by the daemon, so when anna runs inside a container it must already be translated to a daemon-visible path before reaching this struct.

type NetworkMode

type NetworkMode string

NetworkMode controls the container's network access.

const (
	NetworkDisabled NetworkMode = "disabled"
	NetworkAllowAll NetworkMode = "allow_all"
)

type VersionInfo

type VersionInfo struct {
	Server struct {
		APIVersion string
	}
	Client struct {
		Version string
	}
}

VersionInfo holds the minimal version data we care about. The shape is kept stable across the CLI→SDK migration so callers don't churn.

Jump to

Keyboard shortcuts

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