README
¶
Docker
Helpers for working with the Docker Engine API: container names, Compose labels, mounts, networks, exec, logs, progress rendering, and volume usage
Documentation
¶
Overview ¶
Package docker provides helpers for working with the Docker Engine API: container names and Compose labels, mount translation and preservation, network selection, exec and log streaming, progress rendering, and cached volume usage.
Index ¶
- Constants
- func BuildNetworkUsageMaps(containers []container.Summary) (map[string]bool, map[string]bool)
- func ComposeProjectLabel(labels map[string]string) string
- func ComposeServiceLabel(labels map[string]string) string
- func ContainerAnswersToHostname(c *container.Summary, host string) bool
- func ContainerNameExcluded(names []string, excluded map[string]bool) bool
- func ContainerNameFromNames(names []string) string
- func ExcludedContainerNameSet(raw string) map[string]bool
- func ExecInContainer(ctx context.Context, dockerClient *client.Client, containerID string, ...) (int, error)
- func FetchVolumeUsageData(ctx context.Context, dockerClient *client.Client) ([]volume.Volume, error)
- func FilterContainersUsingVolume(containers []container.Summary, volumeName string) []string
- func GetContainersUsingVolume(ctx context.Context, dockerClient *client.Client, volumeName string) ([]string, error)
- func GetVolumeUsageData(ctx context.Context, dockerClient *client.Client) ([]volume.Volume, error)
- func GetVolumeUsageDataStaleWhileRevalidate(ctx context.Context, dockerClient *client.Client) mo.Option[[]volume.Volume]
- func InvalidateVolumeUsageCache(dockerClient *client.Client)
- func IsDefaultNetwork(name string) bool
- func IsExpectedStreamEndError(err error) bool
- func MountForDestination(mounts []container.MountPoint, destination, target string) *mount.Mount
- func MountForEnclosingPath(mounts []container.MountPoint, containerPath, target string) (*mount.Mount, string)
- func MountForSubpath(mounts []container.MountPoint, containerPath, target string) *mount.Mount
- func NestedMounts(mounts []container.MountPoint, containerPath, target string) []mount.Mount
- func NewLogLineWriter(dst io.Writer) io.WriteCloser
- func PreserveVolumeMounts(ctx context.Context, binds []string, mounts []mount.Mount, ...) ([]string, []mount.Mount, error)
- func ReadAllLogs(ctx context.Context, logs io.ReadCloser, logsChan chan<- string) error
- func ReadLogLines(ctx context.Context, reader io.Reader, logsChan chan<- string, prefix string) error
- func RenderJSONMessageStream(reader io.Reader, out io.Writer) error
- func SelectAutoNetworkMode(inspect *container.InspectResponse) string
- func SelectDockerHostReachableNetworkMode(ctx context.Context, dockerClient *client.Client, ...) string
- func StartStdCopy(stream io.Reader, stdout, stderr io.Writer) <-chan error
- func StreamContainerLogs(ctx context.Context, logs io.ReadCloser, logsChan chan<- string, ...) error
- func StreamMultiplexedLogs(ctx context.Context, logs io.Reader, logsChan chan<- string) error
- func WaitStdCopy(done <-chan error) error
Constants ¶
const ( ComposeProjectLabelKey = "com.docker.compose.project" ComposeServiceLabelKey = "com.docker.compose.service" )
Docker Compose attaches these labels to every container it manages. They identify the owning project and the service within that project.
Variables ¶
This section is empty.
Functions ¶
func BuildNetworkUsageMaps ¶
BuildNetworkUsageMaps indexes container network attachments by ID and name.
func ComposeProjectLabel ¶
ComposeProjectLabel returns the trimmed Docker Compose project name from a container's labels, or "" when unset.
func ComposeServiceLabel ¶
ComposeServiceLabel returns the trimmed Docker Compose service name from a container's labels, or "" when unset.
func ContainerAnswersToHostname ¶
ContainerAnswersToHostname reports whether the container is addressable as host on some network: by container name, compose service name, or an endpoint DNS name/alias.
func ContainerNameExcluded ¶
ContainerNameExcluded reports whether any of Docker's container names, stripped of the leading slash, appears in the exclusion lookup.
func ContainerNameFromNames ¶
ContainerNameFromNames returns Docker's first container name without the leading slash Docker stores in container summaries.
func ExcludedContainerNameSet ¶
ExcludedContainerNameSet parses a comma-separated exclusion setting into a name lookup. Returns nil when the setting names no containers.
func ExecInContainer ¶
func ExecInContainer(ctx context.Context, dockerClient *client.Client, containerID string, opts client.ExecCreateOptions, stdout, stderr io.Writer) (int, error)
ExecInContainer runs an exec in containerID, demultiplexing its output into stdout and stderr, and returns the exec's exit code. A non-zero exit code is not an error — callers decide how to report it.
func FetchVolumeUsageData ¶
func FetchVolumeUsageData(ctx context.Context, dockerClient *client.Client) ([]volume.Volume, error)
FetchVolumeUsageData queries the daemon for volume usage, bypassing the cache.
func FilterContainersUsingVolume ¶
FilterContainersUsingVolume returns the IDs of containers in the provided slice that mount the named volume. Use this when checking many volumes in a row — list containers once and reuse the slice.
func GetContainersUsingVolume ¶
func GetContainersUsingVolume(ctx context.Context, dockerClient *client.Client, volumeName string) ([]string, error)
GetContainersUsingVolume lists all containers and returns IDs that mount the named volume. For batch checks (multiple volumes), prefer listing containers once via dockerClient.ContainerList and calling FilterContainersUsingVolume per volume.
func GetVolumeUsageData ¶
GetVolumeUsageData returns current volume usage data, sharing an in-flight refresh with concurrent callers while allowing each caller to honor its own context.
func GetVolumeUsageDataStaleWhileRevalidate ¶
func GetVolumeUsageDataStaleWhileRevalidate(ctx context.Context, dockerClient *client.Client) mo.Option[[]volume.Volume]
GetVolumeUsageDataStaleWhileRevalidate returns immediately with any cached snapshot and starts a bounded refresh when the snapshot is stale or missing.
func InvalidateVolumeUsageCache ¶
InvalidateVolumeUsageCache invalidates usage data for the Docker daemon used by dockerClient.
func IsDefaultNetwork ¶
IsDefaultNetwork reports whether name is one of Docker's built-in networks.
func IsExpectedStreamEndError ¶
IsExpectedStreamEndError reports whether err is the ordinary way a Docker attach/log stream ends rather than a real failure.
func MountForDestination ¶
func MountForDestination(mounts []container.MountPoint, destination, target string) *mount.Mount
MountForDestination returns a Mount suitable for container creation that mirrors an existing container mount at the given destination.
It currently supports bind and named volume mounts. If target is empty, destination is used as the target.
func MountForEnclosingPath ¶
func MountForEnclosingPath(mounts []container.MountPoint, containerPath, target string) (*mount.Mount, string)
MountForEnclosingPath returns the most-specific mount covering containerPath mounted whole at target, plus containerPath's path relative to that mount. Unlike MountForSubpath the subpath need not exist yet, so restores can create it. Returns nil when no bind or volume mount covers containerPath.
func MountForSubpath ¶
func MountForSubpath(mounts []container.MountPoint, containerPath, target string) *mount.Mount
MountForSubpath returns a Mount that exposes a subpath of one of the current container's existing mounts at the requested target. It's a generalisation of MountForDestination for the case where the caller wants a sub-tree below an existing mount destination (e.g. "/app/data/projects/X" when "/app/data" is what the container has mounted).
The function picks the most-specific mount whose Destination is a prefix of containerPath, then constructs the Mount based on the backing type:
- TypeBind: Source = mount.Source joined with the relative subpath. Works because bind sources are real host paths the daemon can address directly.
- TypeVolume: Source = mount.Name (the volume name), and the relative subpath is set on VolumeOptions.Subpath. This lets the daemon mount the named volume directly without needing a host-side path translation — important for setups where the underlying volume storage is opaque (Docker Desktop on WSL2, Docker-in-Docker, etc.).
Returns nil if no mount destination is a prefix of containerPath or if the matching mount is of an unsupported type.
func NestedMounts ¶
func NestedMounts(mounts []container.MountPoint, containerPath, target string) []mount.Mount
NestedMounts mirrors every bind or volume mount whose destination lies strictly below containerPath, re-targeted beneath target, so a helper container sees the same tree the current container does. Parents precede their children; unsupported mount types are skipped.
func NewLogLineWriter ¶
func NewLogLineWriter(dst io.Writer) io.WriteCloser
NewLogLineWriter returns a writer that splits everything written to it on newlines and emits each line as a {"log":"<line>"} NDJSON frame to dst, flushing after each frame when dst supports it. Close flushes any trailing partial line as a final frame. Writers such as compose's plain progress renderer and jsonmessage.DisplayJSONMessagesStream write raw CLI text into this to put docker-CLI-parity output on the wire.
func PreserveVolumeMounts ¶
func PreserveVolumeMounts(ctx context.Context, binds []string, mounts []mount.Mount, mountPoints []container.MountPoint) ([]string, []mount.Mount, error)
PreserveVolumeMounts returns cloned binds and mounts with every inspected volume pinned to its name, so a recreate reuses it instead of a new anonymous one.
func ReadAllLogs ¶
ReadAllLogs reads a non-follow Docker multiplexed log stream and sends non-empty stdout/stderr lines to logsChan.
func ReadLogLines ¶
func ReadLogLines(ctx context.Context, reader io.Reader, logsChan chan<- string, prefix string) error
ReadLogLines sends each non-empty line from reader to logsChan, prepending prefix, until EOF or ctx is done.
func RenderJSONMessageStream ¶
RenderJSONMessageStream renders a Docker JSON message stream (image pull, push, build, load) as the raw text the docker CLI prints in non-TTY mode, writing it to out. Any daemon-reported error is returned verbatim.
func SelectAutoNetworkMode ¶
func SelectAutoNetworkMode(inspect *container.InspectResponse) string
SelectAutoNetworkMode picks the network mode a helper container should share with the inspected container, preferring user-defined networks over defaults.
func SelectDockerHostReachableNetworkMode ¶
func SelectDockerHostReachableNetworkMode(ctx context.Context, dockerClient *client.Client, inspect *container.InspectResponse, dockerHost string) string
SelectDockerHostReachableNetworkMode picks the network for a helper container that must reach a tcp DOCKER_HOST (e.g. a docker-socket-proxy). When the DOCKER_HOST hostname matches a running container — by name, compose service, or DNS alias — that shares a network with the current container, that shared network wins. SelectAutoNetworkMode's alphabetical heuristic routinely lands on an unrelated external network on multi-network setups, leaving the helper unable to reach the daemon.
func StartStdCopy ¶
StartStdCopy demultiplexes a Docker stream into stdout/stderr on a goroutine and reports the copy result on the returned channel. Pair with WaitStdCopy.
func StreamContainerLogs ¶
func StreamContainerLogs(ctx context.Context, logs io.ReadCloser, logsChan chan<- string, follow, isTTY bool) error
StreamContainerLogs streams Docker container logs, handling TTY raw streams and non-TTY multiplexed stdout/stderr streams.
func StreamMultiplexedLogs ¶
StreamMultiplexedLogs demultiplexes a Docker stdout/stderr log stream and sends non-empty lines to logsChan.
func WaitStdCopy ¶
WaitStdCopy waits for a StartStdCopy goroutine, treating an ordinary stream end as success.
Types ¶
This section is empty.
Source Files
Directories