docker

type ArchiveRuntime interface {
	// CopyFromContainer streams the tar of path (absolute, inside the container).
	CopyFromContainer(ctx context.Context, containerID, path string, maxBytes int64) (io.ReadCloser, PathStat, error)
	// CopyToContainer extracts the tar (optionally gzip) in content under dir.
	CopyToContainer(ctx context.Context, containerID, dir string, content io.Reader, maxBytes int64) error
}

type BindMount struct {
	HostPath      string
	ContainerPath string
	ReadOnly      bool
}

type Browser struct {
	ID string
	// Addr is the host loopback address the debug port is published on.
	Addr string
	// contains filtered or unexported fields
}

type BrowserSpec struct {
	Name    string
	Image   string
	Command []string
	Env     map[string]string
	Labels  map[string]string
	// Network is the only network the container joins; empty means none.
	Network     string
	User        string
	MemoryBytes int64
	NanoCPUs    int64
	PidsLimit   int64
	ShmBytes    int64
	// Tmpfs maps a container path to its tmpfs mount options.
	Tmpfs map[string]string
	// DebugPort is the container port published to 127.0.0.1 on a random host port.
	DebugPort int
}

type CPUStatsRaw struct {
	TotalUsageNanos  uint64
	SystemUsageNanos uint64
	OnlineCPUs       uint32
}

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

type ClientOption func(*Client)

type ContainerMount struct {
	Source      string
	Destination string
}

type ContainerNetwork struct {
	Name      string
	IPAddress string
}

type ContainerSpec struct {
	Name      string
	Image     string
	Ports     []PortBinding
	Env       map[string]string
	Resources *Resources
	// GPU, when non-nil, attaches NVIDIA GPUs through the nvidia
	// container runtime. nil means no GPU device request.
	GPU *GPURequest
	// ShmSizeBytes sizes /dev/shm. 0 keeps Docker's default.
	ShmSizeBytes int64
	// 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
	// ExtraHosts are "name:ip" entries Docker writes into /etc/hosts, used
	// to resolve a cross-node database's mesh name without a DNS server.
	ExtraHosts []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. Client.Create merges in
	// its own configured instance label (WithInstanceLabel) on top of
	// whatever's here; that merge never mutates this map.
	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
	// OnPull, when set, receives throttled image pull progress from Create.
	// Not carried over the agent transport: a remote node pulls silently.
	OnPull func(PullEvent)
	// 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
	// ForcePull skips ensureImage's local-presence check and always pulls
	// Image fresh, even when a tag by that name already exists locally:
	// the only way a caller can be sure a mutable tag (":latest" and
	// similar) actually reflects a real upstream update rather than
	// whatever Docker's own tag-based caching happened to keep around.
	// False is unchanged from every container this codebase created
	// before this field existed. Populated from
	// store.DesiredService.PullPolicy == store.PullPolicyAlways.
	ForcePull bool
	// CapAdd lists Linux capabilities added beyond Docker's own default
	// set (container.HostConfig.CapAdd), nil meaning none, unchanged from
	// every container this codebase created before this field existed.
	// First caller: internal/reconcile/application's egress sidecar,
	// which needs NET_ADMIN to install iptables/ipset rules inside the
	// network namespace it shares with the app container.
	CapAdd []string
	// NetworkMode sets container.HostConfig.NetworkMode directly, the
	// Engine API's own string format (e.g. "container:<id>" to join
	// another container's network namespace instead of getting one of
	// its own). Empty leaves HostConfig.NetworkMode unset, Docker's
	// default ("default", meaning the Network field above or the default
	// bridge network), unchanged from every container this codebase
	// created before this field existed. Mutually meaningful alongside
	// Network only in the sense that Docker itself rejects combining a
	// non-default NetworkMode with an EndpointsConfig attachment; callers
	// that set NetworkMode leave Network nil.
	NetworkMode string
	// CPUShares is the relative CPU weight under contention (Docker's
	// default is 1024). 0 keeps the default. Local nodes only; not carried
	// over the agent transport.
	CPUShares int64
	// OomScoreAdj biases the kernel OOM killer toward this container
	// (higher dies first). 0 keeps the default. Local nodes only.
	OomScoreAdj int
	// PidsLimit overrides the hardening pids limit when positive.
	PidsLimit int64
	// Hardened forces the strictest container profile whatever the global
	// hardening mode: read-only root filesystem, every capability dropped
	// with none added back, no-new-privileges, a PID limit and a small
	// noexec /tmp. Used for untrusted workloads such as plugins.
	Hardened bool
	// User runs the container process as this uid[:gid]. Empty keeps the image's user.
	User string
}

