docker

type BindMount struct {
	HostPath      string
	ContainerPath string
	ReadOnly      bool
}

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

type ContainerSpec struct {
	Name      string
	Image     string
	Ports     []PortBinding
	Env       map[string]string
	Resources *Resources
	// Volumes are named Docker volumes to mount at create time. A
	// database controller is the first caller; ordinary
	// application containers leave this nil.
	Volumes []VolumeMount
	// BindMounts are real host directories to mount at create time
	// (BindMount's own doc comment). Nil for every service before this
	// field existed and for the ordinary stateless service today.
	BindMounts []BindMount
	// DNS lists nameserver IPs Docker writes into the container's
	// /etc/resolv.conf, ahead of whatever the daemon would otherwise
	// configure. Empty/nil is byte-identical to today: only a caller
	// that resolved a real, container-reachable mesh DNS address
	// (cmd/levelrail/mesh.go's containerDNSAddr) ever sets this, and
	// only when the mesh is actually enabled and running.
	DNS []string
	// Labels are applied to the container verbatim via the Engine API's
	// own label mechanism (container.Config.Labels), operator-supplied
	// custom Docker labels (internal/spec.Service.Labels, an escape
	// hatch for external tooling that keys off container labels). This
	// package stays spec-agnostic (same reasoning as Image being a
	// plain string, not something spec-aware, this struct's own doc
	// comment above): it trusts Labels arrived here already validated,
	// the same way it already trusts Env and every other field. See
	// internal/spec.ValidateLabels for what's rejected before a caller
	// ever builds a ContainerSpec with this set.
	Labels map[string]string
	// Network attaches the container to a non-default Docker network at
	// create time, with Alias as the name sibling containers on that
	// network can reach it by (Docker's embedded per-network DNS
	// resolves it). Nil means Docker's default "bridge" network,
	// unchanged from every container this codebase created before this
	// field existed: that network has no embedded DNS, so this is what
	// makes multi-service apps able to reach each other by name at all.
	Network *NetworkAttachment
	// RegistryAuth authenticates the image pull (Create's own ensureImage
	// step) against a private registry. Nil means an unauthenticated
	// pull, unchanged from every container this codebase created before
	// this field existed.
	RegistryAuth *RegistryAuth
	// Command overrides the image's own default CMD. Nil means the
	// image's own default, unchanged from every container this codebase
	// created before this field existed. First caller:
	// internal/reconcile/cloudflaretunnel, whose cloudflared image needs
	// an explicit "tunnel run" argument rather than relying on the
	// image's bare entrypoint.
	Command []string
	// Entrypoint overrides the image's own default ENTRYPOINT. Nil means
	// the image's own default, unchanged from every container this
	// codebase created before this field existed. First caller:
	// internal/reconcile/registry, which needs to write an htpasswd file
	// from injected env before handing off to the registry image's real
	// entrypoint.
	Entrypoint []string
}

type ContainerState struct {
	ID      string
	Name    string
	Image   string
	Running bool
	// Ports reflects live port bindings. Docker only actually binds a
	// container's published ports once it's running, so this is empty
	// for a created-but-not-yet-started container, not an error.
	Ports []PortBinding
}

type ContainerStats struct {
	// CPUPercent is 0-100 per core, i.e. a container fully using 2 cores
	// on an otherwise idle host reports 200.0, matching `docker stats`'
	// own convention, computed the same way (delta of cpu_usage over
	// delta of system_cpu_usage, times online CPU count).
	CPUPercent float64
	// MemoryUsageBytes excludes page cache when the cgroup reports it
	// separately (Stats above), matching `docker stats`' "used" figure
	// rather than the raw cgroup usage counter, which double-counts
	// reclaimable cache as "used."
	MemoryUsageBytes uint64
	MemoryLimitBytes uint64
	// NetworkRxBytes/TxBytes are summed across every interface Docker
	// reports for this container; a single container's total network
	// usage is what the per-app metrics requirement asks for, not a
	// per-interface breakdown.
	NetworkRxBytes uint64
	NetworkTxBytes uint64
	// DiskReadBytes/WriteBytes are summed across every block device
	// Docker's blkio accounting reports for this container's cgroup.
	DiskReadBytes  uint64
	DiskWriteBytes uint64
}

type DiskUsage struct {
	ImagesTotalBytes int64
	// ImagesReclaimableBytes follows Docker's own `docker system df`
	// methodology (unused = zero containers reference the image,
	// tagged or not), so an operator sees the same number the docker
	// CLI would show them directly on this host. It is deliberately a
	// bigger number than what PruneDanglingImages actually frees: that
	// call only ever removes the dangling (untagged) subset, on
	// purpose, see PruneDanglingImages' own doc comment for why a
	// tagged-but-currently-unused image is a real rollback target this
	// project has an explicit design rule to protect.
	ImagesReclaimableBytes int64

	ContainersTotalBytes int64
	// ContainersReclaimableBytes sums the writable-layer size (SizeRw,
	// not SizeRootFs, which would double-count shared image layers) of
	// every non-running container, matching what PruneContainers is
	// eligible to remove before its own additional "currently desired"
	// exclusion is applied.
	ContainersReclaimableBytes int64

	VolumesTotalBytes int64
	// VolumesReclaimableBytes sums every volume Docker itself reports
	// as unreferenced by any container (RefCount == 0), a bigger set
	// than PruneAnonymousVolumes actually touches: that call only
	// removes the anonymous subset, never a named volume regardless of
	// use, because a volume that looks unused can be one mid-recreate
	// during a database engine version bump, see
	// PruneAnonymousVolumes' own doc comment.
	VolumesReclaimableBytes int64

	BuildCacheTotalBytes int64
	// BuildCacheReclaimableBytes sums every build cache record not
	// currently InUse, matching what PruneBuildCache removes.
	BuildCacheReclaimableBytes int64
}

