docker

package
v0.6.10 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 45 Imported by: 0

Documentation

Index

Constants

View Source
const BuiltImageNamespace = "aerolvm-build"

BuiltImageNamespace is the local image-name prefix every Daytona-facade build is tagged with. Keeping every built image under a single namespace makes them trivially identifiable by image GC (pkg/docker/image_gc.go) and keeps them out of the way of pulled images.

View Source
const (
	// GuestReadySocketPath is the in-container path toolboxd dials.
	GuestReadySocketPath = "/run/aerol/ready.sock"
)
View Source
const SnapshotImageNamespace = "aerolvm-snapshot"

SnapshotImageNamespace is the local repository namespace committed snapshots live under. Only SnapshotImageTag names images in it, so a snapshot never shares a tag with an ordinary image or with another snapshot, whatever it is called. (Snapshot names like "snapshots/demo:v1" are a convention callers already use, so that namespace stays theirs.)

Variables

View Source
var ErrClientNotConfigured = errors.New("docker: client has no HTTP transport configured")

ErrClientNotConfigured is returned instead of dereferencing a nil transport. Every caller already handles a request error; a nil dereference here does not stay local, because several callers run on detached janitor goroutines (built-image GC, image GC, the events stream) where a panic takes the whole daemon down rather than failing one sweep.

View Source
var ErrSandboxContainerExists = errors.New("docker: sandbox container name already exists")

ErrSandboxContainerExists is returned when adopt-time rename finds the sandbox name already taken — signals the §6 duplicate-create protocol.

Functions

func BuildTagFor added in v0.1.7

func BuildTagFor(dockerfile string, contextHashes []string) string

BuildTagFor returns the deterministic local image tag for a given Dockerfile + optional context hash list. Same input → same tag → docker build is a no-op on the second call, which is what makes the createImage path idempotent under retries.

func BuildTagForNode added in v0.6.1

func BuildTagForNode(dockerfile string, contextHashes []string, nodeID string) string

BuildTagForNode returns a content-addressed tag whose repository also binds the image to the cluster worker that built it. Local build tags are not portable between workers; carrying the owner in the tag lets the create scheduler route to exactly one worker instead of pre-building on the fleet.

func BuildTagForOwner added in v0.6.7

func BuildTagForOwner(dockerfile string, contextHashes []string, nodeID, ownerNamespace string) string

BuildTagForOwner is BuildTagForNode for a build made for an owner: the owner's namespace (a path segment like "tenant-<hash>") follows the node segment, so one owner's build is never another's tag. The same Dockerfile built for two owners gives two tags, and the build cache never hands one owner's result to the other. An empty namespace is an operator build, tagged as before.

func BuiltImageOwnerNamespace added in v0.6.7

func BuiltImageOwnerNamespace(ref string) string

BuiltImageOwnerNamespace returns the owner namespace of a built image's tag (see BuildTagForOwner), or "" for a build with none: an operator's, or one made before builds had owners.

func BuiltImagePlacementNode added in v0.6.1

func BuiltImagePlacementNode(imageRef string) (string, bool)

BuiltImagePlacementNode extracts the worker affinity from a tag produced by BuildTagForNode. Ordinary single-node build tags intentionally return false.

func CanonicalSnapshotImageTag added in v0.6.9

func CanonicalSnapshotImageTag(ref string) (string, bool)

CanonicalSnapshotImageTag returns the one spelling of a snapshot-namespace ref that SnapshotImageTag produces ("aerolvm-snapshot/<hash>:latest"), so a tag used as a lookup key matches whichever spelling the caller wrote. ok is false for a ref outside the snapshot namespace.

func EnsureReadyDir added in v0.5.5

func EnsureReadyDir(dir string) error

EnsureReadyDir creates the sandboxd-owned ready-socket parent directory.

func EquivalentImageNames added in v0.6.7

func EquivalentImageNames(ref string) []string

EquivalentImageNames returns the spellings the engine treats as the same local image as ref, ref itself first: with and without the implicit docker.io registry (or its index.docker.io alias), with and without the implicit library/ path of an official image, and with and without the implicit :latest tag. A ref that does not parse as a name, or pins a digest, has only itself.

func IsBuiltImageRef added in v0.6.7

func IsBuiltImageRef(ref string) bool

IsBuiltImageRef reports whether ref names an image in BuiltImageNamespace, in any spelling the engine resolves to it ("aerolvm-build/x", "docker.io/aerolvm-build/x", ...).

func IsLocalOnlyImageRef added in v0.2.1

func IsLocalOnlyImageRef(imageRef string) bool

IsLocalOnlyImageRef reports an image only this node can have: a built image, or a snapshot's committed image — including ones committed under a "snapshots/..." name before snapshots had tags of their own.

func IsSnapshotImageRef added in v0.6.7

func IsSnapshotImageRef(ref string) bool

IsSnapshotImageRef reports whether ref names an image in the snapshot namespace, in any spelling the engine resolves to it: "aerolvm-snapshot/x", "docker.io/aerolvm-snapshot/x" and "index.docker.io/aerolvm-snapshot/x:latest" are all the same local image.

func LooksLikeImageID added in v0.6.7

func LooksLikeImageID(ref string) bool

LooksLikeImageID reports a reference the engine would resolve by image id rather than by name: "sha256:<hex>", or a bare lowercase hex string with no registry, path or tag. Docker resolves such a string against image ids by prefix when no image of that name exists, so even a few hex digits can pick out an image the caller was never given a name for.

func MintReadyNonce added in v0.5.6

func MintReadyNonce() (string, error)

MintReadyNonce returns a random nonce for per-create readiness sockets. Exported for the containerd driver, which shares the same push protocol.

func ParkedEnvCredentials added in v0.6.9

func ParkedEnvCredentials(env []string) (bootstrapToken, parkNonce string, parked bool)

ParkedEnvCredentials reads back what EnvVars and the park's bootstrap token put in a container's env. A container adopted from a warm pool keeps that env for life, so each time it starts again its toolboxd boots parked and sends its hello with these, and the host must listen for exactly them to adopt it again. parked is false for any container that was never parked.

