dockercli

package
v0.8.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const ComposeCacheMaxSize = 100

ComposeCacheMaxSize is the maximum number of compose config entries to cache. This prevents unbounded memory growth in long-running processes.

View Source 
const HelperImage = "alpine:3.22"

HelperImage is the Docker image used for file operations on volumes

View Source 
const LabelIdentifier = LabelPrefix + "identifier"

LabelIdentifier is the full label key for the Dockform identifier

View Source 
const LabelPrefix = "io.dockform."

LabelPrefix is the prefix for all Dockform labels

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides higher-level helpers around docker CLI.

func New 

func New(contextName string) *Client

func NewWithHost 

func NewWithHost(contextName, host string) *Client

NewWithHost creates a Client that uses a direct Docker host URI instead of a named Docker context. When host is non-empty, DOCKER_HOST is set instead of DOCKER_CONTEXT for all CLI invocations.

func (*Client) CheckDaemon 

func (c *Client) CheckDaemon(ctx context.Context) error

CheckDaemon verifies the docker daemon for the configured context is reachable.

func (*Client) ClearVolume added in v0.3.0 

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

ClearVolume removes all contents of the volume's root directory.

func (*Client) ComposeConfigFull 

func (c *Client) ComposeConfigFull(ctx context.Context, workingDir string, files, profiles, envFiles []string, inlineEnv []string) (ComposeConfigDoc, error)

ComposeConfigFull renders the effective compose config and parses desired services info (image, etc.).

func (*Client) ComposeConfigHash 

func (c *Client) ComposeConfigHash(ctx context.Context, workingDir string, files, profiles, envFiles []string, projectName string, service string, identifier string, inlineEnv []string) (string, error)

ComposeConfigHash returns the compose config hash for a single service. If identifier is non-empty, a temporary overlay compose file is used to add the label `io.dockform.identifier: <identifier>` to that service before hashing.

func (*Client) ComposeConfigHashes added in v0.5.1 

func (c *Client) ComposeConfigHashes(ctx context.Context, workingDir string, files, profiles, envFiles []string, projectName string, services []string, identifier string, inlineEnv []string) (map[string]string, error)

ComposeConfigHashes returns compose config hashes for multiple services, reusing a single labeled overlay compose file when identifier is provided to avoid repeated `compose config`.

func (*Client) ComposeConfigRaw added in v0.3.0 

func (c *Client) ComposeConfigRaw(ctx context.Context, workingDir string, files, profiles, envFiles []string, inlineEnv []string) (string, error)

ComposeConfigRaw returns the fully resolved compose configuration as YAML text. It is equivalent to running `docker compose config` with the provided files, profiles and env files, resolved relative to workingDir. Inline environment variables are provided via the process environment for the command.

func (*Client) ComposeConfigServices 

func (c *Client) ComposeConfigServices(ctx context.Context, workingDir string, files, profiles, envFiles []string, inlineEnv []string) ([]string, error)

ComposeConfigServices returns the list of service names that would be part of the project.

func (*Client) ComposePs 

func (c *Client) ComposePs(ctx context.Context, workingDir string, files, profiles, envFiles []string, projectName string, inlineEnv []string) ([]ComposePsItem, error)

ComposePs lists running (or created) compose services for the project.

func (*Client) ComposeUp 

func (c *Client) ComposeUp(ctx context.Context, workingDir string, files, profiles, envFiles []string, projectName string, inlineEnv []string) (string, error)

ComposeUp runs docker compose up -d with the given parameters. workingDir is where compose files and relative paths are resolved.

func (*Client) ComposeVersion added in v0.5.0 

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

ComposeVersion returns the docker compose plugin version (short form) if available.

func (*Client) ContextHost added in v0.5.0 

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

ContextHost returns the Docker host endpoint for the configured context. When a host override is set (from the manifest), it is returned directly. Falls back to the default context when none is set.

func (*Client) CreateNetwork 

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

func (*Client) CreateVolume 

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

func (*Client) ExtractTarToVolume 

func (c *Client) ExtractTarToVolume(ctx context.Context, volumeName, targetPath string, r io.Reader) error

ExtractTarToVolume extracts a tar stream (stdin) into the volume targetPath without clearing existing files. It ensures targetPath exists.

func (*Client) ExtractZstdTarToVolume added in v0.3.0 

func (c *Client) ExtractZstdTarToVolume(ctx context.Context, volumeName string, r io.Reader) error

ExtractZstdTarToVolume reads a zstd-compressed tar from r and extracts into the volume root.

func (*Client) ImageExists added in v0.5.0 