type Event struct {
	Action        EventAction
	ContainerName string
	Time          time.Time
}

type EventAction string

type ExecExitError struct {
	Cmd       []string
	Container string
	ExitCode  int
	Stderr    string
}

type ExecSession interface {
	io.ReadWriteCloser
	Resize(ctx context.Context, size TTYSize) error
}

type ExecTTYOptions struct {
	Cmd        []string
	Env        []string
	User       string
	WorkingDir string
	Size       TTYSize
}

type ImageInfo struct {
	Tag       string
	CreatedAt time.Time
}

type LogLine struct {
	// Stream is "stdout" or "stderr".
	Stream string
	// Timestamp is Docker's own recorded time for this line, parsed from
	// the log stream (Logs always requests Timestamps: true). Zero if the
	// line didn't parse as the expected "<timestamp> <message>" shape;
	// callers should fall back to their own clock in that case rather
	// than treating a parse failure as fatal.
	Timestamp time.Time
	Message   string
}

type NetworkAttachment struct {
	Name  string
	Alias string
}

type NetworkInfo struct {
	ID   string
	Name string
}

type PortBinding struct {
	ContainerPort int
	HostPort      int
	// Protocol is "tcp" or "udp". Empty is treated as "tcp" by Create.
	Protocol string
}

type PruneBuildCacheResult struct {
	Removed        []string
	ReclaimedBytes uint64
}

type PruneContainersResult struct {
	Removed        []string
	ReclaimedBytes uint64
}

type PruneImagesResult struct {
	Removed        []string
	ReclaimedBytes uint64
}

type PruneResult struct {
	ContainersRemoved        []string
	ContainersReclaimedBytes uint64
	ImagesRemoved            []string
	ImagesReclaimedBytes     uint64
	VolumesRemoved           []string
	VolumesReclaimedBytes    uint64
	BuildCacheRemoved        []string
	BuildCacheReclaimedBytes uint64
	// Errors collects any stage's failure without aborting the rest:
	// the same "one broken resource must not block others" principle
	// internal/reconcile/application.Controller.removeContainers
	// already applies to stale-container cleanup, applied here across
	// prune stages instead of across containers.
	Errors []string
}

type PruneVolumesResult struct {
	Removed        []string
	ReclaimedBytes uint64
}

type RegistryAuth struct {
	Username string
	Password string
}

type Resources struct {
	MemoryBytes int64
	NanoCPUs    int64
	// SwapMemoryBytes is Docker's own MemorySwap: total memory plus swap
	// combined, only meaningful alongside MemoryBytes.
	SwapMemoryBytes int64
	// CPUSetCPUs pins the container to specific host CPUs, Docker's own
	// cpuset-cpus format (e.g. "0-3" or "0,2").
	CPUSetCPUs string
}

