docker

type Client interface {
	// List returns every container carrying our label prefix, running or not.
	List(ctx context.Context) ([]Container, error)
	// EnsureImage pulls the image if it is not already present. Idempotent.
	EnsureImage(ctx context.Context, imageRef string) error
	// Create creates and starts the given replica of a workload with hard limits on
	// every axis. It is idempotent by (workload, replica) identity: if a matching
	// container already exists for this spec version it is a no-op.
	Create(ctx context.Context, spec contract.WorkloadSpec, version string, replica int) (Container, error)
	// Stop stops and removes the container with the given ID immediately. Idempotent:
	// a missing container is treated as success.
	Stop(ctx context.Context, id string) error
	// Drain gracefully stops (SIGTERM, grace period) and removes a container that has
	// been superseded by a healthy replacement, so in-flight requests can finish. Used
	// for the old container in a zero-downtime rolling deploy. Idempotent.
	Drain(ctx context.Context, id string) error
	// Restart restarts the container with the given ID. Idempotent.
	Restart(ctx context.Context, id string) error
	// Stats returns current memory and CPU usage for a container, read via the
	// Docker Engine API so it works uniformly on Linux and on Docker Desktop
	// (macOS, Windows), where container cgroups are not on the host filesystem.
	Stats(ctx context.Context, id string) (contract.CgroupUsage, error)
	// Logs returns container output newer than `since` (an RFC3339 timestamp). If
	// `since` is empty a short tail is returned, so a first report is not a flood.
	// Read via the Docker Engine API so it works on Linux and Docker Desktop alike.
	Logs(ctx context.Context, id string, since string) ([]contract.LogLine, error)
	// TakeReleaseReports returns and clears the release-command outcomes captured since
	// the last call, keyed by workload ID, for the agent to attach to its status report.
	TakeReleaseReports() map[string]*contract.ReleaseReport
	// Close releases any underlying SDK resources.
	Close() error
}

type Container struct {
	// ID is the Docker container ID.
	ID string
	// WorkloadID is the WorkloadSpec.ID this container serves.
	WorkloadID string
	// BlobID is the internal Blob identity of the Egg.
	BlobID string
	// EggID is the customer-facing Egg identity.
	EggID string
	// ImageRef is the image this container was created from.
	ImageRef string
	// SpecVersion is the desired-state version this container was created for.
	SpecVersion string
	// State is the low-level runtime state.
	State contract.ContainerState
	// Healthy reports the last observed health-check result.
	Healthy bool
	// RestartCount is the Docker-reported restart count.
	RestartCount int
	// CgroupPath is the absolute cgroup v2 path for this container, used to read
	// resource stats directly.
	CgroupPath string
	// ReplicaIndex is the 0-based replica index within the workload. A workload
	// running N replicas has containers with indices 0..N-1.
	ReplicaIndex int
	// PublishedPort is the host port this container's app port is published on (0
	// when it is not published, e.g. a database Egg). Ingress load-balances across
	// the published ports of a workload's live replicas.
	PublishedPort int
	// Legacy is true for a container created by an older agent that predates replica
	// indexing (no replica label). It is always rolled so the fleet converges onto
	// the indexed naming.
	Legacy bool
}

type DiskUsager interface {
	VolumeUsageBytes(ctx context.Context, containerID string) (int64, error)
}

type Migrator interface {
	// SnapshotLive streams a logical dump of the LIVE serving container to w and reads
	// the verification counts. The source keeps serving during the dump: pg_dump takes
	// an MVCC-consistent snapshot and redis SAVE flushes current memory to disk, so the
	// dump reflects a real point in time. Snapshotting the live container (rather than a
	// throwaway on a stopped volume) is what makes it correct for an in-memory engine
	// like Redis, whose data is not on disk until it is saved.
	SnapshotLive(ctx context.Context, engine, containerID string, env []string, w io.Writer) (contract.MigrationCounts, error)
	// RestoreDatabase restores a logical dump read from r into a FRESH copy of the
	// Egg's volume, reads the verification counts, then removes the restore container
	// (the Egg only starts serving on the target after cutover). Isolated (no network)
	// and idempotent: a retry re-restores cleanly.
	RestoreDatabase(ctx context.Context, engine, name, volumeName, image string, env []string, r io.Reader) (contract.MigrationCounts, error)
}