runtime

type Container struct {
	ID      string
	Name    string
	State   string // running, exited, paused, ...
	Labels  map[string]string
	Mounts  []Mount
	Project string // com.docker.compose.project, empty if not a compose service
	Service string // com.docker.compose.service, empty if not a compose service

	// Image is the container's image reference. Populated on both List and
	// Inspect.
	Image string

	// LogDriver is the effective logging driver, e.g. "json-file", "local",
	// "journald". Inspect-only (the list summary carries no HostConfig), and
	// empty when unknown.
	LogDriver string

	// Env holds the container's environment entries as KEY=VALUE strings.
	// Inspect-only. Core surfaces the raw slice: callers that only need the
	// names must split it themselves and must not log the values.
	Env []string

	// Health is the container health status when a HEALTHCHECK is defined,
	// e.g. "healthy", "unhealthy", "starting". Empty when the container has no
	// healthcheck. Inspect-only.
	Health string

	// ExitCode is the exit code of the container's main process from its last
	// run, read off Docker's inspect State.ExitCode. It is 0 for a container
	// that is still running or that exited cleanly, so a consumer treating a
	// non-zero value as a failure must pair it with the State ("exited") or a
	// die event rather than reading it in isolation. Inspect-only.
	ExitCode int

	// OOMKilled reports whether the container's last exit was the kernel OOM
	// killer reaping it, read off Docker's inspect State.OOMKilled. Inspect-only.
	OOMKilled bool

	// RestartCount is how many times the runtime has restarted this container
	// under its restart policy, read off Docker's inspect RestartCount. A
	// consumer watching for a crash loop reads this alongside the start events
	// from Watch; core surfaces the count and leaves the loop policy to the
	// consumer. Inspect-only.
	RestartCount int

	// Networks lists the container's network attachments and the IP
	// addresses it holds on each. Unlike Image/LogDriver/Env/Health, the
	// list summary carries this data at no extra cost (it is already part
	// of the same API response), so Networks is populated on both List and
	// Inspect.
	Networks []ContainerNetwork
}

type ContainerNetwork struct {
	Name string
	ID   string
	IPs  []netip.Addr
}

type ContainerSpec struct {
	// Name is the container name. Empty lets the engine assign one.
	Name string
	// Image is the image reference to create from. Call PullImage first if it
	// may not be present locally.
	Image string
	// Cmd overrides the image's default command when non-empty.
	Cmd []string
	// Entrypoint overrides the image's default entrypoint when non-empty.
	Entrypoint []string
	// Env holds environment entries as KEY=VALUE strings.
	Env []string
	// Labels are stamped on the container for identification and cleanup.
	Labels map[string]string
	// Mounts attaches named volumes into the container.
	Mounts []VolumeMount
	// Network is the network name or id to attach to. Empty uses the engine's
	// default network; a verify passes the isolated network from CreateNetwork.
	Network string
	// Start starts the container immediately after creating it.
	Start bool
}

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

type Event struct {
	Type   EventType
	ID     string
	Name   string
	Labels map[string]string
}

type EventType string

type ExecHandle struct {
	Stdout io.Reader
	Wait   func() (exitCode int, err error)
}

type ExecSpec struct {
	Cmd  []string
	User string // empty means the container's default user

	// Stdin, when non-nil, is attached to the command's standard input and
	// copied to completion, after which the write side is closed so the
	// command sees EOF. It is nil for the common case (a quiesce or a
	// dump-producing command that reads nothing on stdin); a stream-restore
	// sets it to pipe a backup dump into the restoring process. When nil, Exec
	// behaves exactly as it always has, so this field is backward compatible
	// with every existing caller.
	Stdin io.Reader
}

type Mount struct {
	Type        MountType
	Name        string // named-volume name, empty for binds and tmpfs
	Source      string // host-side path, empty for tmpfs
	Destination string // container-side path
	ReadOnly    bool
}

type MountType string

