ports

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 3, 2026 License: MIT Imports: 4 Imported by: 0

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

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 WithHost

func WithHost(host string) ClientOption

WithHost sets the Docker host address.

func WithTLSConfig

func WithTLSConfig(config *TLSConfig) ClientOption

WithTLSConfig sets TLS configuration.

func WithVersion

func WithVersion(version string) ClientOption

WithVersion sets the API version.

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.
	// opts.Timeout specifies how long to wait before forcefully killing;
	// nil leaves the daemon's default in effect.
	// opts.Signal selects the termination signal (e.g. "SIGINT"); empty
	// uses the container image's STOPSIGNAL or the daemon default
	// (SIGTERM). See domain.StopOptions and #234.
	Stop(ctx context.Context, containerID string, opts domain.StopOptions) 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

type EventCallback func(event domain.Event) error

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.

type TLSConfig

type TLSConfig struct {
	CAFile   string
	CertFile string
	KeyFile  string
	Insecure bool
}

TLSConfig contains TLS configuration options.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL