container

type APIClient interface {
	ImagePull(ctx context.Context, refStr string, options image.PullOptions) (io.ReadCloser, error)
	ImageList(ctx context.Context, options image.ListOptions) ([]image.Summary, error)
	ContainerCreate(
		ctx context.Context,
		cfg *dockercontainer.Config,
		hostConfig *dockercontainer.HostConfig,
		networkingConfig any,
		platform any,
		containerName string,
	) (dockercontainer.CreateResponse, error)
	ContainerStart(ctx context.Context, containerID string, options dockercontainer.StartOptions) error
	ContainerStop(ctx context.Context, containerID string, options dockercontainer.StopOptions) error
	ContainerRemove(ctx context.Context, containerID string, options dockercontainer.RemoveOptions) error
	Ping(ctx context.Context) (any, error)
	Close() error
}

type Config struct {
	Logger *slog.Logger
	// Injection overrides the env-derived DNS/CA injection for spawned containers.
	Injection   *Injection
	Runtime     RuntimeName
	PoolSize    int
	IdleTimeout time.Duration
}

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

type ExecAPIClient interface {
	ContainerExec(
		ctx context.Context,
		containerID string,
		cmd []string,
	) (stdout, stderr []byte, exitCode int, err error)
}

type ExecResult struct {
	// Stdout and Stderr hold the demultiplexed output streams.
	Stdout string
	Stderr string
	// ExitCode is the command's exit status.
	ExitCode int
}

type ExecStreamAPIClient interface {
	ContainerExecStream(
		ctx context.Context,
		containerID string,
		cmd []string,
		stdout, stderr io.Writer,
	) (int, error)
}

type ExitWaiter interface {
	// WaitExit blocks until the container stops and returns its exit code.
	WaitExit(ctx context.Context, containerID string) (int, error)
}

type ImagePusher interface {
	// TagAndPush tags the local image source as target, pushes target, and returns the pushed digest when known.
	TagAndPush(ctx context.Context, source, target string) (string, error)
}

type Injection struct {
	CAFile string
	DNS    []string
}

type LogReader interface {
	// ReadLogs writes the last tail lines (all when tail is empty) to the writers; follow keeps streaming.
	ReadLogs(ctx context.Context, containerID, tail string, follow bool, stdout, stderr io.Writer) error
}

type LogStreamer interface {
	// StreamLogs writes the container's stdout and stderr to the given writers as they are produced.
	// It blocks until the container is removed or stops, or ctx ends.
	StreamLogs(ctx context.Context, containerID string, stdout, stderr io.Writer) error
}

type LogsAPIClient interface {
	ContainerLogs(ctx context.Context, containerID string, options dockercontainer.LogsOptions) (io.ReadCloser, error)
}

type NetworkAPIClient interface {
	NetworkCreate(ctx context.Context, name string) (string, error)
	NetworkConnect(ctx context.Context, networkID, containerID string) error
	NetworkRemove(ctx context.Context, networkID string) error
}

type NetworkRuntime interface {
	// CreateNetwork creates a bridge network and returns its ID.
	CreateNetwork(ctx context.Context, name string) (string, error)
	// ConnectNetwork attaches a running container to the network.
	ConnectNetwork(ctx context.Context, networkID, containerID string) error
	// RemoveNetwork deletes the network.
	RemoveNetwork(ctx context.Context, networkID string) error
}

type OCIRuntimeAPIClient interface {
	Runtimes(ctx context.Context) ([]string, error)
}

type OCIRuntimeLister interface {
	OCIRuntimes(ctx context.Context) ([]string, error)
}

type PooledContainer struct {
	// LastUsed is the timestamp of the last time this container was used.
	LastUsed time.Time
	// ID is the container ID.
	ID string
	// Image is the image the container was started from.
	Image string
	// InUse indicates whether the container is currently handling an invocation.
	InUse bool
}

type PushAPIClient interface {
	ImageTag(ctx context.Context, source, target string) error
	ImagePush(ctx context.Context, ref string) (string, error)
}

type Runtime interface {
	// Ping checks whether the container daemon is reachable.
	Ping(ctx context.Context) error
	// PullImage pulls the specified image from the registry.
	PullImage(ctx context.Context, imageRef string) error
	// HasImage reports whether the given image reference is already present locally.
	HasImage(ctx context.Context, imageRef string) (bool, error)
	// CreateAndStart creates a new container from spec and starts it.
	// Returns the container ID.
	CreateAndStart(ctx context.Context, spec Spec) (string, error)
	// StopAndRemove stops and removes a container.
	StopAndRemove(ctx context.Context, containerID string) error
	// Exec runs cmd inside a running container and waits for it to finish.
	// A non-zero exit status is reported in the result, not as an error.
	Exec(ctx context.Context, containerID string, cmd []string) (ExecResult, error)
	// AcquireWarm returns a warm container from the pool for the given image.
	AcquireWarm(ctx context.Context, spec Spec) (*PooledContainer, error)
	// ReleaseContainer marks a pooled container as idle.
	ReleaseContainer(containerID string) error
	// ReapIdleContainers stops and removes containers idle longer than IdleTimeout.
	ReapIdleContainers(ctx context.Context)
	// StartReaper launches a background goroutine that periodically reaps idle containers.
	StartReaper(ctx context.Context, interval time.Duration)
	// Close releases resources held by the runtime client.
	Close() error
}

type RuntimeName string

type Spec struct {
	Image   string
	Name    string
	Network string
	// WorkingDir overrides the image's working directory; empty keeps it.
	WorkingDir string
	// User runs the container process as uid[:gid]; empty keeps the image's user.
	User string
	// GroupAdd lists supplementary group IDs for the container process.
	GroupAdd []string
	// OCIRuntime selects the daemon-registered OCI runtime (e.g. runsc); empty uses the daemon default.
	OCIRuntime string
	Env        []string
	Mounts     []string
	Cmd        []string
	Entrypoint []string
	Ports      []string
	Tmpfs      []string
	Privileged bool
	// MemoryBytes caps container memory; zero is unlimited.
	MemoryBytes int64
	// NanoCPUs caps CPU in billionths of a CPU; zero is unlimited.
	NanoCPUs int64
}

type Starter interface {
	CreateAndStart(ctx context.Context, spec Spec) (string, error)
}

type StreamExecer interface {
	// ExecStream runs cmd, writing combined stdout and stderr to out as produced; it returns the exit status.
	ExecStream(ctx context.Context, containerID string, cmd []string, out io.Writer) (int, error)
}

type WaitAPIClient interface {
	ContainerWait(
		ctx context.Context,
		containerID string,
		options dockercontainer.WaitOptions,
	) dockercontainer.WaitResult
}