func ReadyWaitMS added in v0.5.5

func ReadyWaitMS() int64

ReadyWaitMS returns the most recent successful readiness wait (ms). Exported for tests; production dashboards read the expvar counters above.

func RemoveParkSocket added in v0.5.5

func RemoveParkSocket(path string)

RemoveParkSocket unlinks a park socket path if not active.

func RemoveReadySocketsForSandbox added in v0.5.5

func RemoveReadySocketsForSandbox(dir, sandboxID string)

RemoveReadySocketsForSandbox unlinks any ready sockets keyed to sandboxID.

func SnapshotImageTag added in v0.6.7

func SnapshotImageTag(name string) string

SnapshotImageTag is the local tag a snapshot called name is committed under: `aerolvm-snapshot/<hash of the name>:latest`. The name a caller chooses is only a catalog entry; were it the tag, a snapshot called "python" would replace the python image on its node for everyone. The hash is of the name's canonical spelling, so every spelling of one name (which the catalog treats as one snapshot) gets one tag, and a retried commit lands on the tag the first attempt used.

func SnapshotImageTagForOwner added in v0.6.8

func SnapshotImageTagForOwner(owner, name string) string

SnapshotImageTagForOwner is SnapshotImageTag scoped to an owner: the hash folds in the owning tenant, so two tenants that commit a same-named snapshot on one node get DIFFERENT local tags instead of colliding on one image (a tenant could otherwise boot, or fail over onto, another tenant's committed bytes). owner "" reproduces the legacy owner-agnostic tag, so operator and pre-existing snapshots are unchanged.

func SweepOrphanReadySockets added in v0.5.5

func SweepOrphanReadySockets(dir string) error

SweepOrphanReadySockets removes stale socket files from a prior crash. Paths registered by live creates (activeReadySockets) are skipped.

func SweepOrphanReadySocketsExcept added in v0.5.5

func SweepOrphanReadySocketsExcept(dir string, keep map[string]struct{}) error

SweepOrphanReadySocketsExcept removes stale socket files while preserving paths still referenced by Docker bind mounts. A stopped container cannot restart if its persisted bind source disappears.

func WithSandboxID added in v0.2.3

func WithSandboxID(parent context.Context, sandboxID string) context.Context

WithSandboxID returns a context derived from parent that carries the sandbox identifier the pull is being executed on behalf of. Used by the Create path so the PullObserver fired after a successful private mirror pull can flag the correct row. Empty IDs are ignored.

Types

type AOCRPullAuth added in v0.6.5

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

AOCRPullAuth is the node-local credential the daemon presents when pulling cluster-owned artifacts (snapshots + Firecracker templates) from AOCR. It mirrors the producer-side SnapshotPushConfig: the same cluster PAT authorizes both push (snapshot_push.go / template_push.go) and pull, scoped to the `cluster/<id>/*` namespace by AOCR's auth/src/clusterPat.ts.

Why it is exported rather than private to the Client: both container engines pull AOCR-distributed snapshots on the create path with no caller credential — dockerd through this package (Create / PullImage → pullImageDedup) and native containerd through internal/runtime/containerd's ensureImage. One shared resolver keeps the scoping rules (configured host + `cluster/` repo only) identical across engines, so flipping a node from docker to containerd can neither widen nor lose what the cluster PAT is presented for.

The credential is node config, not user data: it is never sealed, stored on a sandbox row, or forwarded cross-node. Immutable after construction, so concurrent Resolve calls need no lock.

func NewAOCRPullAuth added in v0.6.5

func NewAOCRPullAuth(hosts []string, clusterID, patPath string) *AOCRPullAuth

NewAOCRPullAuth builds the cluster-PAT pull credential, or returns nil (the feature stays off, pulls stay anonymous) when clusterID or patPath is empty or no non-empty host is supplied — the "consume-only node without AOCR creds" case where a public registry needs no auth. A nil *AOCRPullAuth is a valid Resolve receiver, so callers may store the result unconditionally.

func (*AOCRPullAuth) Resolve added in v0.6.5

func (a *AOCRPullAuth) Resolve(imageRef string) (*models.RegistryAuth, error)

Resolve returns the cluster-PAT credential for imageRef when the ref targets a configured AOCR host under the `cluster/` namespace.

  • (nil, nil): out of scope (other host, non-cluster repo, bare Docker Hub ref) or a nil receiver. The pull stays anonymous, which is correct for public images. The PAT file is not read, so an unrelated pull pays no file I/O.
  • (auth, nil): in scope. Server is the ref's host as written, Username the cluster ID, Password the PAT read fresh from disk.
  • (nil, err): in scope, but the PAT file is missing, unreadable, or blank. err names the file path, never its contents; the caller owns the policy (both engines warn and fall back to an anonymous attempt).

type BuildImageRequest added in v0.1.7

type BuildImageRequest struct {
	Tag               string
	DockerfileContent string
	ContextTar        []byte
	OnLog             func(line string)
	// ForcePull resolves every image the build names — FROM, COPY --from,
	// a base image's ONBUILD triggers — from its registry, never from the
	// images already on this node. A build for a tenant sets it: the node
	// holds other tenants' snapshots and builds, and an image name (or a
	// short image id, which the engine also resolves) in a Dockerfile must
	// not reach them.
	ForcePull bool
}

BuildImageRequest is the input to (*Client).BuildImage.

DockerfileContent is mandatory. ContextTar is optional — when nil, the build context contains just the Dockerfile. Tag is the image name to tag the result with; it should already be qualified (e.g. registry/name:tag) if the caller intends to push it.

type BuiltImage added in v0.1.7

type BuiltImage struct {
	// Tag is one of the image's RepoTags, qualified (e.g.
	// "aerolvm-build/abc123:latest").
	Tag string
	// LastTagTime is when the daemon last (re)tagged the image, UTC. Used
	// instead of Image.Created because content-addressed builds can hit the
	// docker layer cache and return an image whose Created timestamp is
	// arbitrarily old. The tag itself, in contrast, is fresh: every
	// successful BuildImage with t=<tag> bumps LastTagTime to "now", and
	// callers that only had a cache-hit explicitly call RefreshTag below.
	LastTagTime time.Time
}

BuiltImage is the slice of Docker's image-list payload that the built-image janitor needs: one of the locally-built image's RepoTags (always in the BuiltImageNamespace) plus when the daemon last (re)tagged it. Multiple RepoTags per image are possible if the same content was tagged twice; we surface each tag as its own BuiltImage so the GC decision is per-tag.

type Client

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

func New

func New(logger *slog.Logger, cfg config.Config, rules *netrules.Manager) (*Client, error)

func (*Client) ApplyEgressHold added in v0.6.6

func (c *Client) ApplyEgressHold(containerIP string) error

ApplyEgressHold installs the fail-closed hold DROP (CEO D16).

func (*Client) ApplyEgressPolicy added in v0.5.4

func (c *Client) ApplyEgressPolicy(containerIP string, allowCIDRs, denyCIDRs []string) error

ApplyEgressPolicy installs the selective-egress CIDR policy. Idempotent — called on Create (initial install), StartSandbox (after a Stop+Start cycle drops the rules on the stop event), and reconcile (to heal host-side state loss). A no-op when no policy is set or network rules are disabled.

func (*Client) ApplyNetworkBlockAll added in v0.1.5

func (c *Client) ApplyNetworkBlockAll(containerIP string) error

ApplyNetworkBlockAll installs the per-IP egress DROP rule. Idempotent — the underlying rule manager checks for an existing match before inserting. Called on Create (initial install), StartSandbox (after a Stop+Start cycle drops the rule on the stop event), and reconcile (to heal after host-side state loss).

func (*Client) ApplyNetworkBlockAllReport added in v0.5.6

func (c *Client) ApplyNetworkBlockAllReport(containerIP string) (bool, error)

ApplyNetworkBlockAllReport implements runtime.NetworkBlockReporter. inserted is true only when the rule was found missing — reconcile uses that to count isolation drift without paying an extra iptables probe per pass.

func (*Client) ApplyNetworkBlockIngress added in v0.1.7

func (c *Client) ApplyNetworkBlockIngress(containerIP string) error

ApplyNetworkBlockIngress installs the per-IP ingress DROP rule used by the network-quota enforcer when net_bytes_in_limit is crossed. Idempotent.

func (*Client) BuildImage added in v0.1.7

func (c *Client) BuildImage(ctx context.Context, req BuildImageRequest) error

BuildImage drives `POST /build` against the local Docker daemon and tags the resulting image with req.Tag. Streams build progress as NDJSON; if req.OnLog is set, each `stream` chunk is forwarded line-by-line.

Idempotent: tagging the same Dockerfile content+context twice with the same tag is a no-op for the daemon — it returns the cached image hash.

func (*Client) ClearEgressHold added in v0.6.6

func (c *Client) ClearEgressHold(containerIP string) error

ClearEgressHold lifts the hold after a successful gateway attach.

func (*Client) ClearEgressPolicy added in v0.5.4

func (c *Client) ClearEgressPolicy(containerIP string, allowCIDRs, denyCIDRs []string) error

ClearEgressPolicy removes the selective-egress rules for the IP. Called on stop/destroy before Docker recycles the IP — a stale ACCEPT/DROP would otherwise re-attach to whoever next gets this IP from the IPAM pool.

func (*Client) ClearNetworkBlockEgress added in v0.1.7

func (c *Client) ClearNetworkBlockEgress(containerIP string) error

ClearNetworkBlockEgress removes the per-IP egress DROP rule. Symmetric to ApplyNetworkBlockAll. The underlying rule is shared with NetworkBlockAll, so the service must consult sandbox.NetworkBlockAll before invoking this on a quota-clear path — otherwise it would silently undo the operator's egress block.

func (*Client) ClearNetworkBlockIngress added in v0.1.7

func (c *Client) ClearNetworkBlockIngress(containerIP string) error

ClearNetworkBlockIngress removes the per-IP ingress DROP rule. Service layer only calls this when the inbound limit is raised above current usage.

func (*Client) ClearNetworkRules

func (c *Client) ClearNetworkRules(containerIP string) error

ClearNetworkRules releases any per-IP network rules previously attached to a sandbox. Used by the event-driven path when a container exits or is destroyed out-of-band, since Destroy() handles this for us during normal teardown. Clears both egress (NetworkBlockAll / quota egress) and ingress (quota ingress) rules — once the IP is gone there is nothing left to firewall on.

func (*Client) ConfigureAOCRPullAuth added in v0.5.2

func (c *Client) ConfigureAOCRPullAuth(hosts []string, clusterID, patPath string)

ConfigureAOCRPullAuth installs the cluster-PAT pull credential onto an existing Client. A no-op (any prior setting is kept; by default pulls stay anonymous) when NewAOCRPullAuth reports the config incomplete. Called once from the daemon after config load, alongside ConfigureMirror.

func (*Client) ConfigureMirror added in v0.2.3

func (c *Client) ConfigureMirror(cfg MirrorConfig, ring *secrets.UpstreamWrapKeyRing)

ConfigureMirror installs the AOCR mirror policy onto an existing Client. Both arguments are optional: a zero MirrorConfig disables rewriting, and a nil key ring disables identity-token wrapping (the pull falls back to raw username/password in X-Registry-Auth). main() is expected to load the wrap key ring exactly once at startup and hand it in here.

func (*Client) ContainerPID added in v0.1.7

func (c *Client) ContainerPID(ctx context.Context, containerRef string) (int, error)

ContainerPID returns the host PID of a running container's init process. The PID is the entry point into the container's network namespace — /proc/<pid>/net/dev is per-netns, so the netstats poller reads byte counters straight from there with no nsenter / veth-iflink dance. Returns 0 when the container is not running (Docker reports Pid:0 in that case).

func (*Client) ContainerStats added in v0.5.1

func (c *Client) ContainerStats(ctx context.Context, containerRef string) (ContainerStat, error)

ContainerStats returns a one-shot CPU/memory snapshot for a container via the Docker stats endpoint with stream=false — a single cheap request that does not hold the connection open. Callers (the opt-in live usage sampler) bound how often they call it; this method does no rate limiting of its own.

Memory follows `docker stats` working-set semantics: the inactive file cache is subtracted so page cache does not inflate the figure.

func (*Client) Create

func (c *Client) Create(ctx context.Context, req models.CreateSandboxRequest, sandboxID string, toolboxToken string, hostMounts []mounts.ContainerBind) (*SandboxRuntime, error)

Create provisions and starts a managed container. The caller chooses the sandbox ID up-front; we set it as the container's Docker name so the name is the canonical sandbox identifier end-to-end (the container ID is an internal detail). Host-side mounts are passed as bind sources prepared by the mounts manager; sandboxd never writes a mounts.json into the container.

func (*Client) CreateSnapshot added in v0.1.7

func (c *Client) CreateSnapshot(ctx context.Context, containerRef, imageRef string) (string, error)

CreateSnapshot commits a sandbox container into the image imageRef.

A plain Docker commit copies the container's whole env into the image, and that env holds the sandbox's toolbox token and every variable its create passed (API keys included), which AerolVM otherwise keeps sealed. The image is distributed (snapshot push), so it must carry neither:

  1. The commit gets an explicit config: the container's own, with every variable the create added cleared (snapshotEnv). Docker cannot drop a key in a commit (it merges the container's env back for any key the config omits), so cleared keys stay with an empty value.
  2. The graphdriver image store also writes the container's original config, env included, into the image's container_config, whatever the commit's config says. So that commit stays an untagged intermediate, and the tagged image is committed from a helper container created from it, whose own config is already clean. The pushed config is the tagged image's only.