type Runtime interface {
	// InspectByName returns the current state of the container with this
	// name, or (nil, nil) if no such container exists. It never returns
	// an error for "not found": that's a valid observed state, not a
	// failure.
	InspectByName(ctx context.Context, name string) (*ContainerState, error)

	// Create makes a container from spec but does not start it. Returns
	// the new container's ID.
	Create(ctx context.Context, spec ContainerSpec) (id string, err error)

	// Start starts an existing container by ID.
	Start(ctx context.Context, id string) error

	// Events streams container lifecycle events until ctx is cancelled.
	// The error channel receives at most one error (a stream failure)
	// and is then closed; the event channel is closed once the stream
	// ends for any reason.
	Events(ctx context.Context) (<-chan Event, <-chan error)

	// ListImages returns every locally-present tag under repo (e.g.
	// "levelrail/myapp"), newest first, for rollback candidate discovery.
	// An empty result and a nil error both mean "no images found", not
	// an error: a service that's never been built has no images yet.
	ListImages(ctx context.Context, repo string) ([]ImageInfo, error)

	// ListByPrefix returns every container (running or not) whose name
	// starts with prefix, for a controller to find every container
	// belonging to a service it manages, not just the one canonical name
	// nginxdemo's simpler world got away with.
	ListByPrefix(ctx context.Context, prefix string) ([]ContainerState, error)

	// Stop stops a running container, sending Signal (empty means
	// Docker's default, SIGTERM) and waiting up to timeout before
	// forcing it. A negative timeout waits indefinitely.
	Stop(ctx context.Context, id string, timeout time.Duration) error

	// Remove deletes a container. force also removes a still-running
	// one (stopping it first); without force, removing a running
	// container is an error, matching Docker's own default.
	Remove(ctx context.Context, id string, force bool) error

	// UpdateResources applies new memory, CPU, swap, and cpuset limits to
	// an already-running container in place, via the Engine API's own
	// ContainerUpdate call. Unlike every other resource-affecting change
	// a controller can want (image, env, ports, health check), this one
	// has a real live-update path: Docker itself supports adjusting a
	// running container's cgroup limits without stopping it, so a
	// reconciler can converge a resource-limit-only diff without the
	// blue-green cutover a full recreate would otherwise force.
	UpdateResources(ctx context.Context, id string, resources Resources) error

	// EnsureVolume creates a named Docker volume if it doesn't already
	// exist. Idempotent: calling it for a volume that's already present
	// is not an error, matching the Engine API's own VolumeCreate
	// semantics (creating by an existing name returns that volume
	// unchanged rather than failing).
	EnsureVolume(ctx context.Context, name string) error

	// EnsureNetwork creates a Docker bridge network named name if it
	// doesn't already exist, returning its ID either way. Idempotent:
	// inspect first, create only on a genuine miss, the same shape the
	// real implementation's ensureImage already uses for images.
	// Reconcile calls happen often (event-driven plus periodic resync),
	// so this must be safe to call on every pass, not just the first.
	EnsureNetwork(ctx context.Context, name string) (id string, err error)

	// RemoveNetwork deletes a Docker network by name. Removing a network
	// that doesn't exist is not an error: cleanup is level-triggered and
	// may run against state that's already converged.
	RemoveNetwork(ctx context.Context, name string) error

	// ListNetworksByPrefix returns every Docker network whose name
	// starts with prefix, for a reconciler to diff observed networks
	// against current desired state (internal/reconcile/application's
	// NetworkCleanupController).
	ListNetworksByPrefix(ctx context.Context, prefix string) ([]NetworkInfo, error)

	// Exec runs cmd inside the already-running container containerID and
	// returns its stdout as a stream, using the Engine API's exec
	// facility (ContainerExecCreate then ContainerExecAttach), the same
	// two calls `docker exec` itself is built on. This is the one Runtime
	// method that reaches into a process running inside a container
	// rather than managing the container's own lifecycle; it exists for
	// internal/backup's Dumper, which has no other way to run a
	// database's own native dump tool (pg_dump, mysqldump, redis-cli)
	// against a live container without shelling out, which is exactly
	// what every other method on this interface already exists to avoid.
	//
	// The returned ReadCloser carries only cmd's stdout. Stderr is
	// captured by the implementation and, if cmd exits non-zero,
	// surfaced as the error a later Read returns once the stream ends:
	// the same "an error can arrive with or after the final bytes"
	// contract every io.Reader already promises, so a caller only ever
	// has one place to check for failure instead of a second out-of-band
	// exit-code field. Close must be called once the caller is done with
	// the stream, success or failure alike, to release the underlying
	// exec connection.
	Exec(ctx context.Context, containerID string, cmd []string) (io.ReadCloser, error)

	// ExecWithInput is Exec plus a stdin stream: it runs cmd inside
	// containerID exactly as Exec does (same stdout/stderr handling, same
	// exit-code-becomes-a-trailing-error contract), except cmd's stdin is
	// wired to stdin instead of being left unattached. This exists for
	// internal/backup's Restorer, which needs to pipe a downloaded dump
	// into psql/mysql running inside a live container; Exec itself can't
	// do this; ContainerExecCreate has to be told AttachStdin: true up
	// front for the exec session to have a stdin pipe at all, and every
	// other caller of Exec (ContainerDumper) never needs one, so this is a
	// second method rather than a third parameter Exec's own existing
	// call site would otherwise have to grow to accommodate.
	//
	// Implementations read stdin to completion (EOF) and then signal
	// end-of-input to the exec'd process the way closing stdin on a real
	// terminal would, before returning; a command like psql that reads
	// until EOF and then exits depends on that signal to ever finish, not
	// only on stdin's bytes arriving. Callers are not required to provide
	// a stdin that reaches EOF on its own if the command they're running
	// doesn't need one; passing an empty reader is equivalent to Exec's
	// own "nothing attached to stdin" behavior for that command.
	//
	// The returned ReadCloser carries stdout, identically to Exec's; Close
	// must be called once done, same contract.
	ExecWithInput(ctx context.Context, containerID string, cmd []string, stdin io.Reader) (io.ReadCloser, error)
}

type TTYRuntime interface {
	ExecTTY(ctx context.Context, containerID string, opts ExecTTYOptions) (ExecSession, error)
}

type TTYSize struct {
	Rows uint16
	Cols uint16
}

type VolumeMount struct {
	Name          string
	ContainerPath string
	// ReadOnly mounts the volume read-only inside the container. False
	// (read-write) for every caller before internal/backup's volume
	// archiver started setting it explicitly true, so this is
	// byte-identical to every mount created before this field existed.
	ReadOnly bool
}