podman

type Client interface {
	// Pods
	PlayKube(ctx context.Context, hostID, yaml string, replace bool, networks ...string) error
	PodInspect(ctx context.Context, hostID, name string) (Pod, error)
	// WaitForPodCompletion polls every container in the named pod until each
	// has exited or timeout elapses. Returns the first non-zero exit code
	// found (in container order), else 0 if every container exited 0. A
	// timeout returns a non-nil error (ErrWaitTimeout) — never a zero exit
	// code, which would misread as success.
	WaitForPodCompletion(ctx context.Context, hostID, podName string, timeout time.Duration) (exitCode int, err error)
	PodList(ctx context.Context, hostID string, labelFilters map[string]string) ([]Pod, error)
	PodStart(ctx context.Context, hostID, name string) error
	PodStop(ctx context.Context, hostID, name string) error
	PodRestart(ctx context.Context, hostID, name string) error
	PodRemove(ctx context.Context, hostID, name string, force bool) error

	// Secrets
	SecretCreate(ctx context.Context, hostID, name string, value []byte) error
	SecretList(ctx context.Context, hostID string) ([]Secret, error)
	SecretInspect(ctx context.Context, hostID, name string) (Secret, error)
	SecretRemove(ctx context.Context, hostID, name string) error

	// Volumes
	VolumeInspect(ctx context.Context, hostID, name string) (Volume, error)
	VolumeRemove(ctx context.Context, hostID, name string, force bool) error
	// VolumeExport streams the named volume's contents from host as an
	// uncompressed tar. The caller must Close the returned reader.
	VolumeExport(ctx context.Context, hostID, name string) (io.ReadCloser, error)
	// VolumeImport unpacks an uncompressed tar (as produced by VolumeExport)
	// into the named volume on host. The volume must already exist.
	VolumeImport(ctx context.Context, hostID, name string, r io.Reader) error
	// VolumeCreate creates an empty named volume on host. Creating a volume that
	// already exists is a no-op (no error).
	VolumeCreate(ctx context.Context, hostID, name string) error

	// Stats
	// ContainerStats returns a single non-streaming resource sample for every
	// container on the host. It is one call per host; the caller attributes
	// samples to instances by container name.
	ContainerStats(ctx context.Context, hostID string) ([]ContainerStats, error)
	// VolumeUsage returns each volume's on-disk size in bytes, keyed by volume
	// name, from one `system df` call. Podman walks images, containers and
	// volumes to answer this, so it can take minutes on a large store — callers
	// must run it on a slow cadence with its own timeout, never on a hot path.
	VolumeUsage(ctx context.Context, hostID string) (map[string]int64, error)

	// Networks
	// NetworkEnsure creates the named network if absent; creating one that
	// already exists is a no-op (no error).
	NetworkEnsure(ctx context.Context, hostID, name string) error

	// Exec
	// ContainerExec runs cmd in the named running container and returns its
	// exit code and combined stdout+stderr. A non-zero exit code is NOT an
	// error; only a transport/podman failure returns a non-nil error.
	ContainerExec(ctx context.Context, hostID, container string, cmd []string) (ExecResult, error)
	// CopyToContainer writes content as a single file `name` into directory
	// `destDir` inside the running container (e.g. destDir="/etc/caddy",
	// name="Caddyfile"). destDir must already exist in the container.
	CopyToContainer(ctx context.Context, hostID, container, destDir, name string, content []byte) error

	// Logs
	ContainerLogs(ctx context.Context, hostID, container string, opts LogOptions) (<-chan LogLine, error)

	// Images
	ImagePull(ctx context.Context, hostID, ref string) error

	// Prune
	// ImagePrune removes unused images. all=false removes only dangling layers;
	// all=true also removes tagged images not used by any container.
	ImagePrune(ctx context.Context, hostID string, all bool) (PruneReport, error)
	// ContainerPrune removes stopped (exited) containers.
	ContainerPrune(ctx context.Context, hostID string) (PruneReport, error)
	// BuildCachePrune removes dangling build cache.
	BuildCachePrune(ctx context.Context, hostID string) (PruneReport, error)
	// VolumePrune removes unused (unattached) volumes. filters are libpod volume
	// prune filters (e.g. {"label!": {"podman-api.protect=true"}}) so callers can
	// protect volumes; never removes in-use volumes.
	VolumePrune(ctx context.Context, hostID string, filters map[string][]string) (PruneReport, error)

	// Health
	Ping(ctx context.Context, hostID string) error
	Version(ctx context.Context, hostID string) (string, error)
	UsedHostPorts(ctx context.Context, hostID string) ([]PortMapping, error)

	// Host
	HostInfo(ctx context.Context, hostID string) (HostInfo, error)
	// Knows reports whether hostID is a registered host this client can reach.
	// The host set is updated at construction and whenever SetHosts is called
	// (e.g. after a SIGHUP host-config reload).
	Knows(hostID string) bool
	// SetHosts replaces the client's host map at runtime. New hosts become
	// connectable; removed hosts are dropped (and their cached connections
	// cleaned up); changed connection params (addr/socket/ssh_key) invalidate
	// the cached context so the next call reopens the connection.
	SetHosts(hosts []config.Host)
}