The intermediate is deleted where Docker allows it (the containerd image store). The graphdriver store keeps it as the tagged image's parent, local to this node, and removes it when the snapshot image is deleted.

func (*Client) Destroy

func (c *Client) Destroy(ctx context.Context, sandbox *models.Sandbox) error

func (*Client) ExecCreate

func (c *Client) ExecCreate(ctx context.Context, containerID string, cmd []string, env []string, workdir string, tty bool) (string, error)

ExecCreate creates an exec instance attached to the given container. The returned exec ID must be passed to ExecStart to actually run the command.

func (*Client) ExecInspect

func (c *Client) ExecInspect(ctx context.Context, execID string) (exitCode int, running bool, err error)

ExecInspect returns the exit code and running state of an exec instance. Call this after the hijacked stream closes to learn the process exit code.

func (*Client) ExecResize

func (c *Client) ExecResize(ctx context.Context, execID string, height, width int) error

ExecResize forwards a window-resize event to a running PTY exec.

func (*Client) ExecStart

func (c *Client) ExecStart(ctx context.Context, execID string, tty bool) (*ExecSession, error)

ExecStart starts a previously-created exec and hijacks the connection so the caller can pipe stdin/stdout directly. The returned ExecSession owns the underlying net.Conn — close it when done.

func (*Client) ExportImageTar added in v0.4.1