type Network struct {
	Name     string
	ID       string
	Driver   string
	Internal bool
	Subnets  []netip.Prefix
	Labels   map[string]string
}

type NetworkInspector interface {
	// ListNetworks returns every network the runtime knows about, with its
	// subnet CIDRs and whether it is marked internal.
	ListNetworks(ctx context.Context) ([]Network, error)
}

type NetworkSpec struct {
	Name   string
	Labels map[string]string
}

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

type Provisioner interface {
	// PullImage pulls ref if the runtime does not already have it locally. It
	// is a no-op when the image is already present, so a caller may call it
	// unconditionally before CreateContainer.
	PullImage(ctx context.Context, ref string) error

	// CreateNetwork creates an isolated network and returns its id. The
	// network is always internal (no external routing, no gateway to the host
	// or the internet), so a container attached to it cannot reach production
	// services or the network at large. That isolation is the entire point of
	// the capability and is not configurable: a restored copy proven on such a
	// network is a DORA-style segregation fact the caller can assert directly
	// via NetworkInspector.ListNetworks (the created network reports
	// Internal == true).
	CreateNetwork(ctx context.Context, spec NetworkSpec) (id string, err error)

	// RemoveNetwork removes a network by id or name. It fails if a container
	// is still attached, so remove containers first.
	RemoveNetwork(ctx context.Context, id string) error

	// CreateVolume creates a fresh empty named volume and returns its name. A
	// verify restores into one of these, never a real service volume.
	CreateVolume(ctx context.Context, spec VolumeSpec) (name string, err error)

	// RemoveVolume removes a named volume. It fails if a container still holds
	// it, so remove the container first (or use RemoveContainer, which also
	// drops the container's anonymous volumes).
	RemoveVolume(ctx context.Context, name string) error

	// CreateContainer creates a container from spec.Image with the spec's
	// volume mounts, on the spec's network, with its env, labels, and optional
	// command or entrypoint override. It publishes no ports. The container is
	// created but not started unless spec.Start is set (starting a
	// separately-created container otherwise uses the base Runtime.Start). It
	// returns the container id even on a start error, so the caller can still
	// tear the container down.
	CreateContainer(ctx context.Context, spec ContainerSpec) (id string, err error)

	// RemoveContainer removes a container by id or name along with its
	// anonymous volumes. force removes a running container (equivalent to a
	// stop-then-remove) rather than failing.
	RemoveContainer(ctx context.Context, id string, force bool) error
}

type Runtime interface {
	// List returns every container the runtime knows about, running or not.
	List(ctx context.Context) ([]Container, error)

	// Inspect returns a single container by ID or name.
	Inspect(ctx context.Context, id string) (Container, error)

	// Watch streams lifecycle events until ctx is cancelled. The error channel
	// carries a terminal error and is then closed alongside the event channel.
	Watch(ctx context.Context) (<-chan Event, <-chan error)

	// Exec runs a command inside a running container and returns a handle whose
	// Stdout the caller reads (for stream backups it is piped straight into the
	// engine's stdin) before calling Wait for the exit code.
	Exec(ctx context.Context, id string, spec ExecSpec) (*ExecHandle, error)

	// Stop stops a running container, waiting up to timeoutSeconds before a kill.
	Stop(ctx context.Context, id string, timeoutSeconds int) error

	// Start starts a stopped container.
	Start(ctx context.Context, id string) error

	// Kill sends a signal to a running container, e.g. "SIGHUP" to prompt a
	// collector to reload its configuration.
	Kill(ctx context.Context, id string, signal string) error

	// Restart restarts a container, using the runtime's default stop timeout.
	Restart(ctx context.Context, id string) error

	// Close releases the underlying client.
	Close() error
}

type VolumeMount struct {
	// Volume is the named volume to mount, as returned by CreateVolume.
	Volume string
	// Destination is the container-side path to mount it at.
	Destination string
	// ReadOnly mounts the volume read-only when true.
	ReadOnly bool
}

type VolumeSpec struct {
	Name   string
	Labels map[string]string
}