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
	Runtime     RuntimeName
	PoolSize    int
	IdleTimeout time.Duration
}

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

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 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
	// 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 is the container image reference.
	Image string
	// Name is an optional container name.
	Name string
	// Env is a list of environment variables in KEY=VALUE format.
	Env []string
	// Mounts is a list of bind-mount strings in HOST:CONTAINER[:OPTIONS] format.
	Mounts []string
	// Cmd overrides the image's default CMD.
	Cmd []string
	// Entrypoint overrides the image's default ENTRYPOINT.
	Entrypoint []string
}