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
- func CleanupOrphanedContainers(ctx context.Context, c *Client, annaHome string)
- type API
- type Client
- func (c *Client) Close() error
- func (c *Client) ContainerAlive(ctx context.Context, containerID string) (bool, error)
- func (c *Client) CreateAndStart(ctx context.Context, opts CreateOptions) (string, error)
- func (c *Client) Exec(ctx context.Context, opts ExecOptions) (*ExecResult, error)
- func (c *Client) ImageExists(ctx context.Context, image string) (bool, error)
- func (c *Client) InspectContainerState(ctx context.Context, containerRef string) (*ContainerState, error)
- func (c *Client) PullImage(ctx context.Context, image string) error
- func (c *Client) StartExec(ctx context.Context, opts ExecOptions) (*ExecHandle, error)
- func (c *Client) Stop(ctx context.Context, containerID string) error
- func (c *Client) Version(ctx context.Context) (*VersionInfo, error)
- func (c *Client) VolumeCreate(ctx context.Context, opts mobyclient.VolumeCreateOptions) (mobyclient.VolumeCreateResult, error)
- type ContainerState
- type CreateOptions
- type ExecHandle
- type ExecOptions
- type ExecResult
- type Mount
- type MountType
- type NetworkMode
- type VersionInfo
Constants ¶
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 ¶
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)
VolumeCreate(ctx context.Context, opts mobyclient.VolumeCreateOptions) (mobyclient.VolumeCreateResult, 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 ¶
New returns a Client configured from the process environment. API-version negotiation is enabled by default in the moby SDK.
func NewWithAPI ¶
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) ContainerAlive ¶
ContainerAlive reports whether the container is running. Returns (false, nil) when the container no longer exists.
func (*Client) CreateAndStart ¶
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 ¶
ImageExists reports whether the image exists locally. Returns false (no error) when the daemon reports not-found; any other error surfaces.
func (*Client) InspectContainerState ¶ added in v0.17.0
func (c *Client) InspectContainerState(ctx context.Context, containerRef string) (*ContainerState, error)
InspectContainerState returns the running state and exit code of a container referenced by ID or name. Returns (nil, nil) when the container does not exist.
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 ¶
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.
func (*Client) VolumeCreate ¶ added in v0.17.0
func (c *Client) VolumeCreate(ctx context.Context, opts mobyclient.VolumeCreateOptions) (mobyclient.VolumeCreateResult, error)
PullImage pulls an image, draining the JSON progress stream into slog.Info.
type ContainerState ¶ added in v0.17.0
ContainerState holds the container running state and last exit code.
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
User string // optional container user override
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 ¶
ExecResult holds the result of a blocking Exec call.
type Mount ¶
Mount represents a mount from a daemon-visible source to a container path. Bind mount sources are interpreted by the daemon, so when anna runs inside a container they must already be translated to daemon-visible paths before reaching this struct. Volume mount sources are Docker volume names.
type MountType ¶ added in v0.17.0
type MountType string
MountType identifies how Docker should mount Source into the container.
type NetworkMode ¶
type NetworkMode string
NetworkMode controls the container's network access.
const ( NetworkDisabled NetworkMode = "disabled" NetworkAllowAll NetworkMode = "allow_all" )
type VersionInfo ¶
VersionInfo holds the minimal version data we care about. The shape is kept stable across the CLI→SDK migration so callers don't churn.