type ContainerState struct {
	ID    string
	Name  string
	Image string
	// ImageID is the local image ID the container actually runs, empty
	// when the transport does not report it.
	ImageID string
	// Created is when the container was created, zero when unknown.
	Created time.Time
	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
	// ConfiguredPorts are the bindings the container was created with,
	// read only for a stopped container (whose Ports is always empty) so a
	// caller can still tell a stale port from a current one.
	ConfiguredPorts []PortBinding
	// Labels are the container's own Docker labels, verbatim, including
	// internal/spec.InstanceLabelKey when the creating control-plane
	// instance set one. Callers doing cleanup/stale-detection across a
	// name-prefix match (internal/reconcile/application's
	// staleContainers) use this to additionally confirm a matching-name
	// container was actually created by this same instance before
	// treating it as this service's own leftover; see
	// InstanceLabelKey's own doc comment for why a name/brand match
	// alone isn't enough on a Docker daemon shared by more than one
	// control-plane instance.
	Labels map[string]string
	// Networks lists the Docker networks the container is attached to with
	// its address on each. Only the local Docker client reports it.
	Networks []ContainerNetwork
}

type ContainerStats struct {
	// CPUPercent is 0-100 per core, computed from this one-shot
	// response's own PreCPUStats, which some Docker installs (Docker
	// Desktop's VM-backed daemon) leave empty. A periodic poller should
	// use CPURaw plus its own previous sample instead (see CPUPercent
	// the function below).
	CPUPercent float64
	// CPURaw is this sample's raw counters, for a caller that polls on
	// an interval and keeps its own previous sample.
	CPURaw CPUStatsRaw
	// 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 CreateDeclaration struct {
	Name        string
	HostNetwork bool
	GPU         bool
	BindPaths   []string
	CapAdd      []string
}

type CreateDeclarer interface {
	DeclareCreate(CreateDeclaration) func()
}

type DaemonSecurity struct {
	Rootless bool
	// UsernsRemap means container root maps to an unprivileged host user.
	UsernsRemap bool
	Options     []string
}

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 ExitState struct {
	Running   bool
	OOMKilled bool
	ExitCode  int
	// RestartCount and StartedAt are zero when the transport cannot report
	// them (the remote agent protocol does not carry them yet).
	RestartCount int
	StartedAt    time.Time
	// FinishedAt is when the container last stopped; zero while running or
	// when the transport cannot report it.
	FinishedAt time.Time
}

type ExitStateInspector interface {
	// InspectExitState returns the container's exit state, or (nil, nil)
	// if no such container exists, the same "not found is a valid
	// observed state" contract InspectByName documents below.
	InspectExitState(ctx context.Context, name string) (*ExitState, error)
}

type GPURequest struct {
	Count     int
	DeviceIDs []string
}

type HardeningConfig struct {
	Mode HardeningMode
	// PidsLimit is the per-container process cap; 0 or negative disables it.
	PidsLimit int64
	// ExtraCaps are operator-granted capabilities added on top of
	// MinimalCapabilities for every container.
	ExtraCaps []string
}

type HardeningMode string

type HardeningReport struct {
	Mode            HardeningMode
	Applied         bool
	CapDrop         []string
	CapAdd          []string
	NoNewPrivileges bool
	PidsLimit       int64
}

type ImageDetailInspector interface {
	InspectImageDetails(ctx context.Context, ref string) (*ImageDetails, error)
	NodePlatform(ctx context.Context) (NodePlatform, error)
}