func (c *Client) ExportImageTar(ctx context.Context, ref string) (io.ReadCloser, error)

ExportImageTar streams `GET /images/{name}/get` (the daemon-side equivalent of `docker save <ref>`) and hands the caller back the raw tar body. The returned stream is an uncompressed tar in the docker-save layout (manifest.json + repositories + per-layer-sha directories each containing layer.tar). Closing the returned stream releases the underlying response.

This is the consumer-side pair to ImportImage in the PR 6-B template-push pipeline: a remote node imports a template artifact tar as a single-layer image, pushes it to AOCR, and the consumer pulls + exports it to get the original tar bytes back out. Uses streamClient (no timeout) because rootfs.ext4 can run hundreds of MB and http.Client.Timeout covers the entire response body read.

func (*Client) IPOwner added in v0.6.6

func (c *Client) IPOwner(ctx context.Context, ip string) (string, error)

IPOwner reports which sandbox currently holds ip on the sandbox network, by reading dockerd's live network attachment list. It exists for the P0-6 owner check: dockerd assigns the IP at start, before the new sandbox's row is persisted, so the store alone can't see a fresh owner.

func (*Client) ImageExists added in v0.1.7

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

ImageExists reports whether the named image already exists in the local daemon. Used by the daytona facade to short-circuit redundant builds.

func (*Client) ImportImage added in v0.4.1

func (c *Client) ImportImage(ctx context.Context, req ImportImageRequest) error

ImportImage streams a tarball into the Docker daemon's "import from tarball" endpoint (POST /images/create?fromSrc=-&repo=<tag>) and tags the result as DestTag. Mirrors the pullImage transport choice (streamClient) so a large rootfs.ext4 layer doesn't trip an http.Client.Timeout — the import scans the whole tar before the daemon flushes its response, so the read can be slow.

The contract is "after a nil return, DestTag exists locally". The template push pipeline then hands DestTag to PushImage exactly the way the snapshot push pipeline hands its commit-produced tag in; keeping the surfaces parallel means a single mental model for both halves of "AOCR replication."

func (*Client) Inspect

func (c *Client) Inspect(ctx context.Context, containerRef string) (*SandboxRuntime, error)

func (*Client) ListBuiltImages added in v0.1.7

func (c *Client) ListBuiltImages(ctx context.Context) ([]BuiltImage, error)

ListBuiltImages returns every locally-built image (tags in BuiltImageNamespace) the daemon currently holds. The janitor uses this to find candidates for unreferenced-and-old removal.

We filter server-side by reference so the API call only returns matching images — much cheaper than pulling the whole image list and filtering client-side on a daemon that may hold hundreds of base images. Each candidate is then individually inspected to read Metadata.LastTagTime, which the cheaper /images/json list endpoint does not return.

func (*Client) ListManaged