func (c *Client) ImageExists(ctx context.Context, imageRef string) (bool, error)

ImageExists returns true if the given image is present locally in the configured context.

func (*Client) InspectContainerLabels 

func (c *Client) InspectContainerLabels(ctx context.Context, containerName string, keys []string) (map[string]string, error)

InspectContainerLabels returns selected labels from a container.

func (*Client) InspectMultipleContainerLabels 

func (c *Client) InspectMultipleContainerLabels(ctx context.Context, containerNames []string, keys []string) (map[string]map[string]string, error)

InspectMultipleContainerLabels returns selected labels from multiple containers in a single call

func (*Client) InspectNetwork added in v0.3.0 

func (c *Client) InspectNetwork(ctx context.Context, name string) (NetworkInspect, error)

InspectNetwork returns details about a docker network

func (*Client) InspectVolume added in v0.3.0 

func (c *Client) InspectVolume(ctx context.Context, name string) (VolumeDetails, error)

InspectVolume returns driver/options/labels for a volume.

func (*Client) IsVolumeEmpty added in v0.3.0 

func (c *Client) IsVolumeEmpty(ctx context.Context, volumeName string) (bool, error)

IsVolumeEmpty returns true if the volume has no files (ignores . and ..).

func (*Client) ListComposeContainersAll 

func (c *Client) ListComposeContainersAll(ctx context.Context) ([]PsBrief, error)

ListComposeContainersAll lists all containers with compose labels (project/service) across the Docker context.

func (*Client) ListContainersUsingVolume added in v0.3.0 

func (c *Client) ListContainersUsingVolume(ctx context.Context, volumeName string) ([]string, error)

ListContainersUsingVolume returns container names (running or stopped) that reference the volume.

func (*Client) ListNetworks 

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

ListNetworks returns names of docker networks.

func (*Client) ListRunningContainersUsingVolume added in v0.3.0 

func (c *Client) ListRunningContainersUsingVolume(ctx context.Context, volumeName string) ([]string, error)

ListRunningContainersUsingVolume returns names of running containers that reference the volume.

func (*Client) ListVolumes 

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

ListVolumes returns names of docker volumes.

func (*Client) NetworkSummaries added in v0.6.0 

func (c *Client) NetworkSummaries(ctx context.Context) ([]NetworkSummary, error)

NetworkSummaries returns basic metadata for docker networks (name & driver).

func (*Client) PauseContainer added in v0.6.0 

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

PauseContainer pauses a running container by name.

func (*Client) PsJSON added in v0.6.0 

func (c *Client) PsJSON(ctx context.Context, all bool, filters []string) ([]PsJSONRow, error)

PsJSON returns docker ps entries as parsed rows. When all is true, includes stopped containers (-a). Filters are passed as raw values for repeated --filter arguments, e.g., 

["label=io.dockform.identifier=myid", "label=com.docker.compose.service=web"]

func (*Client) ReadFileFromVolume 

func (c *Client) ReadFileFromVolume(ctx context.Context, volumeName, targetPath, relFile string) (string, error)

ReadFileFromVolume returns the contents of a file inside a mounted volume target path. If the file does not exist, it returns an empty string and no error.

func (*Client) RemoveContainer 

func (c *Client) RemoveContainer(ctx context.Context, name string, force bool) error

RemoveContainer removes a container by name. If force is true, the container will be stopped if running and removed.

func (*Client) RemoveNetwork 

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

func (*Client) RemovePathsFromVolume 

func (c *Client) RemovePathsFromVolume(ctx context.Context, volumeName, targetPath string, relPaths []string) error

RemovePathsFromVolume removes one or more relative paths from the mounted targetPath.

func (*Client) RemoveVolume 

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

func (*Client) RestartContainer 

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

RestartContainer restarts a container by name.

func (*Client) RunInHelperImage added in v0.6.0 

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

RunInHelperImage executes a command in the helper image without mounting volumes. Useful for checking if binaries are available.

func (*Client) RunVolumeScript added in v0.6.0 

func (c *Client) RunVolumeScript(ctx context.Context, volumeName, targetPath, script string, env []string) (VolumeScriptResult, error)

RunVolumeScript executes a shell script inside a helper container with the specified volume mounted. The volume is mounted at targetPath (e.g., /app), matching where files were synced.

func (*Client) ServerVersion added in v0.5.0 

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

ServerVersion returns the Docker Engine server version for the configured context.

func (*Client) StartContainers added in v0.3.0 

func (c *Client) StartContainers(ctx context.Context, names []string) error

StartContainers starts the given containers.

func (*Client) StopContainers added in v0.3.0 