type ImageDetails struct {
	ID             string
	Arch, OS       string
	SizeBytes      int64
	Entrypoint     []string
	Cmd            []string
	ExposedPorts   []string
	HasHealthcheck bool
	Healthcheck    []string
}

type ImageInfo struct {
	Tag       string
	CreatedAt time.Time
}

type ImageInspector interface {
	InspectImageID(ctx context.Context, ref string) (string, error)
}

type ImageLayerInspector interface {
	InspectImageLayers(ctx context.Context, ref string) ([]string, error)
}

type ImageLoader interface {
	LoadImage(ctx context.Context, r io.Reader) error
}

type ImagePinner interface {
	TagImage(ctx context.Context, source, target string) error
	UntagImage(ctx context.Context, ref string) error
}

type ImageResolver interface {
	ResolveImage(ctx context.Context, ref string, auth *RegistryAuth, requireFresh bool) (ResolvedImage, error)
}

type ImageSource string

type LabeledContainer struct {
	ID      string
	Name    string
	Created time.Time
	Labels  map[string]string
}

type LifecycleEvent struct {
	// Action is create, start, die, oom, kill, stop or health_status.
	Action    string
	Health    string
	ExitCode  int
	HasExit   bool
	OOMKilled bool
	Time      time.Time
}

type LifecycleWatcher interface {
	WatchContainer(ctx context.Context, name string) (<-chan LifecycleEvent, <-chan error)
}

type LocalContainer struct {
	Name     string
	Image    string
	Running  bool
	Networks []LocalNetwork
	// Ports are every port the image exposes, published or not.
	Ports []int
	// Published are the host ports this container publishes.
	Published   []int
	Mappings    []PortMapping
	Mounts      []ContainerMount
	NetworkMode string
	Args        []string
	ExtraHosts  []string
}

type LocalNetwork struct {
	Name string
	IP   string
	// Gateway is the host side of the network, reachable from the container.
	Gateway string
}

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 NamedVolume struct {
	Name      string
	SizeBytes int64  // -1 if the volume driver doesn't report size
	CreatedAt string // Docker's own volume creation timestamp, RFC3339
	// Mounted reports whether this volume is currently attached to any
	// container, running or stopped, the same mountedVolumeNames signal
	// PruneAnonymousVolumes already relies on. A caller can use this as
	// a second, independent guard on top of desired-state absence: this
	// project's own containers are only ever created from desired state,
	// so a volume neither in desired state nor mounted anywhere is
	// orphaned by two independent signals, not one.
	Mounted bool
}

type NetworkAdmin interface {
	DescribeNetworks(ctx context.Context, prefix string) ([]NetworkDetail, error)
	RemoveNetworkIfEmpty(ctx context.Context, name string) (bool, error)
	NetworkPoolUsage(ctx context.Context) (PoolUsage, error)
}

type NetworkAttachment struct {
	Name  string
	Alias string
}

type NetworkDetail struct {
	ID       string
	Name     string
	Labels   map[string]string
	Subnets  []string
	Created  time.Time
	Attached int
}

type NetworkInfo struct {
	ID   string
	Name string
	// Labels are the network's own Docker labels, verbatim. Same
	// cross-instance-ownership purpose as ContainerState.Labels above:
	// NetworkCleanupController checks internal/spec.InstanceLabelKey
	// here before treating a matching-name network as an orphan of this
	// instance's own apps.
	Labels map[string]string
}

type NetworkPool struct {
	Base netip.Prefix
}

type NetworkShareVolumeOpts struct {
	Protocol     string
	Host         string
	RemotePath   string
	MountOptions string
	Username     string
	Password     string
}

type NodePlatform struct {
	Arch, OS string
}

type OneShotResult struct {
	ExitCode int64
	Stdout   []byte
	Stderr   []byte
}