type Container struct {
	ID   string
	Name string
	// Image is InspectContainerData.ImageDigest, which is
	// image.Digest().String(): a BARE digest with no repository, e.g.
	// "sha256:42283567cae4…". It is NOT the "repo@sha256:…" shape — measured
	// across 34 non-infra containers on engine-1 (podman 5.8.2, 2026-08-07),
	// 34/34. When podman has no digest, enrichContainer falls back to
	// InspectContainerData.Image, a bare 64-hex image ID that is not a manifest
	// digest at all; a consumer that must resolve against a registry has to
	// distinguish the two.
	Image string
	// ImageTag is InspectContainerData.ImageName, the full reference:
	// "host/repo:tag" (18/34 in the same survey) or "host/repo@sha256:…" (16/34).
	ImageTag string
	Status   string
	// Health is the container's healthcheck status: "" when the container
	// declares no healthcheck, otherwise "healthy" / "unhealthy" / "starting".
	Health string
	// HealthStartPeriod and HealthInterval are the container's *declared*
	// healthcheck timings, both zero when it declares no healthcheck. They are
	// the grace the container was promised, so readiness waits can bound
	// themselves by the spec they are verifying rather than by a fixed constant
	// that may be shorter than the first check can possibly run (#196).
	HealthStartPeriod time.Duration
	HealthInterval    time.Duration
	StartedAt         time.Time
	RestartCount      int
	Ports             []PortMapping
	Env               map[string]string
	// ExitCode is the container's last exit code, as libpod reports it. It is
	// meaningful only when Exited is true; a running container has ExitCode 0
	// (never populated) alongside Exited false.
	ExitCode int
	// Exited reports whether the container has stopped running (libpod's
	// State.Running == false). Distinguishes "never ran" / "still running"
	// from "ran and produced ExitCode".
	Exited bool
}

type ContainerStats struct {
	Name            string
	CPUNano         uint64 // cumulative CPU time, nanoseconds
	MemUsageBytes   uint64
	MemLimitBytes   uint64 // 0 when the container declares no limit
	NetRxBytes      uint64 // summed across interfaces
	NetTxBytes      uint64
	BlockReadBytes  uint64
	BlockWriteBytes uint64
	PIDs            uint64
}

type DiskUsage struct {
	Total       int64 // bytes (graphroot partition size)
	Used        int64 // bytes
	Free        int64 // bytes (Total-Used)
	Reclaimable int64 // bytes reclaimable from dangling volumes (system df)
}

type ExecResult struct {
	ExitCode int
	Output   string // combined stdout+stderr
}

type HostInfo struct {
	CPUs       int         // logical CPUs
	MemTotal   int64       // bytes
	MemFree    int64       // bytes
	MemUsedPct float64     // derived: (MemTotal-MemFree)/MemTotal*100, 0 if MemTotal==0
	CPUPct     *float64    // average CPU utilization since boot (user+system %); nil when libpod omits CPUUtilization
	LoadAvg    *[3]float64 // 1/5/15-min; nil when unavailable
	Disk       DiskUsage
}

type LogLine struct {
	Container string
	Stream    string // stdout / stderr
	Time      time.Time
	Line      string
}

type LogOptions struct {
	Tail   int    // 0 = all
	Since  string // RFC3339 or duration like "5m"; "" = beginning
	Follow bool
}

type Pod struct {
	ID         string
	Name       string
	Status     string // "Running", "Created", "Exited", etc.
	Created    time.Time
	Containers []Container
	Labels     map[string]string
	// InfraID is the ID of the pod's infra container, empty when the pod has
	// none. It is the only reliable way to tell an infra container from an app
	// container: names collide (`podman kube play` names containers
	// <pod>-<containerName>) and an infra container reports no image at all,
	// which is indistinguishable from an app container whose inspect failed.
	InfraID string
}

type PortMapping struct {
	HostIP        string
	HostPort      int
	ContainerPort int
	Protocol      string // tcp/udp
	Pod           string // pod name owning this port (empty if not derivable)
	Container     string // container name owning this port (empty if not derivable)
}

type PruneReport struct {
	Items     []string
	Reclaimed int64
}

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

type Secret struct {
	Name      string
	CreatedAt time.Time
}

type Volume struct {
	Name      string
	SizeBytes int64
}