func (c *Client) StopContainers(ctx context.Context, names []string) error

StopContainers stops the given containers gracefully.

func (*Client) StreamContainerLogs added in v0.6.0 

func (c *Client) StreamContainerLogs(ctx context.Context, name string, tail int, since string, w io.Writer) error

StreamContainerLogs streams logs for a container to w until ctx is canceled. tail specifies how many lines to include initially (0 = default). since is optional RFC3339 timestamp.

func (*Client) StreamTarFromVolume added in v0.3.0 

func (c *Client) StreamTarFromVolume(ctx context.Context, volumeName string, w io.Writer) error

StreamTarFromVolume streams a tar of the root of the volume to w. The tar is created using numeric owners and includes xattrs/acls when supported.

func (*Client) StreamTarZstdFromVolume added in v0.3.0 

func (c *Client) StreamTarZstdFromVolume(ctx context.Context, volumeName string, w io.Writer) error

StreamTarZstdFromVolume streams a zstd-compressed tar of the volume to w. It installs zstd in the helper container if missing (apk add).

func (*Client) SyncDirToVolume 

func (c *Client) SyncDirToVolume(ctx context.Context, volumeName, targetPath, localDir string) error

SyncDirToVolume streams a tar of localDir to the named volume's targetPath. Requirements: - targetPath must be absolute and not '/' - Ensure destination exists in the helper container (mkdir -p) - Mount the volume at a fixed path in the helper container and operate there - Remove current contents then extract tar stream into targetPath

func (*Client) TarStatsFromVolume added in v0.3.0 

func (c *Client) TarStatsFromVolume(ctx context.Context, volumeName string) (int64, int64, error)

TarStatsFromVolume calculates uncompressed tar size (bytes) and file count in the volume. It runs commands inside a helper container and returns (tarBytes, fileCount).

func (*Client) UpdateContainerLabels 

func (c *Client) UpdateContainerLabels(ctx context.Context, containerName string, labels map[string]string) error

UpdateContainerLabels adds or updates labels for a running container.

func (*Client) VolumeExists 

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

VolumeExists returns true if a volume with the given name exists in the Docker context, regardless of labels. This must not create the volume; it only lists existing names.

func (*Client) VolumeSummaries added in v0.6.0 

func (c *Client) VolumeSummaries(ctx context.Context) ([]VolumeSummary, error)

VolumeSummaries returns a list of volume metadata including driver and mountpoint.

func (*Client) WithIdentifier 

func (c *Client) WithIdentifier(id string) *Client

WithIdentifier sets an optional label identifier to scope discovery.

func (*Client) WriteFileToVolume 

func (c *Client) WriteFileToVolume(ctx context.Context, volumeName, targetPath, relFile, content string) error

WriteFileToVolume writes content to a file inside a mounted volume target path, creating parent directories.

type ClientFactory 

type ClientFactory interface {
	// GetClient returns a Docker client for the specified context name.
	// The identifier is used to scope resource discovery.
	GetClient(contextName, identifier string) *Client

	// GetClientForContext returns a Docker client configured for the specified context.
	GetClientForContext(contextName string, cfg *manifest.Config) *Client
}

ClientFactory creates and caches Docker clients for different contexts.

type ComposeConfigDoc 

type ComposeConfigDoc struct {
	Services map[string]ComposeService `json:"services" yaml:"services"`
}

type ComposePort 

type ComposePort struct {
	Target    int         `json:"target" yaml:"target"`
	Published interface{} `json:"published" yaml:"published"`
	Protocol  string      `json:"protocol" yaml:"protocol"`
}

type ComposePsItem 

type ComposePsItem struct {
	Name       string             `json:"Name"`
	Service    string             `json:"Service"`
	Image      string             `json:"Image"`
	State      string             `json:"State"`
	Project    string             `json:"Project"`
	Publishers []ComposePublisher `json:"Publishers"`
}

ComposePsItem is a subset of fields from `docker compose ps --format json`.

type ComposePublisher 

type ComposePublisher struct {
	URL           string `json:"URL"`
	TargetPort    int    `json:"TargetPort"`
	PublishedPort int    `json:"PublishedPort"`
	Protocol      string `json:"Protocol"`
}

type ComposeService 

type ComposeService struct {
	Image         string                 `json:"image" yaml:"image"`
	ContainerName string                 `json:"container_name" yaml:"container_name"`
	Ports         []ComposePort          `json:"ports" yaml:"ports"`
	Networks      ComposeServiceNetworks `json:"networks" yaml:"networks"`
	Volumes       []ComposeServiceVolume `json:"volumes" yaml:"volumes"`
}

