Documentation
¶
Overview ¶
Package docker provides a Docker integration layer for Gopherstack. It wraps the Docker SDK to support image pulling, container lifecycle management (create/start/stop/remove), volume mounts, and a simple warm-container pool with configurable idle timeout.
This package is the foundation for Lambda runtime container execution (Python, Node.js, Java, .NET, Ruby, custom images) planned for v0.7.
Index ¶
- Variables
- type APIClient
- type Client
- func (c *Client) AcquireWarm(ctx context.Context, spec ContainerSpec) (*PooledContainer, error)
- func (c *Client) Close() error
- func (c *Client) CreateAndStart(ctx context.Context, spec ContainerSpec) (string, error)
- func (c *Client) HasImage(ctx context.Context, imageRef string) (bool, error)
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) PullImage(ctx context.Context, imageRef string) error
- func (c *Client) ReapIdleContainers(ctx context.Context)
- func (c *Client) ReleaseContainer(containerID string) error
- func (c *Client) StartReaper(ctx context.Context, interval time.Duration)
- func (c *Client) StopAndRemove(ctx context.Context, containerID string) error
- type Config
- type ContainerSpec
- type PooledContainer
Constants ¶
This section is empty.
Variables ¶
var ErrContainerNotFound = errors.New("container not found")
ErrContainerNotFound is returned when a requested container does not exist in the pool.
ErrDockerUnavailable is returned when Docker is not available on the host.
var ErrPoolExhausted = errors.New("container pool exhausted")
ErrPoolExhausted is returned when no warm container is available and the pool is full.
Functions ¶
This section is empty.
Types ¶
type APIClient ¶
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 *container.Config,
hostConfig *container.HostConfig,
networkingConfig any,
platform any,
containerName string,
) (container.CreateResponse, error)
ContainerStart(ctx context.Context, containerID string, options container.StartOptions) error
ContainerStop(ctx context.Context, containerID string, options container.StopOptions) error
ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error
Ping(ctx context.Context) (any, error)
Close() error
}
APIClient is a subset of the Docker SDK client interface used by this package. It is defined as an interface to enable testing without a real Docker daemon.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the Gopherstack Docker client. It wraps the Docker SDK and provides image management and a per-image warm container pool.
func NewClient ¶
NewClient creates a new Docker Client using the host's Docker daemon. Returns ErrDockerUnavailable if Docker is not reachable.
func NewClientWithAPI ¶
NewClientWithAPI creates a Client with an injected APIClient. This is primarily intended for testing; production code should use NewClient.
func (*Client) AcquireWarm ¶
func (c *Client) AcquireWarm(ctx context.Context, spec ContainerSpec) (*PooledContainer, error)
AcquireWarm returns a warm container from the pool for the given image. If no warm container is available, a new one is created (up to PoolSize). The caller must call ReleaseContainer when done.
Note: pool capacity is a soft limit. When multiple goroutines call AcquireWarm concurrently, the pool may temporarily exceed PoolSize by the number of concurrent callers that see no idle container and concurrently create new ones.
func (*Client) CreateAndStart ¶
CreateAndStart creates a new container from spec and starts it. Returns the container ID.
func (*Client) HasImage ¶
HasImage reports whether the given image reference is already present locally.
func (*Client) PullImage ¶
PullImage pulls the specified image from the registry. The pull output is discarded; callers that need progress should use the Docker SDK directly.
func (*Client) ReapIdleContainers ¶
ReapIdleContainers stops and removes containers that have been idle longer than IdleTimeout. It is intended to be called periodically by a background goroutine.
func (*Client) ReleaseContainer ¶
ReleaseContainer marks a pooled container as idle. If the container is not in the pool, ErrContainerNotFound is returned.
func (*Client) StartReaper ¶
StartReaper launches a background goroutine that periodically reaps idle containers. It stops when ctx is cancelled.
type Config ¶
type Config struct {
// Logger is an optional structured logger.
Logger *slog.Logger
// PoolSize is the maximum number of warm containers per image.
// Defaults to 3.
PoolSize int
// IdleTimeout is the duration after which an idle container is reaped.
// Defaults to 10 minutes.
IdleTimeout time.Duration
}
Config holds configuration for the Docker integration layer.
type ContainerSpec ¶
type ContainerSpec struct {
// Image is the Docker 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
}
ContainerSpec holds the specification for creating a container.
type PooledContainer ¶
type PooledContainer struct {
// LastUsed is the timestamp of the last time this container was used.
LastUsed time.Time
// ID is the Docker 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
}
PooledContainer tracks a container managed by the warm pool.
Source Files