docker

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2026 License: GPL-3.0, LGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package docker provides a thin abstraction over the Docker CLI.

Package docker provides a thin abstraction over the Docker CLI.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	Executor Executor
	Command  string // docker executable path (default: "docker")
}

Client provides operations against the Docker CLI.

func NewClient 

func NewClient(executor Executor) *Client

NewClient returns a Client that runs docker commands through the given executor.

func (*Client) AppendFile 

func (c *Client) AppendFile(ctx context.Context, container ContainerName, path, content string) error

AppendFile appends content to a file in a running container via docker exec.

func (*Client) ConnectNetwork 

func (c *Client) ConnectNetwork(ctx context.Context, network NetworkName, container ContainerName) error

ConnectNetwork connects a container to a network.

func (*Client) ContainerExists 

func (c *Client) ContainerExists(ctx context.Context, name ContainerName) (bool, error)

ContainerExists returns true if the given container exists (running or stopped).

func (*Client) CopyFilesToContainer 

func (c *Client) CopyFilesToContainer(ctx context.Context, container ContainerName, destDir string, files map[string]File) error

CopyFilesToContainer writes files into a container directory via docker cp. Each file carries its own content and permissions. The container may be running or stopped. Keys are sorted for deterministic tar output.

func (*Client) CopyFromContainer 

func (c *Client) CopyFromContainer(ctx context.Context, container ContainerName, srcPath string) ([]byte, error)

CopyFromContainer reads a single file from a container via docker cp. The container may be running or stopped.

func (*Client) CopyToContainer 

func (c *Client) CopyToContainer(ctx context.Context, container ContainerName, destDir string, files map[string][]byte) error

CopyToContainer writes files into a container directory via docker cp. All files are written with mode 0644. Use CopyFilesToContainer for explicit per-file permissions.

func (*Client) CreateContainer 

func (c *Client) CreateContainer(ctx context.Context, args ...string) (ContainerID, error)

CreateContainer creates a container without starting it (docker create). Use StartContainer to start it afterwards. Returns the container ID.

func (*Client) CreateNetwork 

func (c *Client) CreateNetwork(ctx context.Context, name NetworkName, labels map[string]string) (NetworkID, error)

CreateNetwork creates a Docker network and returns its ID. Labels are applied as --label flags when non-nil.

func (*Client) CreateVolume 

func (c *Client) CreateVolume(ctx context.Context, name VolumeName, labels map[string]string) error

CreateVolume creates a Docker volume. Labels are applied as --label flags when non-nil.

func (*Client) DisconnectNetwork 

func (c *Client) DisconnectNetwork(ctx context.Context, network NetworkName, container ContainerName) error

DisconnectNetwork disconnects a container from a network.

func (*Client) Exec 

func (c *Client) Exec(ctx context.Context, container ContainerName, command ...string) (string, error)

Exec runs a command inside a container and returns its stdout.

func (*Client) ExecWithStdin 

func (c *Client) ExecWithStdin(ctx context.Context, container ContainerName, stdin io.Reader, command ...string) error

ExecWithStdin runs a command inside a container, piping stdin to it.

func (*Client) InspectContainer 

func (c *Client) InspectContainer(ctx context.Context, name ContainerName) (*ContainerInfo, error)

InspectContainer returns detailed information about a container.

func (*Client) InspectNetwork 

func (c *Client) InspectNetwork(ctx context.Context, name NetworkName) (*NetworkInfo, error)

InspectNetwork returns detailed information about a network.

func (*Client) KillContainer 

func (c *Client) KillContainer(ctx context.Context, name ContainerName) error

KillContainer sends SIGKILL to a running container (docker kill).

func (*Client) ListContainers 

func (c *Client) ListContainers(ctx context.Context, filters ...string) ([]ContainerListEntry, error)

ListContainers returns containers matching the given filters. Each filter is passed as a --filter flag to docker ps (e.g. "label=sind.cluster").

func (*Client) ListNetworks 

func (c *Client) ListNetworks(ctx context.Context, filters ...string) ([]NetworkListEntry, error)

ListNetworks returns networks matching the given filters. Each filter is passed as a --filter flag (e.g. "name=sind").

func (*Client) ListVolumes 

func (c *Client) ListVolumes(ctx context.Context, filters ...string) ([]VolumeListEntry, error)

