Documentation
¶
Overview ¶
Package ports defines the port interfaces for Docker operations. These interfaces abstract the Docker client implementation, enabling easy testing with mocks and future SDK migrations.
Index ¶
- type AttachOptions
- type AuthProvider
- type ClientFactory
- type ClientOption
- type ClientOptions
- type ContainerService
- type DockerClient
- type EventCallback
- type EventService
- type ExecService
- type ImageService
- type NetworkCreateOptions
- type NetworkService
- type SwarmService
- type SystemService
- type TLSConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AttachOptions ¶
type AttachOptions struct {
Stream bool
Stdin bool
Stdout bool
Stderr bool
DetachKeys string
Logs bool
}
AttachOptions represents options for attaching to a container.
type AuthProvider ¶
type AuthProvider interface {
// GetAuthConfig returns the authentication configuration for a registry.
GetAuthConfig(registry string) (domain.AuthConfig, error)
// GetEncodedAuth returns base64-encoded authentication for a registry.
GetEncodedAuth(registry string) (string, error)
}
AuthProvider provides authentication for registry operations.
type ClientFactory ¶
type ClientFactory interface {
// NewClient creates a new DockerClient from environment variables.
NewClient() (DockerClient, error)
// NewClientWithOptions creates a new DockerClient with custom options.
NewClientWithOptions(opts ...ClientOption) (DockerClient, error)
}
ClientFactory creates DockerClient instances.
type ClientOption ¶
type ClientOption func(*ClientOptions)
ClientOption is a function that configures a DockerClient.
func WithHTTPHeaders ¶
func WithHTTPHeaders(headers map[string]string) ClientOption
WithHTTPHeaders sets custom HTTP headers.
func WithTLSConfig ¶
func WithTLSConfig(config *TLSConfig) ClientOption
WithTLSConfig sets TLS configuration.
type ClientOptions ¶
type ClientOptions struct {
// Host is the Docker host address.
Host string
// Version is the API version to use.
Version string
// TLSConfig contains TLS configuration.
TLSConfig *TLSConfig
// HTTPHeaders are custom HTTP headers to send.
HTTPHeaders map[string]string
}
ClientOptions contains options for creating a DockerClient.
type ContainerService ¶
type ContainerService interface {
// Create creates a new container.
// Returns the container ID on success.
Create(ctx context.Context, config *domain.ContainerConfig) (string, error)
// Start starts a stopped container.
Start(ctx context.Context, containerID string) error
// Stop stops a running container.
// The timeout parameter specifies how long to wait before forcefully killing.
// If timeout is nil, the default timeout is used.
Stop(ctx context.Context, containerID string, timeout *time.Duration) error
// Remove removes a container.
Remove(ctx context.Context, containerID string, opts domain.RemoveOptions) error
// Inspect returns detailed information about a container.
Inspect(ctx context.Context, containerID string) (*domain.Container, error)
// List returns a list of containers matching the options.
List(ctx context.Context, opts domain.ListOptions) ([]domain.Container, error)
// Wait blocks until a container stops and returns its exit status.
// Returns two channels: one for the wait response, one for errors.
// The context can be used to cancel the wait operation.
Wait(ctx context.Context, containerID string) (<-chan domain.WaitResponse, <-chan error)
// Logs returns the logs from a container.
// The returned ReadCloser must be closed by the caller.
Logs(ctx context.Context, containerID string, opts domain.LogOptions) (io.ReadCloser, error)
// CopyLogs copies container logs to the provided writers.
// This is a convenience method that handles stdout/stderr demultiplexing.
CopyLogs(ctx context.Context, containerID string, stdout, stderr io.Writer, opts domain.LogOptions) error
// Kill sends a signal to a container.
Kill(ctx context.Context, containerID string, signal string) error
// Pause pauses a container.
Pause(ctx context.Context, containerID string) error
// Unpause unpauses a paused container.
Unpause(ctx context.Context, containerID string) error
// Rename renames a container.
Rename(ctx context.Context, containerID string, newName string) error
// Attach attaches to a container.
Attach(ctx context.Context, containerID string, opts AttachOptions) (*domain.HijackedResponse, error)
}
ContainerService provides operations for managing Docker containers.
type DockerClient ¶
type DockerClient interface {
// Containers returns the container service interface.
Containers() ContainerService
// Exec returns the exec service interface.
Exec() ExecService
// Images returns the image service interface.
Images() ImageService
// Events returns the event service interface.
Events() EventService
// Services returns the Swarm service interface.
Services() SwarmService
// Networks returns the network service interface.
Networks() NetworkService
// System returns the system service interface.
System() SystemService
// Close closes the client and releases resources.
Close() error
}
DockerClient is the main interface for Docker operations. It provides access to specialized service interfaces for different Docker resource types.
type EventCallback ¶
EventCallback is called for each Docker event received. Return an error to stop the subscription.
type EventService ¶
type EventService interface {
// Subscribe returns channels that receive Docker events.
// The events channel receives events matching the filter.
// The errors channel receives any errors during subscription.
//
// Both channels are closed when the context is canceled or an error occurs.
// The caller should NOT close these channels; they are managed by the implementation.
//
// Example usage:
// ctx, cancel := context.WithCancel(context.Background())
// defer cancel() // This cleanly stops event streaming
//
// events, errs := client.Events().Subscribe(ctx, filter)
// for {
// select {
// case event := <-events:
// // Handle event
// case err := <-errs:
// // Handle error
// return
// }
// }
Subscribe(ctx context.Context, filter domain.EventFilter) (<-chan domain.Event, <-chan error)
// SubscribeWithCallback provides callback-based event subscription.
// The callback is invoked for each event received.
// This method blocks until the context is canceled or an error occurs.
// Returns nil if canceled cleanly, or an error if subscription fails.
SubscribeWithCallback(ctx context.Context, filter domain.EventFilter, callback EventCallback) error
}
EventService provides operations for subscribing to Docker events. This interface uses context-based cancellation for safe channel management.
type ExecService ¶
type ExecService interface {
// Create creates an exec instance in a container.
// Returns the exec ID on success.
Create(ctx context.Context, containerID string, config *domain.ExecConfig) (string, error)
// Start starts an exec instance.
// For attached exec, this returns a hijacked connection.
Start(ctx context.Context, execID string, opts domain.ExecStartOptions) (*domain.HijackedResponse, error)
// Inspect returns information about an exec instance.
Inspect(ctx context.Context, execID string) (*domain.ExecInspect, error)
// Run is a convenience method that creates, starts, and waits for an exec.
// It copies stdout and stderr to the provided writers.
// Returns the exit code of the command.
Run(ctx context.Context, containerID string, config *domain.ExecConfig, stdout, stderr io.Writer) (int, error)
}
ExecService provides operations for executing commands in containers.
type ImageService ¶
type ImageService interface {
// Pull pulls an image from a registry.
// The returned ReadCloser contains pull progress and must be closed by the caller.
// The progress can be decoded as JSON-encoded PullProgress messages.
Pull(ctx context.Context, opts domain.PullOptions) (io.ReadCloser, error)
// PullAndWait pulls an image and waits for completion.
// This is a convenience method that handles the progress stream.
PullAndWait(ctx context.Context, opts domain.PullOptions) error
// List returns a list of images matching the options.
List(ctx context.Context, opts domain.ImageListOptions) ([]domain.ImageSummary, error)
// Inspect returns detailed information about an image.
Inspect(ctx context.Context, imageID string) (*domain.Image, error)
// Remove removes an image.
Remove(ctx context.Context, imageID string, force, pruneChildren bool) error
// Tag tags an image.
Tag(ctx context.Context, source, target string) error
// Exists checks if an image exists locally.
Exists(ctx context.Context, imageRef string) (bool, error)
}
ImageService provides operations for managing Docker images.
type NetworkCreateOptions ¶
type NetworkCreateOptions struct {
Driver string
Scope string
EnableIPv6 bool
IPAM *domain.IPAM
Internal bool
Attachable bool
Ingress bool
Options map[string]string
Labels map[string]string
}
NetworkCreateOptions represents options for creating a network.
type NetworkService ¶
type NetworkService interface {
// Connect connects a container to a network.
Connect(ctx context.Context, networkID, containerID string, config *domain.EndpointSettings) error
// Disconnect disconnects a container from a network.
Disconnect(ctx context.Context, networkID, containerID string, force bool) error
// List returns a list of networks matching the options.
List(ctx context.Context, opts domain.NetworkListOptions) ([]domain.Network, error)
// Inspect returns detailed information about a network.
Inspect(ctx context.Context, networkID string) (*domain.Network, error)
// Create creates a new network.
Create(ctx context.Context, name string, opts NetworkCreateOptions) (string, error)
// Remove removes a network.
Remove(ctx context.Context, networkID string) error
}
NetworkService provides operations for managing Docker networks.
type SwarmService ¶
type SwarmService interface {
// Create creates a new Swarm service.
// Returns the service ID on success.
Create(ctx context.Context, spec domain.ServiceSpec, opts domain.ServiceCreateOptions) (string, error)
// Inspect returns detailed information about a service.
Inspect(ctx context.Context, serviceID string) (*domain.Service, error)
// List returns a list of services matching the options.
List(ctx context.Context, opts domain.ServiceListOptions) ([]domain.Service, error)
// Remove removes a service.
Remove(ctx context.Context, serviceID string) error
// ListTasks returns a list of tasks for services matching the options.
ListTasks(ctx context.Context, opts domain.TaskListOptions) ([]domain.Task, error)
// WaitForTask waits for a task to reach a terminal state.
// Returns the final task state or an error if the timeout is reached.
WaitForTask(ctx context.Context, taskID string, timeout time.Duration) (*domain.Task, error)
// WaitForServiceTasks waits for all tasks of a service to reach a terminal state.
// This is useful for one-shot service jobs.
WaitForServiceTasks(ctx context.Context, serviceID string, timeout time.Duration) ([]domain.Task, error)
}
SwarmService provides operations for managing Docker Swarm services.
type SystemService ¶
type SystemService interface {
// Info returns system-wide information.
Info(ctx context.Context) (*domain.SystemInfo, error)
// Ping pings the Docker server.
Ping(ctx context.Context) (*domain.PingResponse, error)
// Version returns version information.
Version(ctx context.Context) (*domain.Version, error)
// DiskUsage returns disk usage information.
DiskUsage(ctx context.Context) (*domain.DiskUsage, error)
}
SystemService provides operations for Docker system information.