func (c *Client) ListManaged(ctx context.Context) (map[string]*SandboxRuntime, error)

func (*Client) ListParkedContainers added in v0.5.5

func (c *Client) ListParkedContainers(ctx context.Context) ([]containerSummary, error)

ListParkedContainers returns all park-labeled containers for boot purge. all=1 matters: a parked container that crashed or exited still has its container object and, worse, its IP-keyed DROP rule — listing only running containers would leave both behind forever.

func (*Client) NetRulesEnabled added in v0.6.9

func (c *Client) NetRulesEnabled() bool

NetRulesEnabled reports whether this client's firewall rules are live. With network rules off, or on a non-Linux host, the manager is disabled and every rule method below returns nil without installing anything.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

func (*Client) PrepareNetnsPause added in v0.6.9

func (c *Client) PrepareNetnsPause(ctx context.Context, before time.Time)

PrepareNetnsPause readies restricted creates on a node without the pause pool (whose own loop does both): it pulls the pause image if it is missing, so the first restricted create doesn't wait for the pull, and removes the pause containers an earlier run left for sandboxes whose workload container is gone (a crash between the two creates, or a destroy that died halfway). Only pauses created before `before` are judged, so a create in flight is never touched. Best effort, off the boot path: the create path pulls for itself and the next boot sweeps again.

func (*Client) PullImage added in v0.4.1

func (c *Client) PullImage(ctx context.Context, ref string, auth *models.RegistryAuth) error

PullImage is the exported single-call pull wrapper the template puller uses. Goes through pullImageDedup so concurrent first-callers for the same ref collapse to one daemon request — the same dedup that protects the create-sandbox pull path. Auth is optional: nil means anonymous, except that pullImageDedup back-fills the cluster PAT for AOCR `cluster/...` refs when ConfigureAOCRPullAuth has been called (see aocr_pull_auth.go), so the template puller can pass nil and still authenticate against a private AOCR.

func (*Client) PurgeParkedContainers added in v0.5.5

func (c *Client) PurgeParkedContainers(ctx context.Context) (int, error)

PurgeParkedContainers destroys the park inventory a previous run left and clears its rules. Adopted containers carry the park label too and are live sandboxes; isParkedContainer leaves them alone.

func (*Client) PushAllowedPorts

func (c *Client) PushAllowedPorts(ctx context.Context, containerIP, toolboxToken string, ports []int) error

PushAllowedPorts updates the toolbox's in-memory allowlist of ports that /proxy/<port>/... is permitted to reach. The list should match the sandbox's currently exposed ports. Best-effort: callers log on failure.

func (*Client) PushImage added in v0.1.7

func (c *Client) PushImage(ctx context.Context, req PushImageRequest) (string, error)

PushImage tags SourceTag as DestRef and pushes the result to the destination registry. Returns the canonical "repo:tag" that was pushed.

Credentials are passed through per-call via X-Registry-Auth; nothing is written to the daemon's auth config and nothing is logged. The local SourceTag is preserved after a successful push so a follow-up sandbox create still hits the local fast path.

func (*Client) ReassertEgressFloor added in v0.6.9

func (c *Client) ReassertEgressFloor(context.Context) (bool, error)

ReassertEgressFloor puts the floor back if something removed it.

func (*Client) ReassertNodeGuard added in v0.6.9

func (c *Client) ReassertNodeGuard(context.Context) (bool, error)

ReassertNodeGuard puts the guard back if something removed it.

func (*Client) RefreshTag added in v0.1.7

func (c *Client) RefreshTag(ctx context.Context, fullRef string) error

RefreshTag re-applies an image's existing repo:tag, which causes the daemon to bump Metadata.LastTagTime to "now". The built-image janitor uses LastTagTime as the "this tag was used recently, don't GC it" signal, so callers that hand out a cached tag (without running BuildImage) must call this to keep the GC clock from running on a tag that's actively in use. Idempotent and cheap — Docker treats re-tagging an existing tag as a no-op aside from the metadata bump.

func (*Client) RemoveImage

func (c *Client) RemoveImage(ctx context.Context, imageRef string) error

RemoveImage deletes an image from the local Docker daemon by reference (name:tag or digest). 404 (already gone) and 409 (still in use) are treated as success: the goal is "image is no longer occupying disk on our account", and a 409 means another container raced ahead and started using the image between the caller's eligibility check and this call — leaving it is correct, not an error. Other failures are returned for the caller to log.

func (*Client) Resize

func (c *Client) Resize(ctx context.Context, containerRef string, req models.ResizeSandboxRequest) error

func (*Client) SandboxBridge added in v0.6.6

func (c *Client) SandboxBridge(ctx context.Context) (SandboxNetwork, error)

SandboxBridge returns the Linux bridge, gateway IP and subnet of the sandbox network (SB_DOCKER_NETWORK, default "bridge" → docker0). sandboxd hands it to the egress gateway, which has no docker socket access (plans/ egress-domain-filtering.md S5, CEO D21).

func (*Client) SetEgressFloor added in v0.6.6

func (c *Client) SetEgressFloor(ctx context.Context, cidrs []netip.Prefix) error

SetEgressFloor installs the operator's node-wide deny floor for the sandbox network's subnet (§5.10 PC-2).

func (*Client) SetNetnsPauseImage added in v0.6.9

func (c *Client) SetNetnsPauseImage(image string)

SetNetnsPauseImage sets the image of the pause containers restricted creates start for themselves: SB_DOCKER_NETNS_POOL_PAUSE_IMAGE, the same image the pool's slots run.

func (*Client) SetNodeGuard added in v0.6.9

func (c *Client) SetNodeGuard(ctx context.Context, allow []netrules.NodePort) error

SetNodeGuard default-denies the sandbox network's subnet from the node itself, except allow (netrules ChainAerolvmNode).

func (*Client) SetPullObserver added in v0.2.3

func (c *Client) SetPullObserver(obs PullObserver)

SetPullObserver installs a single observer. Calling again replaces the previous one. Pass nil to disable. main() is expected to set this once at startup to wire the post-pull AutoImportPending flag.

func (*Client) SetWarmPool added in v0.5.5

func (c *Client) SetWarmPool(p *dockerpool.Pool)

SetWarmPool wires the docker warm pool. Nil disables the fast path.

func (*Client) Start

func (c *Client) Start(ctx context.Context, containerRef string) (*SandboxRuntime, error)

func (*Client) StartImageIDCacheWarmer added in v0.5.6

func (c *Client) StartImageIDCacheWarmer(ctx context.Context, pool *dockerpool.Pool, interval time.Duration, logger *slog.Logger)

StartImageIDCacheWarmer runs a background ticker that re-resolves every pool-eligible image into the TTL cache. RefillInterval must be strictly less than imageIDCacheTTL — otherwise sparse creates (one per 15s+) go cold between ticks. The inspect is timing-free and generation-fenced so it never records a boot-path docker_image stage and never re-installs a stale ID after an in-band Flush.

func (*Client) StartNetnsPool added in v0.5.5

func (c *Client) StartNetnsPool(ctx context.Context, logger *slog.Logger, depth int, pauseImage string, interval time.Duration) *NetnsPool

StartNetnsPool wires and starts the pause-netns pool on the client. Call once at daemon boot; no-op protection is the caller's problem (daemon wiring runs it once behind the config gate).

func (*Client) StartWithIdentity added in v0.6.6

func (c *Client) StartWithIdentity(ctx context.Context, containerRef, sandboxID, toolboxToken string) (*SandboxRuntime, error)

StartWithIdentity starts a stopped sandbox's container. One adopted from the warm pool still carries the pool's env (SB_POOL_PARKED=1, its slot's bootstrap token and park nonce, the bind to its slot's park socket), since Docker keeps a container's env across stop and start. Its toolboxd boots parked, holds the user's command back and answers nothing but /health, so a plain Start would pass its health poll and hand out a sandbox whose every call is 503 "sandbox not adopted". It is adopted again over its slot's socket with the sandbox's own identity, exactly as at create.

func (*Client) Stop

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

func (*Client) StreamEvents

func (c *Client) StreamEvents(ctx context.Context, out chan<- DockerEvent) error

StreamEvents subscribes to Docker's /events feed for managed containers and pushes normalized events to out. It blocks until ctx is cancelled or the stream errors. Callers are expected to reconnect on error.

func (*Client) SweepOrphanReadySockets added in v0.5.5

func (c *Client) SweepOrphanReadySockets(ctx context.Context) error

SweepOrphanReadySockets removes ready sockets not referenced by existing managed Docker containers. Docker persists bind mounts across stop/start, so deleting a stopped container's ready-socket source would make docker start fail before toolboxd can boot.

func (*Client) ToolboxAddress added in v0.6.2

func (c *Client) ToolboxAddress(ctx context.Context, sandbox *models.Sandbox) (string, error)

ToolboxAddress returns the host:port at which sandboxd reaches the sandbox's toolboxd. By default that is ContainerIP:ToolboxPort. With SB_DOCKER_TOOLBOX_LOOPBACK it is the container's current 127.0.0.1 binding, read with one inspect per call because the port changes on every start.

func (*Client) WritableLayerBytes added in v0.6.9

func (c *Client) WritableLayerBytes(ctx context.Context, containerRef string) (int64, error)

WritableLayerBytes implements runtime.WritableLayerSizer: the container's SizeRw (bytes written to its writable layer), which dockerd computes on a size=true inspect.

type ContainerStat added in v0.5.1

type ContainerStat struct {
	CPUTotalNanos uint64 // cumulative CPU time (ns) consumed since container start
	MemBytes      uint64 // current working-set memory in bytes
}

ContainerStat is a one-shot resource snapshot for a container: the cumulative CPU time consumed since it started and its current working-set memory. The CPU figure is a monotonic counter; callers difference it across reads to get CPU time consumed in a window. Memory is an instantaneous gauge.

type CreateTiming added in v0.5.5

type CreateTiming = createtiming.CreateTiming

CreateTiming moved to pkg/createtiming so the firecracker driver can record boot stages on the same recorder without importing pkg/docker (Phase 0, plans/firecracker-create-latency.md). These aliases keep the docker package's existing callers (v1 handlers, tests) source-stable; the context key lives in createtiming so both packages share one recorder per request.

func CreateTimingFrom added in v0.5.5

func CreateTimingFrom(ctx context.Context) *CreateTiming

CreateTimingFrom returns the recorder stashed on ctx, if any.

func WithCreateTiming added in v0.5.5

func WithCreateTiming(parent context.Context) (context.Context, *CreateTiming)

WithCreateTiming returns a child context that carries a CreateTiming recorder.

type DockerEvent

type DockerEvent struct {
	ContainerID string
	SandboxID   string
	Action      string // "die", "destroy", "oom", "start", "stop"
	ExitCode    int    // populated on "die" when reported by Docker
	Time        time.Time
}

DockerEvent is a normalized container lifecycle event from the Docker engine, scoped to containers carrying our managed label.

type EventsSource added in v0.5.6

type EventsSource interface {
	StreamEvents(ctx context.Context, out chan<- DockerEvent) error
	netstats.PIDLookup
}

EventsSource is the engine-agnostic surface the service layer uses for the daemon event monitor and netstats PID resolution. *Client satisfies it for the dockerd path; internal/runtime/containerd.Driver satisfies it for the containerd path. Keeping DockerEvent on this seam avoids a second event type while both engines can coexist during migration.

type ExecSession

type ExecSession struct {
	ID     string
	Conn   net.Conn
	Reader *bufio.Reader
}

ExecSession is a hijacked Docker exec stream. With Tty=true the byte stream is unframed (raw); with Tty=false it follows Docker's stdin/stdout/stderr multiplexing. The SSH gateway only uses Tty=true for shells and Tty=false for one-shot exec, where stderr framing isn't decoded — stdout+stderr both reach the SSH client through the merged stream as the SSH side expects.

func (*ExecSession) Close