ListVolumes returns volumes matching the given filters. Each filter is passed as a --filter flag (e.g. "name=sind-dev").

func (*Client) NetworkExists 

func (c *Client) NetworkExists(ctx context.Context, name NetworkName) (bool, error)

NetworkExists returns true if the given network exists.

func (*Client) PauseContainer 

func (c *Client) PauseContainer(ctx context.Context, name ContainerName) error

PauseContainer suspends all processes in a container (docker pause).

func (*Client) ReadFile 

func (c *Client) ReadFile(ctx context.Context, container ContainerName, path string) (string, error)

ReadFile reads a file from a running container via docker exec.

func (*Client) RemoveContainer 

func (c *Client) RemoveContainer(ctx context.Context, name ContainerName) error

RemoveContainer removes a container.

func (*Client) RemoveNetwork 

func (c *Client) RemoveNetwork(ctx context.Context, name NetworkName) error

RemoveNetwork removes a Docker network.

func (*Client) RemoveVolume 

func (c *Client) RemoveVolume(ctx context.Context, name VolumeName) error

RemoveVolume removes a Docker volume.

func (*Client) RunContainer 

func (c *Client) RunContainer(ctx context.Context, args ...string) (ContainerID, error)

RunContainer creates and starts a container in detached mode (docker run -d). The args are passed directly and should include the image name as the last element. Returns the container ID.

func (*Client) RunEphemeral 

func (c *Client) RunEphemeral(ctx context.Context, image string, pull bool, command ...string) (string, error)

RunEphemeral runs a command in a temporary container and returns its stdout. The container is removed after the command completes (docker run --rm). When pull is true, --pull always is added to force a fresh image pull.

func (*Client) ServerVersion added in v0.2.0 

func (c *Client) ServerVersion(ctx context.Context) (string, error)

ServerVersion returns the Docker Engine server version string.

func (*Client) SignalContainer 

func (c *Client) SignalContainer(ctx context.Context, name ContainerName, signal string) error

SignalContainer sends a signal to a running container (docker kill -s).

func (*Client) StartContainer 

func (c *Client) StartContainer(ctx context.Context, name ContainerName) error

StartContainer starts a stopped container.

func (*Client) StopContainer 

func (c *Client) StopContainer(ctx context.Context, name ContainerName) error

StopContainer gracefully stops a running container.

func (*Client) UnpauseContainer 

func (c *Client) UnpauseContainer(ctx context.Context, name ContainerName) error

UnpauseContainer resumes a paused container (docker unpause).

func (*Client) VolumeExists 

func (c *Client) VolumeExists(ctx context.Context, name VolumeName) (bool, error)

VolumeExists returns true if the given volume exists.

func (*Client) WriteFile 

func (c *Client) WriteFile(ctx context.Context, container ContainerName, path, content string) error

WriteFile overwrites a file in a running container via docker exec.

type ContainerID 

type ContainerID string

ContainerID is a Docker container identifier (64 hex characters).

type ContainerInfo 

type ContainerInfo struct {
	ID     ContainerID
	Name   ContainerName
	Status string
	Labels map[string]string
	IPs    map[NetworkName]string
}

ContainerInfo holds inspected container details.

type ContainerListEntry 

type ContainerListEntry struct {
	ID     ContainerID
	Name   ContainerName
	State  string
	Image  string
	Labels map[string]string
}

ContainerListEntry holds summary information from docker ps.

type ContainerName 

type ContainerName string

ContainerName is a human-readable Docker container name.

type Executor 

type Executor interface {
	// Run executes the named command with the given arguments and returns
	// the captured stdout and stderr. If the command exits with a non-zero
	// status, the returned error wraps an *exec.ExitError.
	Run(ctx context.Context, name string, args ...string) (stdout string, stderr string, err error)

	// RunWithStdin is like Run but pipes the given reader to the command's stdin.
	RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (stdout string, stderr string, err error)
}

Executor runs external commands and captures their output.

type File 

type File struct {
	Content []byte
	Mode    int64 // e.g. 0644, 0600
}

File represents a file to copy into a container with explicit permissions.

type MockCall 

type MockCall struct {
	Name  string
	Args  []string
	Stdin string // captured stdin content (empty if no stdin)
}

MockCall records a single invocation of MockExecutor.

type MockExecutor 

