container

type ContainerDriver interface {
	// Login authenticates with a container registry.
	Login(ctx context.Context, server, username, password string) error

	// Pull fetches an image from a registry.
	Pull(ctx context.Context, image string) error

	// Exec runs a command inside a running container and captures output.
	Exec(ctx context.Context, nameOrID string, command []string, opts ExecOptions) (*ExecResult, error)

	// ExecStream runs a command inside a running container, calling fn for each output line.
	ExecStream(ctx context.Context, nameOrID string, command []string, opts ExecOptions, fn func(stream, line string)) (*ExecResult, error)

	// ImageList returns locally available images.
	ImageList(ctx context.Context) ([]ImageInfo, error)

	// ImageRemove removes a local image.
	ImageRemove(ctx context.Context, image string) error

	// Run creates and starts a container, returning its ID.
	Run(ctx context.Context, image string, opts RunOptions) (string, error)

	// Stop stops a running container (graceful then force).
	Stop(ctx context.Context, nameOrID string) error

	// WaitStopped polls until the container is no longer running, or the
	// timeout elapses. Returns true if the container reached a stopped
	// state, false if the timeout was hit first. An error is returned if
	// the container cannot be found/inspected for reasons other than "not
	// running" (e.g. it was fully removed while waiting is treated as stopped).
	WaitStopped(ctx context.Context, nameOrID string, timeout time.Duration) (bool, error)

	// Remove removes a stopped container.
	Remove(ctx context.Context, nameOrID string) error

	// Inspect returns details about a container.
	Inspect(ctx context.Context, nameOrID string) (*ContainerInfo, error)

	// List returns all containers (running and stopped).
	List(ctx context.Context) ([]ContainerInfo, error)

	// VolumeCreate creates a named volume. size is optional (e.g. "20G") and
	// only honoured by Apple Containers; other drivers silently ignore it.
	VolumeCreate(ctx context.Context, name, size string) error

	// VolumeRemove removes a named volume.
	VolumeRemove(ctx context.Context, name string) error

	// VolumeList returns all named volumes.
	VolumeList(ctx context.Context) ([]string, error)
}

type ContainerInfo struct {
	ID      string
	Name    string
	Status  string
	Image   string
	Running bool
}

type ExecOptions struct {
	Env     []string
	WorkDir string
	User    string
}

type ExecResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

type ImageInfo struct {
	ID        string
	Reference string
	Digest    string
	Size      int64
}

type Options struct {
	// DockerSock and PodmanSock override the default operator endpoints
	// (empty = default). They are trusted and never checked.
	DockerSock, PodmanSock string

	// AppleCLI is the absolute path of Apple's `container` CLI (empty =
	// DefaultAppleCLI). It is never looked up on PATH.
	AppleCLI string

	// Paths is the filesystem jail. When it restricts paths, a Unix socket a
	// script names in Client(socket=...) and every host path a script binds
	// into a container with run(volumes=...) must lie within it.
	Paths fssecurity.Config

	// Policy is the network policy. When set, a TCP/HTTP(S) endpoint a
	// script names in Client(socket=...) must pass it, and run() refuses
	// network="host", which would give the container the host's loopback
	// services.
	Policy *netsecurity.Config

	// DenyPrivileged refuses run(privileged=True). Privileged containers are
	// allowed by default; a privileged container can reach every host device
	// and disk, so set this where scripts must not control the host.
	DenyPrivileged bool
}

type RunOptions struct {
	Name       string
	Ports      []string // "hostPort:containerPort"
	Env        []string // "KEY=value"
	Volumes    []string // "name:/path" or "/host:/container"
	Command    []string
	Privileged bool
	Network    string
}