func (e *ExecSession) Close() error

Close releases the hijacked connection. Idempotent.

type ImportImageRequest added in v0.4.1

type ImportImageRequest struct {
	DestTag string
	Tar     io.Reader
}

ImportImageRequest is the input to (*Client).ImportImage. Tar carries the artifact bytes that become the image's single layer; DestTag is the local repo:tag the daemon assigns on success. The tag MUST be a local name (typically under BuiltImageNamespace) so the existing built-image GC sweeps it after the subsequent push completes — the Phase 6 PR 6-B.1 template-push pipeline relies on this.

type MirrorConfig added in v0.2.3

type MirrorConfig struct {
	Host      string
	PushHost  string
	Upstreams []MirrorUpstream
}

MirrorConfig is the per-node mirror policy. A zero value disables all rewriting — pullImage behaves exactly as it did before. This is the safety hatch for any node that isn't running with AOCR mirror enabled.

`Host` is the mirror vhost (e.g. `mirror.aocr.aerol.ai`). `PushHost` is the AOCR push vhost (e.g. `aocr.aerol.ai`); we recognize both so already-rewritten refs and cluster-snapshot refs pass through unchanged — important on the failover path where a sandbox's stored `RegistryRef` may already point at the AOCR side.

func (MirrorConfig) Enabled added in v0.2.3

func (c MirrorConfig) Enabled() bool

Enabled reports whether mirror rewriting is active. Returns false for any zero/empty config so callers can short-circuit without parsing.

type MirrorRewrite added in v0.2.3

type MirrorRewrite struct {
	// RewrittenRef is what should actually be pulled. When Rewritten=false
	// this equals the original input.
	RewrittenRef string
	// OriginalRef is the user-visible ref (what to store on the sandbox
	// row for trace/display). Always equals the input.
	OriginalRef string
	// Rewritten=true means the ref was redirected to the mirror.
	Rewritten bool
	// UpstreamHost / UpstreamRepo / UpstreamTag are the components AOCR's
	// auth service needs to validate a wrapped credential and probe the
	// upstream. They are populated only when Rewritten=true.
	UpstreamHost string
	// UpstreamRepo is the *mirror-side* repo path, e.g.
	// `aocr/ghcr/aerol-ai/sandbox` — this matches the Distribution scope
	// string AOCR's `route.ts` parses. For Docker Hub passthrough or
	// non-rewritten refs this is empty.
	UpstreamRepo string
	UpstreamTag  string
}

MirrorRewrite is the structured result of `RewriteImageRefForMirror`. All fields are populated even when no rewrite happened so the caller has a single value to plumb through (no nil checks).

func RewriteImageRefForMirror added in v0.2.3

func RewriteImageRefForMirror(ref string, cfg MirrorConfig) MirrorRewrite

RewriteImageRefForMirror is a pure function: no I/O, no globals. It inspects an image reference and decides whether to redirect it through the AOCR mirror vhost.

Rules (in order):

  1. Empty / unparseable refs are passed through.
  2. Refs that already point at the mirror or push vhost are passed through (idempotency — re-running a rewrite is a no-op).
  3. Refs whose host matches a configured `MirrorUpstream.Host` are rewritten to `<mirrorHost>/aocr/<short>/<repo>:<tag>`.
  4. Docker Hub refs (host=docker.io, or no host prefix at all) pass through — the Docker daemon handles them via `registry-mirrors`.
  5. Refs with an unknown host pass through, so private registries the operator didn't configure as mirror upstreams keep working.

type MirrorUpstream added in v0.2.3

type MirrorUpstream struct {
	Host      string
	Shortname string
}

MirrorUpstream maps an upstream registry host to the short prefix the AOCR mirror uses to disambiguate it in its URL path.

Example: `{Host: "ghcr.io", Shortname: "ghcr"}` causes `ghcr.io/aerol-ai/sandbox:v1` to be rewritten to `mirror.aocr.aerol.ai/aocr/ghcr/aerol-ai/sandbox:v1`. The `aocr/` prefix is a reserved namespace owned by the AOCR mirror; AOCR's auth route helper (`auth/src/upstreamAuth/route.ts`) strips `aocr/<short>/` back off when routing scope strings to the upstream probe.

Why `aocr` and not `_`: Docker's reference grammar (distribution/reference) requires each path component to match `[a-z0-9]+([._-][a-z0-9]+)*`. The bare `_` segment that early drafts of the mirror used is NOT a valid component, and Docker daemon rejects refs like `mirror.aocr.aerol.ai/_/ghcr/...` with "invalid reference format" before they ever leave the client.

Docker Hub is intentionally absent from this list: it's handled by the Docker daemon's `registry-mirrors` daemon.json setting (which only supports DockerHub), not by client-side rewriting. Refs that resolve to `docker.io` pass through unchanged here.

type NetnsPool added in v0.5.5

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

NetnsPool keeps DockerNetnsPoolDepth pause containers warm and hands them to Create. All docker calls go through the owning Client.

func (*NetnsPool) Adopt added in v0.5.5

func (p *NetnsPool) Adopt(ctx context.Context, sandboxID string) (netnsSlot, bool)

Adopt pops a warm slot and renames it to the sandbox's adopted name. The rename doubles as the liveness check — it fails if the pause died — and establishes crash-safe ownership before the sandbox container exists. Returns ok=false on any miss; the caller falls back to the plain cold path.

func (*NetnsPool) Stop added in v0.5.5

func (p *NetnsPool) Stop(ctx context.Context)

Stop halts the refill loop and removes all free slots. Adopted slots belong to their sandboxes and are cleaned up by Destroy.

type ParkedListener added in v0.5.5

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

ParkedListener accepts a parked hello and holds the connection for adopt.

func NewParkedListener added in v0.5.5

func NewParkedListener(dir, slotID, bootstrapToken, parkNonce string) (*ParkedListener, error)

NewParkedListener listens for a warm-pool parked hello.

func (*ParkedListener) Adopt added in v0.5.5