type MockExecutor struct {
	// OnCall, if set, is called to produce a result for each invocation.
	// The args slice contains the docker subcommand and its arguments
	// (e.g. ["inspect", "sind-dns"]). Stdin is non-empty for RunWithStdin calls.
	OnCall func(args []string, stdin string) MockResult

	Calls []MockCall
	// contains filtered or unexported fields
}

MockExecutor records all calls and returns preconfigured results. It is safe for concurrent use.

Results are dispatched in two modes:

  • If OnCall is set, it is called for every invocation to produce a result.
  • Otherwise, results queued via AddResult are returned in FIFO order.

OnCall is useful when multiple goroutines share a MockExecutor and result dispatch must be based on command arguments rather than call order.

func (*MockExecutor) AddResult 

func (m *MockExecutor) AddResult(stdout, stderr string, err error)

AddResult enqueues a result to be returned by the next Run or RunWithStdin call. Only used when OnCall is nil.

func (*MockExecutor) Run 

func (m *MockExecutor) Run(_ context.Context, name string, args ...string) (string, string, error)

Run implements Executor.

func (*MockExecutor) RunWithStdin 

func (m *MockExecutor) RunWithStdin(_ context.Context, stdin io.Reader, name string, args ...string) (string, string, error)

RunWithStdin implements Executor.

type MockResult 

type MockResult struct {
	Stdout string
	Stderr string
	Err    error
}

MockResult holds the return values for a single MockExecutor call.

type NetworkID 

type NetworkID string

NetworkID is a Docker network identifier.

type NetworkInfo 

type NetworkInfo struct {
	Name    NetworkName
	Driver  string
	Subnet  string
	Gateway string
}

NetworkInfo holds detailed information about a Docker network.

type NetworkListEntry 

type NetworkListEntry struct {
	Name   NetworkName
	Driver string
}

NetworkListEntry holds summary information from docker network ls.

type NetworkName 

type NetworkName string

NetworkName is a human-readable Docker network name.

type OSExecutor 

type OSExecutor struct{}

OSExecutor runs commands using os/exec.

func (*OSExecutor) Run 

func (e *OSExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)

Run implements Executor.

func (*OSExecutor) RunWithStdin 

func (e *OSExecutor) RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (string, string, error)

RunWithStdin implements Executor.

type RecordedCall 

type RecordedCall struct {
	Name   string
	Args   []string
	Stdout string
	Stderr string
	Err    error
}

RecordedCall captures one invocation of the executor.

type Recorder 

type Recorder struct {
	*RecordingExecutor
	// contains filtered or unexported fields
}

Recorder holds a RecordingExecutor and the underlying mock (if any). In unit mode, mock is non-nil and AddResult configures responses. In integration mode, mock is nil and AddResult is a no-op.

func NewIntegrationRecorder 

func NewIntegrationRecorder() *Recorder

NewIntegrationRecorder returns a Recorder backed by an OSExecutor.

func NewMockRecorder 

func NewMockRecorder() *Recorder

NewMockRecorder returns a Recorder backed by a MockExecutor.

func (*Recorder) AddResult 

func (r *Recorder) AddResult(stdout, stderr string, err error)

AddResult queues a mock response. No-op in integration mode.

func (*Recorder) IsIntegration 

func (r *Recorder) IsIntegration() bool

IsIntegration returns true when running against real Docker.

type RecordingExecutor 

type RecordingExecutor struct {
	Inner Executor
	// contains filtered or unexported fields
}

RecordingExecutor wraps another Executor and records all calls with their results. Useful for observing actual Docker CLI I/O during tests.

func (*RecordingExecutor) Calls 

func (r *RecordingExecutor) Calls() []RecordedCall

Calls returns a copy of all recorded calls.

func (*RecordingExecutor) Dump 

func (r *RecordingExecutor) Dump() string

Dump returns a human-readable log of all recorded calls.

func (*RecordingExecutor) Run 

func (r *RecordingExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)

Run implements Executor.

func (*RecordingExecutor) RunWithStdin 

func (r *RecordingExecutor) RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (string, string, error)

RunWithStdin implements Executor.

type VolumeListEntry 

type VolumeListEntry struct {
	Name   VolumeName
	Driver string
}

VolumeListEntry holds summary information from docker volume ls.

type VolumeName 

type VolumeName string

VolumeName is a human-readable Docker volume name.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.