type OneShotSpec struct {
	Name    string
	Image   string
	Command []string
	Env     map[string]string
	Labels  map[string]string
	// Files are copied into the container before it starts, keyed by absolute path.
	Files map[string][]byte
	// Volumes maps a named volume to its mount path; each is created if missing.
	Volumes     map[string]string
	MemoryBytes int64
	NanoCPUs    int64
	PidsLimit   int64
	// MaxOutput caps captured stdout and stderr each; 0 means 32 MiB.
	MaxOutput int64
}

type PathStat struct {
	Name       string
	Size       int64
	Mode       os.FileMode
	LinkTarget string
}

type PoolExhaustedError struct {
	Pool     string
	InUse    int
	Capacity int
	Daemon   bool
}

type PoolUsage struct {
	Pool     string
	Enabled  bool
	Capacity int
	InUse    int
}

type PortBinding struct {
	ContainerPort int
	HostPort      int
	// HostIP is the interface a published port binds to. Empty is
	// treated as 0.0.0.0 (every interface) by Create, matching Docker's
	// own default: resolving the "private"/"public"/literal-IP shorthand
	// this maps from (internal/bindaddr) into a concrete IP is the
	// caller's job, the same "translation is the caller's job, keep this
	// package spec-agnostic" reasoning Resources' own doc comment gives.
	HostIP string
	// Protocol is "tcp" or "udp". Empty is treated as "tcp" by Create.
	Protocol string
}

type PortMapping struct {
	Private int
	Public  int
}

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 PullConfig struct {
	Interval     time.Duration
	MinPercent   int
	MaxLayerLine int
}

type PullEvent struct {
	Phase PullPhase
	Ref   string
	// Aggregate view, set on Progress and Done.
	Layers, LayersDone, Extracting, Existing int
	BytesCurrent, BytesTotal                 int64
	Percent                                  int
	// Layer view, set on PullPhaseLayer.
	LayerID, LayerState string
	LayerCurrent        int64
	LayerTotal          int64
	// Final status line and digest, set on Done.
	Status string
	Digest string
}

type PullPhase string

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

type RegistryAuth struct {
	Username string
	Password string
}

type ResolvedImage struct {
	// Ref is what to create containers from: the input pinned to Digest
	// when a registry digest is known, otherwise the input unchanged.
	Ref string
	// Digest is the registry digest (a manifest list digest for a
	// multi-arch image), empty when only a local image ID is known.
	Digest string
	// LocalID is the local image ID when the image was found only locally.
	LocalID string
	Source  ImageSource
	// RegistryErr is why the registry lookup failed, for Cache and None.
	RegistryErr error
}

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 RunOutcome struct {
	ContainerID string
	ExitCode    int
	OOMKilled   bool
	// Output is the tail of the container's combined stdout and stderr.
	// OutputCaptured is false when the node's transport cannot return logs.
	Output         string
	OutputCaptured bool
}

type RunToCompletionRuntime interface {
	RunToCompletion(ctx context.Context, spec ContainerSpec, maxOutput int) (RunOutcome, error)
}

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)

	// NetworkConnect attaches containerID to network by name. Idempotent:
	// already being attached is not an error, since a reconciler calls
	// this on every pass, not just once.
	NetworkConnect(ctx context.Context, network, containerID string) error

	// NetworkDisconnect detaches containerID from network by name. Not
	// being attached is not an error, for the same level-triggered
	// reason RemoveNetwork's own doc comment gives. force matches the
	// Engine API's own NetworkDisconnect force flag: detach even if the
	// container believes it's still using that network.
	NetworkDisconnect(ctx context.Context, network, containerID string, force bool) 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 RuntimeInfo struct {
	Kind     RuntimeKind
	Rootless bool
	// Host is the docker host URL (unix://... or tcp://...) this was
	// classified from.
	Host string
	// Source is the env var name that supplied Host, or "detected" for a
	// well-known socket path found on disk, or "default" for the
	// standard rootful fallback.
	Source string
}

type RuntimeKind string

type ServiceUser struct {
	Name        string
	Root        bool
	DockerGroup bool
}

type StatsInspector interface {
	Stats(ctx context.Context, containerID string) (ContainerStats, 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
}