func (l *ParkedListener) Adopt(ctx context.Context, sandboxID, token, adoptNonce string) error

Adopt sends the adopt frame and waits for the ready ack.

func (*ParkedListener) Alive added in v0.5.5

func (l *ParkedListener) Alive() bool

Alive reports whether the held parked connection is still open.

func (*ParkedListener) BindSpec added in v0.5.5

func (l *ParkedListener) BindSpec() string

BindSpec returns the docker bind mount for this socket.

func (*ParkedListener) Close added in v0.5.5

func (l *ParkedListener) Close() error

Close shuts down the park listener and any held connection.

func (*ParkedListener) EnvVars added in v0.5.5

func (l *ParkedListener) EnvVars() []string

EnvVars returns env vars for a parked container.

func (*ParkedListener) HostSocketPath added in v0.5.5

func (l *ParkedListener) HostSocketPath() string

HostSocketPath returns the host-side socket path.

func (*ParkedListener) WaitParked added in v0.5.5

func (l *ParkedListener) WaitParked(ctx context.Context) error

WaitParked accepts one valid parked hello and retains the connection.

type PoolSpawner added in v0.5.5

type PoolSpawner struct {
	Client *Client
}

PoolSpawner implements dockerpool.Spawner against this client.

func (*PoolSpawner) DestroyParked added in v0.5.5

func (p *PoolSpawner) DestroyParked(ctx context.Context, slot *dockerpool.ParkedSlot) error

func (*PoolSpawner) Park added in v0.5.5

func (p *PoolSpawner) Park(ctx context.Context, slotID string, key dockerpool.Key) (*dockerpool.ParkedSlot, error)

type PullObserver added in v0.2.3

type PullObserver func(ctx context.Context, sandboxID string)

PullObserver is invoked exactly once per successful pull that BOTH went through a mirror rewrite AND used non-anonymous upstream credentials — the precondition for the F21 auto-import flow. The sandboxID is whatever the caller stashed on the context with WithSandboxID; empty IDs skip the observer call (no row to flag).

Errors inside the observer are the caller's problem: pullImage does not surface them, so the observer must not panic and should handle its own retry/logging. The observer runs synchronously on the pull goroutine; keep it fast.

type PushImageRequest added in v0.1.7

type PushImageRequest struct {
	SourceTag string
	DestRef   string
	Auth      models.RegistryAuth
	OnLog     func(line string)
	// OnDigest is invoked once with the manifest digest the registry
	// returned for the pushed tag (e.g. "sha256:abc..."), if the daemon
	// surfaced one in the push stream's `aux` payload. Optional —
	// callers that don't care about the digest can leave it nil.
	OnDigest func(digest string)
}

PushImageRequest is the input to (*Client).PushImage. SourceTag is the local image (typically an aerolvm-build/<sha>:latest tag returned by BuildImage). DestRef is the fully-qualified destination, e.g. "ghcr.io/my-org/my-image:v1.2.3"; if no ":tag" is present, "latest" is used. Auth is request-scoped credentials — they are sent to the daemon as a one-shot X-Registry-Auth header and never persisted.

type ReadyListener added in v0.5.5

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

ReadyListener accepts a single valid readiness push from toolboxd.

func NewReadyListener added in v0.5.5

func NewReadyListener(dir, sandboxID, token, nonce string) (*ReadyListener, error)

NewReadyListener creates and listens on a per-create unix socket under dir. The socket file is nonce-keyed so boot sweeps and retries cannot collide.

func (*ReadyListener) BindSpec added in v0.5.5

func (l *ReadyListener) BindSpec() string

BindSpec returns the docker bind mount for this socket.

func (*ReadyListener) Close added in v0.5.5

func (l *ReadyListener) Close() error

Close shuts down the readiness accept loop. The kernel unlinks the socket path when the listener fd closes; call ParkBindSource afterward when Docker must keep bind-mounting the path across stop/start.

func (*ReadyListener) EnvVars added in v0.5.5

func (l *ReadyListener) EnvVars() []string

EnvVars returns the env vars toolboxd needs to dial the socket.

func (*ReadyListener) HostSocketPath added in v0.5.5

func (l *ReadyListener) HostSocketPath() string

HostSocketPath returns the host-side socket path.

func (*ReadyListener) InvalidAttempts added in v0.5.5

func (l *ReadyListener) InvalidAttempts() (int, string)

InvalidAttempts reports how many pushes were rejected and the last reason.

func (*ReadyListener) ParkBindSource added in v0.5.5

func (l *ReadyListener) ParkBindSource() error

ParkBindSource re-listens on the host path so the bind-mount source inode survives listener shutdown. Docker validates bind sources on container start.

func (*ReadyListener) Wait added in v0.5.5

func (l *ReadyListener) Wait(ctx context.Context) error

Wait accepts connections until a valid ready signal arrives or ctx expires.

type SandboxNetwork added in v0.6.6

type SandboxNetwork struct {
	Name    string
	Gateway netip.Addr
	Subnet  netip.Prefix
	// Driver ("bridge" for docker0 and a user-defined bridge) and IPRange
	// (the part of Subnet IPAM hands out, dockerd's fixed-cidr) size the
	// docker bridge slot pool: a bridge holds 1,023 ports, and IPAM can run
	// out of addresses first.
	Driver  string
	IPRange netip.Prefix
}

SandboxNetwork is the sandbox network's bridge as the egress gateway needs it: where to listen (Gateway on Name) and which sources the node-wide floor and control-port guard cover (Subnet, §5.10 PC-2).

type SandboxRuntime

type SandboxRuntime = models.SandboxRuntimeState

SandboxRuntime is the Docker-layer alias of the canonical models.SandboxRuntimeState type. The alias keeps every existing reference in pkg/docker compiling unchanged while letting non-Docker runtime implementations import only pkg/models.

Directories

Path Synopsis
Package netstats reads per-sandbox network byte counters from /proc/<pid>/net/dev.
Package netstats reads per-sandbox network byte counters from /proc/<pid>/net/dev.

Jump to

Keyboard shortcuts

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