type ComposeServiceNetworks added in v0.6.0 

type ComposeServiceNetworks []string

func (*ComposeServiceNetworks) UnmarshalJSON added in v0.6.0 

func (c *ComposeServiceNetworks) UnmarshalJSON(data []byte) error

type ComposeServiceVolume added in v0.6.0 

type ComposeServiceVolume struct {
	Type   string `json:"type" yaml:"type"`
	Source string `json:"source" yaml:"source"`
	Target string `json:"target" yaml:"target"`
}

type DefaultClientFactory 

type DefaultClientFactory struct {
	// contains filtered or unexported fields
}

DefaultClientFactory is the standard implementation of ClientFactory. It caches clients per context+identifier combination for efficient reuse.

func NewClientFactory 

func NewClientFactory() *DefaultClientFactory

NewClientFactory creates a new DefaultClientFactory.

func (*DefaultClientFactory) GetAllClients 

func (f *DefaultClientFactory) GetAllClients() map[string]*Client

GetAllClients returns all cached clients. Useful for cleanup or bulk operations.

func (*DefaultClientFactory) GetClient 

func (f *DefaultClientFactory) GetClient(contextName, identifier string) *Client

GetClient returns a Docker client for the specified context name. Clients are cached and reused for the same context+identifier combination.

func (*DefaultClientFactory) GetClientForContext 

func (f *DefaultClientFactory) GetClientForContext(contextName string, cfg *manifest.Config) *Client

GetClientForContext returns a Docker client configured for the specified context. When the context has a host override in the manifest, the client uses DOCKER_HOST instead of DOCKER_CONTEXT.

type Exec 

type Exec interface {
	Run(ctx context.Context, args ...string) (string, error)
	RunInDir(ctx context.Context, dir string, args ...string) (string, error)
	RunInDirWithEnv(ctx context.Context, dir string, extraEnv []string, args ...string) (string, error)
	RunWithStdin(ctx context.Context, stdin io.Reader, args ...string) (string, error)
	// RunWithStdout streams the stdout of the docker command to the provided writer without buffering it in memory.
	// Stderr is still captured and included in any returned error for debuggability.
	RunWithStdout(ctx context.Context, stdout io.Writer, args ...string) error
	// RunDetailed runs a command and returns structured Result with stdout, stderr, and exit code.
	RunDetailed(ctx context.Context, opts Options, args ...string) (Result, error)
}

Exec abstracts docker command execution for ease of testing.

type ExecEvent 

type ExecEvent struct {
	Phase    string // "start" or "finish"
	Args     []string
	Dir      string
	Duration time.Duration
	ExitCode int
	Err      error
}

ExecEvent describes a loggable moment in command execution.

type LRUCache 

type LRUCache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

LRUCache is a simple thread-safe LRU cache with a maximum size. When the cache exceeds maxSize, the least recently used entries are evicted.

func NewLRUCache 

func NewLRUCache[K comparable, V any](maxSize int) *LRUCache[K, V]

NewLRUCache creates a new LRU cache with the specified maximum size. If maxSize <= 0, it defaults to 100.

func (*LRUCache[K, V]) Clear 

func (c *LRUCache[K, V]) Clear()

Clear removes all items from the cache.

func (*LRUCache[K, V]) Get 

func (c *LRUCache[K, V]) Get(key K) (V, bool)

Get retrieves a value from the cache. Returns the value and true if found, or the zero value and false if not found. Accessing an item moves it to the front (most recently used).

func (*LRUCache[K, V]) Len 

func (c *LRUCache[K, V]) Len() int

Len returns the number of items in the cache.

func (*LRUCache[K, V]) Set 

func (c *LRUCache[K, V]) Set(key K, value V)

Set adds or updates a value in the cache. If the cache is at capacity, the least recently used entry is evicted.

type LoggerHook 

type LoggerHook func(event ExecEvent)

LoggerHook receives start and finish events for command execution.

type NetworkCreateOpts added in v0.3.0 

type NetworkCreateOpts struct {
	Driver       string
	Options      map[string]string
	Internal     bool
	Attachable   bool
	IPv6         bool
	Subnet       string
	Gateway      string
	IPRange      string
	AuxAddresses map[string]string
}

NetworkCreateOpts represents supported docker network create flags.

type NetworkInspect added in v0.3.0 

type NetworkInspect struct {
	Name       string             `json:"Name"`
	Driver     string             `json:"Driver"`
	Options    map[string]string  `json:"Options"`
	Internal   bool               `json:"Internal"`
	Attachable bool               `json:"Attachable"`
	EnableIPv6 bool               `json:"EnableIPv6"`
	IPAM       NetworkInspectIPAM `json:"IPAM"`
	Containers map[string]struct {
		Name string `json:"Name"`
	} `json:"Containers"`
}

