containers

type Container struct {
	Name      string
	State     string
	CreatedAt time.Time
	Labels    map[string]string
	SSHPort   int32
	VNCPort   int32
}

type Event struct {
	Name       string
	Attributes map[string]string
}

type Info struct {
	CPUs          int
	DockerDesktop bool
	Rootless      bool
}

type InspectInfo struct {
	Runtime      string
	ID           string
	Name         string
	State        string
	ImageRef     string
	ImageID      string
	Platform     string
	OS           string
	Architecture string
	CPULimit     float64 // Explicit quota in CPU units; zero means unrestricted.
	CPUSet       []int   // Sorted configured logical CPU IDs; empty means inherited.
	Mounts       []Mount
	Labels       map[string]string
}

type Mount struct {
	HostPath      string
	ContainerPath string
	ReadOnly      bool
}

type Runtime interface {
	// Name returns the normalized runtime name, such as "docker" or "podman".
	Name() string
	// Executable returns the runtime command used for execution.
	Executable() string
	// Run executes a runtime command and returns trimmed stdout.
	Run(ctx context.Context, dir string, args ...string) (string, error)
	// RunOut executes a runtime command with stdout and stderr connected to writers.
	RunOut(ctx context.Context, dir string, stdout, stderr io.Writer, args ...string) error
	// Info queries the runtime server CPU capacity and isolation environment.
	Info(ctx context.Context) (Info, error)

	// List returns all containers known to the runtime.
	List(ctx context.Context) ([]Container, error)
	// InspectContainer returns normalized inspect metadata for one container.
	InspectContainer(ctx context.Context, name string) (*Container, error)
	// InspectInfo returns detailed normalized inspect metadata for one container.
	InspectInfo(ctx context.Context, name string) (*InspectInfo, error)
	// HostPort returns the host port mapped to containerPort.
	HostPort(ctx context.Context, containerName, containerPort string) (int32, error)

	// ImageArchitecture returns the linux architecture for image when available.
	ImageArchitecture(ctx context.Context, image string) (string, error)
	// RemoteManifestDigest queries the registry for the per-architecture manifest digest without downloading layers.
	RemoteManifestDigest(ctx context.Context, image, arch string) (string, error)
	// BaseImageIsLocal reports whether image resolves as a local image tag.
	BaseImageIsLocal(ctx context.Context, image string) bool
	// UntagImage removes an image tag.
	UntagImage(ctx context.Context, image string) error

	// Stats returns current resource usage for name.
	Stats(ctx context.Context, name string) (*Stats, error)
	// DiskUsage returns the writable container layer size in bytes.
	DiskUsage(ctx context.Context, name string) (int64, error)
	// StatsAll returns available resource samples with disk usage, alongside
	// collection errors. Containers without resource samples are omitted.
	StatsAll(ctx context.Context, names []string) (map[string]*Stats, error)
	// WatchStats streams resource usage for the named running containers.
	WatchStats(ctx context.Context, names []string) (iter.Seq2[StatsSample, error], error)
	// WatchDieEvents streams container die events for containers carrying labelKey.
	WatchDieEvents(ctx context.Context, labelKey string) (iter.Seq2[Event, error], error)
}

type Stats struct {
	CPUPerc    float64 `json:"cpu_perc"`
	MemUsed    uint64  `json:"mem_used"`
	MemLimit   uint64  `json:"mem_limit"`
	MemPerc    float64 `json:"mem_perc"`
	PIDs       int     `json:"pids"`
	NetRx      uint64  `json:"net_rx"`
	NetTx      uint64  `json:"net_tx"`
	BlockRead  uint64  `json:"block_read"`
	BlockWrite uint64  `json:"block_write"`
	DiskUsed   int64   `json:"disk_used"`
}

type StatsSample struct {
	Name  string
	Stats *Stats
}