Documentation
¶
Overview ¶
Package docker provides an adapter for the official Docker SDK.
Index ¶
- Variables
- func EncodeAuthConfig(auth domain.AuthConfig) (string, error)
- func ExtractRegistry(image string) string
- type Client
- func (c *Client) Close() error
- func (c *Client) Containers() ports.ContainerService
- func (c *Client) Events() ports.EventService
- func (c *Client) Exec() ports.ExecService
- func (c *Client) Images() ports.ImageService
- func (c *Client) Networks() ports.NetworkService
- func (c *Client) SDK() *client.Client
- func (c *Client) Services() ports.SwarmService
- func (c *Client) System() ports.SystemService
- type ClientConfig
- type ConfigAuthProvider
- type ContainerServiceAdapter
- func (s *ContainerServiceAdapter) Attach(ctx context.Context, containerID string, opts ports.AttachOptions) (*domain.HijackedResponse, error)
- func (s *ContainerServiceAdapter) CopyLogs(ctx context.Context, containerID string, stdout, stderr io.Writer, ...) error
- func (s *ContainerServiceAdapter) Create(ctx context.Context, config *domain.ContainerConfig) (string, error)
- func (s *ContainerServiceAdapter) Inspect(ctx context.Context, containerID string) (*domain.Container, error)
- func (s *ContainerServiceAdapter) Kill(ctx context.Context, containerID string, signal string) error
- func (s *ContainerServiceAdapter) List(ctx context.Context, opts domain.ListOptions) ([]domain.Container, error)
- func (s *ContainerServiceAdapter) Logs(ctx context.Context, containerID string, opts domain.LogOptions) (io.ReadCloser, error)
- func (s *ContainerServiceAdapter) Pause(ctx context.Context, containerID string) error
- func (s *ContainerServiceAdapter) Remove(ctx context.Context, containerID string, opts domain.RemoveOptions) error
- func (s *ContainerServiceAdapter) Rename(ctx context.Context, containerID string, newName string) error
- func (s *ContainerServiceAdapter) Start(ctx context.Context, containerID string) error
- func (s *ContainerServiceAdapter) Stop(ctx context.Context, containerID string, opts domain.StopOptions) error
- func (s *ContainerServiceAdapter) Unpause(ctx context.Context, containerID string) error
- func (s *ContainerServiceAdapter) Wait(ctx context.Context, containerID string) (<-chan domain.WaitResponse, <-chan error)
- type EventServiceAdapter
- type ExecServiceAdapter
- func (s *ExecServiceAdapter) Create(ctx context.Context, containerID string, config *domain.ExecConfig) (string, error)
- func (s *ExecServiceAdapter) Inspect(ctx context.Context, execID string) (*domain.ExecInspect, error)
- func (s *ExecServiceAdapter) Run(ctx context.Context, containerID string, config *domain.ExecConfig, ...) (int, error)
- func (s *ExecServiceAdapter) Start(ctx context.Context, execID string, opts domain.ExecStartOptions) (*domain.HijackedResponse, error)
- type ImageServiceAdapter
- func (s *ImageServiceAdapter) Exists(ctx context.Context, imageRef string) (bool, error)
- func (s *ImageServiceAdapter) Inspect(ctx context.Context, imageID string) (*domain.Image, error)
- func (s *ImageServiceAdapter) List(ctx context.Context, opts domain.ImageListOptions) ([]domain.ImageSummary, error)
- func (s *ImageServiceAdapter) Pull(ctx context.Context, opts domain.PullOptions) (io.ReadCloser, error)
- func (s *ImageServiceAdapter) PullAndWait(ctx context.Context, opts domain.PullOptions) error
- func (s *ImageServiceAdapter) Remove(ctx context.Context, imageID string, force, pruneChildren bool) error
- func (s *ImageServiceAdapter) Tag(ctx context.Context, source, target string) error
- type NetworkServiceAdapter
- func (s *NetworkServiceAdapter) Connect(ctx context.Context, networkID, containerID string, ...) error
- func (s *NetworkServiceAdapter) Create(ctx context.Context, name string, opts ports.NetworkCreateOptions) (string, error)
- func (s *NetworkServiceAdapter) Disconnect(ctx context.Context, networkID, containerID string, force bool) error
- func (s *NetworkServiceAdapter) Inspect(ctx context.Context, networkID string) (*domain.Network, error)
- func (s *NetworkServiceAdapter) List(ctx context.Context, opts domain.NetworkListOptions) ([]domain.Network, error)
- func (s *NetworkServiceAdapter) Remove(ctx context.Context, networkID string) error
- type SwarmServiceAdapter
- func (s *SwarmServiceAdapter) Create(ctx context.Context, spec domain.ServiceSpec, opts domain.ServiceCreateOptions) (string, error)
- func (s *SwarmServiceAdapter) Inspect(ctx context.Context, serviceID string) (*domain.Service, error)
- func (s *SwarmServiceAdapter) List(ctx context.Context, opts domain.ServiceListOptions) ([]domain.Service, error)
- func (s *SwarmServiceAdapter) ListTasks(ctx context.Context, opts domain.TaskListOptions) ([]domain.Task, error)
- func (s *SwarmServiceAdapter) Remove(ctx context.Context, serviceID string) error
- func (s *SwarmServiceAdapter) WaitForServiceTasks(ctx context.Context, serviceID string, timeout time.Duration) ([]domain.Task, error)
- func (s *SwarmServiceAdapter) WaitForTask(ctx context.Context, taskID string, timeout time.Duration) (*domain.Task, error)
- type SystemServiceAdapter
- func (s *SystemServiceAdapter) DiskUsage(ctx context.Context) (*domain.DiskUsage, error)
- func (s *SystemServiceAdapter) Info(ctx context.Context) (*domain.SystemInfo, error)
- func (s *SystemServiceAdapter) Ping(ctx context.Context) (*domain.PingResponse, error)
- func (s *SystemServiceAdapter) Version(ctx context.Context) (*domain.Version, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNilExecConfig is returned when an ExecConfig pointer is nil. ErrNilExecConfig = errors.New("exec: nil ExecConfig") // ErrNoExecOutputWriter is returned when Run is invoked in non-TTY mode // with both stdout and stderr nil. stdcopy.StdCopy panics in that case // the moment it has output to dispatch. ErrNoExecOutputWriter = errors.New("exec: non-TTY mode requires at least one of stdout or stderr") )
Sentinel errors for input validation. Defined as static values so callers can use errors.Is for branching and to satisfy err113 lint guidance.
var ErrHTTPSRequiresUsableCertMaterial = errors.New("https:// has TLS material configured but it is unreadable or invalid")
ErrHTTPSRequiresUsableCertMaterial is returned by NewClientWithConfig when DOCKER_HOST uses the explicit-TLS scheme `https://` AND TLS material is configured (DOCKER_CERT_PATH or ClientConfig.TLSCertPath) but resolveTLSConfig fails to load it (typo in path, unreadable cert.pem, malformed ca.pem, secrets not yet populated, broken volume mount).
Without this gate, applyDockerTLS would emit slog.Warn and leave TLSClientConfig nil; the SDK would then dial with Go's default TLS — the system CA pool, NO client certificate — silently downgrading what the operator declared as mTLS into an unauthenticated TLS handshake.
Asymmetry vs ErrTCPTLSRequiresCertMaterial: tcp+tls:// REQUIRES material even when nothing is set (the scheme is an explicit mTLS opt-in). https:// is fail-open when no material is configured (operator legitimately relies on the system CA bundle); we only fail closed when material IS configured but unloadable. This is the silent-downgrade vector closed by #653.
var ErrMissingDockerHostScheme = errors.New("missing DOCKER_HOST scheme")
ErrMissingDockerHostScheme is returned when DOCKER_HOST is non-empty but has no "://" separator (e.g. "127.0.0.1:2375"). Distinct from ErrUnsupportedDockerHostScheme so operators can tell "I forgot the scheme" from "I used a scheme that isn't supported."
var ErrNilContainerConfig = errors.New("container: nil ContainerConfig")
ErrNilContainerConfig is returned by ContainerServiceAdapter.Create when the supplied *domain.ContainerConfig is nil. Production callers always pass a non-nil config (the executor builds it eagerly), so this is defense-in-depth — but the previous code dereferenced `config.HostConfig` / `config.NetworkConfig` unconditionally and would panic on a hand-rolled nil. Returning a typed sentinel keeps the failure branchable via errors.Is and consistent with ErrNilExecConfig.
var ErrNilDockerClient = errors.New("docker adapter: nil SDK client")
ErrNilDockerClient is returned by any *ServiceAdapter method when the embedded Docker SDK client is nil. The supported wiring (`NewClient` / `NewClientWithConfig`, then accessing the per-service adapters via the `*Client` accessor methods) always returns adapters with a non-nil embedded client, so this is reachable only through hand-rolled adapter values (`&ContainerServiceAdapter{}` and friends) — typically a test fixture or a wiring bug. Returning a typed error converts what would otherwise be a `nil pointer dereference` panic in a hot goroutine into an actionable, branchable failure that callers can route via `errors.Is`.
var ErrTCPTLSRequiresCertMaterial = errors.New("tcp+tls:// requires TLS material")
ErrTCPTLSRequiresCertMaterial is returned by NewClientWithConfig when DOCKER_HOST uses the explicit-TLS scheme `tcp+tls://` but no TLS material is configured (no DOCKER_CERT_PATH / DOCKER_TLS_VERIFY env vars and no ClientConfig.TLSCertPath / TLSVerify overrides).
Without this gate the SDK would dial TLS using Go's stdlib defaults — system CA bundle, NO client certificate — silently downgrading what the operator declared as mTLS into an unauthenticated TLS handshake. This is the analog, for tcp+tls://, of the silent plain-TCP downgrade closed by #612 / #625; tracked in #627.
`tcp://` and `https://` remain fail-open (tcp:// is ambiguous; https:// follows the upstream SDK's documented fail-open-with-warning posture).
var ErrUnsupportedDockerHostScheme = errors.New("unsupported DOCKER_HOST scheme")
ErrUnsupportedDockerHostScheme is returned when a DOCKER_HOST value uses a URL scheme that this adapter does not support. The error message lists the supported schemes so operators get an actionable failure at startup instead of an opaque dial error later.
Supported schemes (case-insensitive): unix, tcp, tcp+tls, http, https, npipe. Notably unsupported: ssh, fd. See docs/TROUBLESHOOTING.md.
Functions ¶
func EncodeAuthConfig ¶
func EncodeAuthConfig(auth domain.AuthConfig) (string, error)
EncodeAuthConfig encodes an auth config for use in API calls.
func ExtractRegistry ¶ added in v0.16.0
ExtractRegistry extracts the registry hostname from an image reference. Uses the canonical docker/distribution/reference parser for robustness.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements ports.DockerClient using the official Docker SDK.
func NewClientWithConfig ¶
func NewClientWithConfig(config *ClientConfig) (*Client, error)
NewClientWithConfig creates a new Docker client with custom configuration.
The effective Docker host is resolved in this order:
- config.Host (if non-empty)
- DOCKER_HOST environment variable
- client.DefaultDockerHost
The host's URL scheme is validated against the allow-list (see schemeHandlers) and normalized to lowercase. Unsupported schemes (ssh://, fd://, etc.) return ErrUnsupportedDockerHostScheme.
The DOCKER_HOST environment variable is consulted at most once per call. This is the contract from issue #617: a single resolveDockerHost seam avoids the SDK-vs-transport disagreement that caused #605 / #606 / #607 / #609 when two readers raced on env.
func (*Client) Containers ¶
func (c *Client) Containers() ports.ContainerService
Containers returns the container service.
func (*Client) Events ¶
func (c *Client) Events() ports.EventService
Events returns the event service.
func (*Client) Images ¶
func (c *Client) Images() ports.ImageService
Images returns the image service.
func (*Client) Networks ¶
func (c *Client) Networks() ports.NetworkService
Networks returns the network service.
func (*Client) SDK ¶
SDK returns the underlying Docker SDK client. This should only be used for operations not covered by the ports interface.
func (*Client) Services ¶
func (c *Client) Services() ports.SwarmService
Services returns the Swarm service.
func (*Client) System ¶
func (c *Client) System() ports.SystemService
System returns the system service.
type ClientConfig ¶
type ClientConfig struct {
// Host is the Docker host address (e.g., "unix:///var/run/docker.sock")
Host string
// Version is the API version (empty for auto-negotiation)
Version string
// HTTPHeaders are custom HTTP headers (optional)
HTTPHeaders map[string]string
// Connection pool settings
MaxIdleConns int
MaxIdleConnsPerHost int
MaxConnsPerHost int
IdleConnTimeout time.Duration
// Timeout settings
DialTimeout time.Duration
ResponseHeaderTimeout time.Duration
// NegotiateTimeout bounds the initial Docker API version negotiation that
// runs once at client creation. Without a bound, NegotiateAPIVersion uses
// context.Background() and can block forever when the Docker daemon is
// reachable but unresponsive (e.g. a socket proxy whose upstream is wedged),
// hanging Ofelia at startup with no diagnostic output.
//
// The Docker SDK swallows ping errors silently, so this timeout does not
// change correctness on successful paths - it only bounds the failure case.
//
// Set to 0 to inherit the default (see DefaultConfig). Use a small value
// to fail fast in tests; production typically wants 10-30s.
NegotiateTimeout time.Duration
// TLSCertPath is the directory containing TLS material (ca.pem, cert.pem,
// key.pem) for HTTPS Docker hosts. When empty, the DOCKER_CERT_PATH
// environment variable is consulted instead. If both are empty, no TLS
// configuration is applied (mirroring docker/docker's
// WithTLSClientConfigFromEnv).
TLSCertPath string
// TLSVerify controls whether the server certificate is verified for HTTPS
// Docker hosts. When nil, the DOCKER_TLS_VERIFY environment variable is
// consulted: any non-empty value enables verification (mirroring
// docker/docker's WithTLSClientConfigFromEnv).
TLSVerify *bool
}
ClientConfig contains configuration for the Docker client.
func DefaultConfig ¶
func DefaultConfig() *ClientConfig
DefaultConfig returns a default configuration.
type ConfigAuthProvider ¶ added in v0.16.0
type ConfigAuthProvider struct {
// contains filtered or unexported fields
}
ConfigAuthProvider implements ports.AuthProvider using Docker's config.json. It reads credentials fresh on each call to support dynamic credential updates (e.g., short-lived tokens from AWS ECR, GCR).
func NewConfigAuthProvider ¶ added in v0.16.0
func NewConfigAuthProvider() *ConfigAuthProvider
NewConfigAuthProvider creates a new auth provider.
func NewConfigAuthProviderWithOptions ¶ added in v0.16.0
func NewConfigAuthProviderWithOptions(configDir string, logger *slog.Logger) *ConfigAuthProvider
NewConfigAuthProviderWithOptions creates an auth provider with options.
func (*ConfigAuthProvider) GetAuthConfig ¶ added in v0.16.0
func (p *ConfigAuthProvider) GetAuthConfig(registry string) (domain.AuthConfig, error)
GetAuthConfig returns auth configuration for a registry.
func (*ConfigAuthProvider) GetEncodedAuth ¶ added in v0.16.0
func (p *ConfigAuthProvider) GetEncodedAuth(registry string) (string, error)
GetEncodedAuth returns base64-encoded auth for a registry.
type ContainerServiceAdapter ¶
type ContainerServiceAdapter struct {
// contains filtered or unexported fields
}
ContainerServiceAdapter implements ports.ContainerService using Docker SDK.
func (*ContainerServiceAdapter) Attach ¶
func (s *ContainerServiceAdapter) Attach( ctx context.Context, containerID string, opts ports.AttachOptions, ) (*domain.HijackedResponse, error)
Attach attaches to a container.
func (*ContainerServiceAdapter) CopyLogs ¶
func (s *ContainerServiceAdapter) CopyLogs( ctx context.Context, containerID string, stdout, stderr io.Writer, opts domain.LogOptions, ) error
CopyLogs copies container logs to writers.
func (*ContainerServiceAdapter) Create ¶
func (s *ContainerServiceAdapter) Create(ctx context.Context, config *domain.ContainerConfig) (string, error)
Create creates a new container.
Returns ErrNilContainerConfig (no panic) if config is nil — the previous code dereferenced config.HostConfig / config.NetworkConfig unconditionally. See #632 / #626.
func (*ContainerServiceAdapter) Inspect ¶
func (s *ContainerServiceAdapter) Inspect(ctx context.Context, containerID string) (*domain.Container, error)
Inspect returns container information.
func (*ContainerServiceAdapter) Kill ¶
func (s *ContainerServiceAdapter) Kill(ctx context.Context, containerID string, signal string) error
Kill sends a signal to a container.
func (*ContainerServiceAdapter) List ¶
func (s *ContainerServiceAdapter) List(ctx context.Context, opts domain.ListOptions) ([]domain.Container, error)
List lists containers.
func (*ContainerServiceAdapter) Logs ¶
func (s *ContainerServiceAdapter) Logs(ctx context.Context, containerID string, opts domain.LogOptions) (io.ReadCloser, error)
Logs returns container logs.
func (*ContainerServiceAdapter) Pause ¶
func (s *ContainerServiceAdapter) Pause(ctx context.Context, containerID string) error
Pause pauses a container.
func (*ContainerServiceAdapter) Remove ¶
func (s *ContainerServiceAdapter) Remove(ctx context.Context, containerID string, opts domain.RemoveOptions) error
Remove removes a container.
func (*ContainerServiceAdapter) Rename ¶
func (s *ContainerServiceAdapter) Rename(ctx context.Context, containerID string, newName string) error
Rename renames a container.
func (*ContainerServiceAdapter) Start ¶
func (s *ContainerServiceAdapter) Start(ctx context.Context, containerID string) error
Start starts a container.
func (*ContainerServiceAdapter) Stop ¶
func (s *ContainerServiceAdapter) Stop(ctx context.Context, containerID string, opts domain.StopOptions) error
Stop stops a container.
func (*ContainerServiceAdapter) Unpause ¶
func (s *ContainerServiceAdapter) Unpause(ctx context.Context, containerID string) error
Unpause unpauses a container.
func (*ContainerServiceAdapter) Wait ¶
func (s *ContainerServiceAdapter) Wait(ctx context.Context, containerID string) (<-chan domain.WaitResponse, <-chan error)
Wait waits for a container to stop.
type EventServiceAdapter ¶
type EventServiceAdapter struct {
// contains filtered or unexported fields
}
EventServiceAdapter implements ports.EventService using Docker SDK. This implementation uses context-based cancellation for safe channel management.
func (*EventServiceAdapter) Subscribe ¶
func (s *EventServiceAdapter) Subscribe(ctx context.Context, filter domain.EventFilter) (<-chan domain.Event, <-chan error)
Subscribe subscribes to Docker events. The returned channels are closed when the context is canceled or an error occurs. The caller should NOT close these channels.
If the embedded SDK client is nil (defense-in-depth), both channels are closed synchronously after pushing ErrNilDockerClient on errCh — no goroutine is launched.
func (*EventServiceAdapter) SubscribeWithCallback ¶
func (s *EventServiceAdapter) SubscribeWithCallback( ctx context.Context, filter domain.EventFilter, callback ports.EventCallback, ) error
SubscribeWithCallback subscribes to events with a callback.
type ExecServiceAdapter ¶
type ExecServiceAdapter struct {
// contains filtered or unexported fields
}
ExecServiceAdapter implements ports.ExecService using Docker SDK.
func (*ExecServiceAdapter) Create ¶
func (s *ExecServiceAdapter) Create(ctx context.Context, containerID string, config *domain.ExecConfig) (string, error)
func (*ExecServiceAdapter) Inspect ¶
func (s *ExecServiceAdapter) Inspect(ctx context.Context, execID string) (*domain.ExecInspect, error)
Inspect returns exec information.
func (*ExecServiceAdapter) Run ¶
func (s *ExecServiceAdapter) Run( ctx context.Context, containerID string, config *domain.ExecConfig, stdout, stderr io.Writer, ) (int, error)
Run executes a command in a container and waits for it to complete.
func (*ExecServiceAdapter) Start ¶
func (s *ExecServiceAdapter) Start(ctx context.Context, execID string, opts domain.ExecStartOptions) (*domain.HijackedResponse, error)
Start starts an exec instance.
type ImageServiceAdapter ¶
type ImageServiceAdapter struct {
// contains filtered or unexported fields
}
ImageServiceAdapter implements ports.ImageService using Docker SDK.
func (*ImageServiceAdapter) List ¶
func (s *ImageServiceAdapter) List(ctx context.Context, opts domain.ImageListOptions) ([]domain.ImageSummary, error)
List lists images.
func (*ImageServiceAdapter) Pull ¶
func (s *ImageServiceAdapter) Pull(ctx context.Context, opts domain.PullOptions) (io.ReadCloser, error)
Pull pulls an image from a registry.
func (*ImageServiceAdapter) PullAndWait ¶
func (s *ImageServiceAdapter) PullAndWait(ctx context.Context, opts domain.PullOptions) error
PullAndWait pulls an image and waits for completion.
type NetworkServiceAdapter ¶
type NetworkServiceAdapter struct {
// contains filtered or unexported fields
}
NetworkServiceAdapter implements ports.NetworkService using Docker SDK.
func (*NetworkServiceAdapter) Connect ¶
func (s *NetworkServiceAdapter) Connect(ctx context.Context, networkID, containerID string, config *domain.EndpointSettings) error
Connect connects a container to a network.
func (*NetworkServiceAdapter) Create ¶
func (s *NetworkServiceAdapter) Create(ctx context.Context, name string, opts ports.NetworkCreateOptions) (string, error)
Create creates a network.
func (*NetworkServiceAdapter) Disconnect ¶
func (s *NetworkServiceAdapter) Disconnect(ctx context.Context, networkID, containerID string, force bool) error
Disconnect disconnects a container from a network.
func (*NetworkServiceAdapter) Inspect ¶
func (s *NetworkServiceAdapter) Inspect(ctx context.Context, networkID string) (*domain.Network, error)
Inspect returns network information.
func (*NetworkServiceAdapter) List ¶
func (s *NetworkServiceAdapter) List(ctx context.Context, opts domain.NetworkListOptions) ([]domain.Network, error)
List lists networks.
type SwarmServiceAdapter ¶
type SwarmServiceAdapter struct {
// contains filtered or unexported fields
}
SwarmServiceAdapter implements ports.SwarmService using Docker SDK.
func (*SwarmServiceAdapter) Create ¶
func (s *SwarmServiceAdapter) Create(ctx context.Context, spec domain.ServiceSpec, opts domain.ServiceCreateOptions) (string, error)
Create creates a new Swarm service.
func (*SwarmServiceAdapter) Inspect ¶
func (s *SwarmServiceAdapter) Inspect(ctx context.Context, serviceID string) (*domain.Service, error)
Inspect returns service information.
func (*SwarmServiceAdapter) List ¶
func (s *SwarmServiceAdapter) List(ctx context.Context, opts domain.ServiceListOptions) ([]domain.Service, error)
List lists services.
func (*SwarmServiceAdapter) ListTasks ¶
func (s *SwarmServiceAdapter) ListTasks(ctx context.Context, opts domain.TaskListOptions) ([]domain.Task, error)
ListTasks lists tasks.
func (*SwarmServiceAdapter) Remove ¶
func (s *SwarmServiceAdapter) Remove(ctx context.Context, serviceID string) error
Remove removes a service.
type SystemServiceAdapter ¶
type SystemServiceAdapter struct {
// contains filtered or unexported fields
}
SystemServiceAdapter implements ports.SystemService using Docker SDK.
func (*SystemServiceAdapter) Info ¶
func (s *SystemServiceAdapter) Info(ctx context.Context) (*domain.SystemInfo, error)
Info returns system information.
func (*SystemServiceAdapter) Ping ¶
func (s *SystemServiceAdapter) Ping(ctx context.Context) (*domain.PingResponse, error)
Ping pings the Docker server.