NetworkInspect represents the subset of docker network inspect we need

type NetworkInspectIPAM added in v0.3.0 

type NetworkInspectIPAM struct {
	Driver string                     `json:"Driver"`
	Config []NetworkInspectIPAMConfig `json:"Config"`
}

NetworkInspectIPAM represents IPAM section of network inspect

type NetworkInspectIPAMConfig added in v0.3.0 

type NetworkInspectIPAMConfig struct {
	Subnet       string            `json:"Subnet"`
	Gateway      string            `json:"Gateway"`
	IPRange      string            `json:"IPRange"`
	AuxAddresses map[string]string `json:"AuxiliaryAddresses"`
}

NetworkInspectIPAMConfig represents a single IPAM config entry

type NetworkSummary added in v0.6.0 

type NetworkSummary struct {
	Name   string
	Driver string
}

NetworkSummary contains key metadata about a network for dashboard display.

type Options 

type Options struct {
	Dir     string
	Env     []string
	Stdin   io.Reader
	Timeout time.Duration
}

Options controls execution behavior per call.

type PsBrief 

type PsBrief struct {
	Project string
	Service string
	Name    string
}

PsBrief represents a container with compose labels.

type PsJSONRow added in v0.6.0 

type PsJSONRow struct {
	ID     string `json:"ID"`
	Names  string `json:"Names"`
	Image  string `json:"Image"`
	Status string `json:"Status"`
	State  string `json:"State"`
	Labels string `json:"Labels"`
}

PsJSONRow represents a single line of `docker ps --format {{json .}}` output. Only the fields we need are included; additional fields are ignored by json.Unmarshal.

func (PsJSONRow) LabelValue added in v0.6.0 

func (r PsJSONRow) LabelValue(key string) string

LabelValue parses a comma-separated label string (as returned by docker ps) and returns the value for key.

type Result 

type Result struct {
	Stdout   string
	Stderr   string
	ExitCode int
	Duration time.Duration
}

Result contains structured outcome of a command.

type SystemExec 

type SystemExec struct {
	ContextName    string
	HostOverride   string // When set, uses DOCKER_HOST instead of DOCKER_CONTEXT
	DefaultTimeout time.Duration
	Logger         LoggerHook
}

SystemExec is a real implementation that shells out to the docker CLI.

func (SystemExec) Run 

func (s SystemExec) Run(ctx context.Context, args ...string) (string, error)

func (SystemExec) RunDetailed 

func (s SystemExec) RunDetailed(ctx context.Context, opts Options, args ...string) (Result, error)

func (SystemExec) RunInDir 

func (s SystemExec) RunInDir(ctx context.Context, dir string, args ...string) (string, error)

func (SystemExec) RunInDirWithEnv 

func (s SystemExec) RunInDirWithEnv(ctx context.Context, dir string, extraEnv []string, args ...string) (string, error)

func (SystemExec) RunWithStdin 

func (s SystemExec) RunWithStdin(ctx context.Context, stdin io.Reader, args ...string) (string, error)

func (SystemExec) RunWithStdout added in v0.3.0 

func (s SystemExec) RunWithStdout(ctx context.Context, stdout io.Writer, args ...string) error

RunWithStdout executes the docker command and streams stdout to the provided writer. It does not buffer stdout in memory.

func (*SystemExec) WithDefaultTimeout 

func (s *SystemExec) WithDefaultTimeout(d time.Duration) *SystemExec

WithDefaultTimeout sets a default timeout for all runs when Options.Timeout is not provided.

func (*SystemExec) WithLogger 

func (s *SystemExec) WithLogger(h LoggerHook) *SystemExec

WithLogger sets a logger hook to observe command execution.

type VolumeDetails added in v0.3.0 

type VolumeDetails struct {
	Name       string            `json:"Name"`
	Driver     string            `json:"Driver"`
	Mountpoint string            `json:"Mountpoint"`
	Options    map[string]string `json:"Options"`
	Labels     map[string]string `json:"Labels"`
}

VolumeDetails contains driver, options and labels of a volume.

type VolumeScriptResult added in v0.6.0 

type VolumeScriptResult struct {
	Stdout string
	Stderr string
}

VolumeScriptResult contains the output from a volume script execution.

type VolumeSummary added in v0.6.0 

type VolumeSummary struct {
	Name       string
	Driver     string
	Mountpoint string
}

VolumeSummary contains basic metadata about a volume for dashboard display.

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.