docker

package
v0.0.0-...-ac86271 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package docker wraps the Docker SDK behind havn-native types.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNetworkAlreadyExists = errors.New("network already exists")

ErrNetworkAlreadyExists is returned by NetworkCreate when the requested network name is already in use.

Functions

func BuildMounts 

func BuildMounts(binds []BindMount, volumes []VolumeMount) []dockermount.Mount

BuildMounts converts havn bind and volume mounts to Docker SDK mounts.

func BuildPortBindings 

func BuildPortBindings(ports []string) (nat.PortSet, nat.PortMap, error)

BuildPortBindings converts host:container(/proto) mappings into Docker types.

func EnvSlice 

func EnvSlice(env map[string]string) []string

EnvSlice converts a map of environment variables to the Docker SDK's "KEY=VALUE" slice format.

func ParseMemoryBytes 

func ParseMemoryBytes(s string) int64

ParseMemoryBytes converts a memory string like "4g" or "512m" to bytes. Returns 0 for empty or unrecognized strings.

func TerminalFd 

func TerminalFd(r io.Reader) int

TerminalFd returns the file descriptor if r provides one via an Fd() method (e.g. *os.File), or -1 if the reader is not backed by a file descriptor.

Types

type AttachOpts 

type AttachOpts struct {
	Cmd     []string  // Command and arguments to execute
	Env     []string  // Environment variables (KEY=VALUE)
	Workdir string    // Working directory inside the container
	User    string    // User to run the command as
	Stdin   io.Reader // Host stdin (typically os.Stdin)
	Stdout  io.Writer // Host stdout (typically os.Stdout)
	Stderr  io.Writer // Host stderr (typically os.Stderr)
}

AttachOpts holds parameters for an interactive tty exec session.

type BindMount 

type BindMount struct {
	Source   string
	Target   string
	ReadOnly bool
}

BindMount represents a host-to-container bind mount.

type BuildOpts 

type BuildOpts struct {
	Tag        string            // image tag to apply
	Context    string            // path to build context directory
	Dockerfile string            // Dockerfile path relative to context
	BuildArgs  map[string]string // build-time variables
	Output     io.Writer         // streaming build output destination
}

BuildOpts holds parameters for building a Docker image.

type Client 

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

Client wraps the Docker SDK client. The SDK client is a private field, never exposed outside this package.

func NewClient 

func NewClient() (*Client, error)

NewClient creates a Client using environment-based configuration (DOCKER_HOST, DOCKER_API_VERSION, etc.). Construction is lazy — no connection is made until a method is called.

func NewClientWithHost 

func NewClientWithHost(host string) (*Client, error)

NewClientWithHost creates a Client targeting a specific Docker host.

func NewClientWithHostAndLogger 

func NewClientWithHostAndLogger(host string, logger *slog.Logger) (*Client, error)

NewClientWithHostAndLogger creates a Client targeting a specific Docker host and uses the injected logger for structured diagnostics.

func (*Client) ContainerAttach 

func (c *Client) ContainerAttach(ctx context.Context, nameOrID string, opts AttachOpts) (int, error)

ContainerAttach creates and attaches to an interactive tty exec session in the specified container. It proxies stdin/stdout/stderr between the host and the container process, handles SIGWINCH for terminal resizing, and puts the host terminal into raw mode for the duration of the session. Returns the remote process exit code. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) ContainerCreate 

func (c *Client) ContainerCreate(ctx context.Context, opts CreateOpts) (string, error)

ContainerCreate creates a container from the given options. Returns the container ID on success. Returns *ImageNotFoundError if the image does not exist locally.

func (*Client) ContainerExec 

func (c *Client) ContainerExec(ctx context.Context, nameOrID string, opts ExecOpts) (ExecResult, error)

ContainerExec runs a non-interactive one-shot command in the specified container and captures stdout/stderr. A non-zero exit code is returned in ExecResult, not as an error — only exec-plumbing failures return errors. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) ContainerInspect 

func (c *Client) ContainerInspect(ctx context.Context, nameOrID string) (ContainerInfo, error)

ContainerInspect returns detailed information about a container by name or ID. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) ContainerList 

func (c *Client) ContainerList(ctx context.Context, filters ContainerListFilters) ([]ContainerInfo, error)

ContainerList returns containers matching the given filters. Returns an empty slice (not nil) when no containers match.

func (*Client) ContainerRemove 

func (c *Client) ContainerRemove(ctx context.Context, nameOrID string, opts RemoveOpts) error

ContainerRemove removes a container by name or ID. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) ContainerStart 

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

ContainerStart starts a container by name or ID. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) ContainerStop 

func (c *Client) ContainerStop(ctx context.Context, nameOrID string, opts StopOpts) error

ContainerStop stops a container by name or ID with the given options. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) CopyFromContainer 

func (c *Client) CopyFromContainer(ctx context.Context, nameOrID string, srcPath string) (io.ReadCloser, error)

CopyFromContainer returns a tar stream of the contents at srcPath inside the container. The caller must close the returned ReadCloser. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) CopyToContainer 

func (c *Client) CopyToContainer(ctx context.Context, nameOrID string, dstPath string, tarStream io.Reader) error

CopyToContainer copies a tar stream into the container at dstPath. Returns *ContainerNotFoundError if the container does not exist.

func (*Client) ImageBuild 

func (c *Client) ImageBuild(ctx context.Context, opts BuildOpts) error

ImageBuild builds a Docker image from the given build context. Build output is streamed to opts.Output. Returns *ImageBuildError if the build itself fails (Dockerfile error, etc.).

func (*Client) ImageExists 

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

ImageExists checks whether an image exists locally. Returns (false, nil) when the image is not found — not an error. Other failures (e.g., daemon unreachable) are returned as errors.

func (*Client) ImageInspect 

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

ImageInspect returns metadata about a Docker image by name or ID. Returns *ImageNotFoundError if the image does not exist locally.

func (*Client) ImagePull 

func (c *Client) ImagePull(ctx context.Context, ref string, output io.Writer) error

ImagePull pulls an image reference from the configured registry and streams daemon output to output when provided.

func (*Client) Info 

func (c *Client) Info(ctx context.Context) (DaemonInfo, error)

Info returns metadata about the Docker daemon. Returns *DaemonUnreachableError when the daemon is unreachable.

func (*Client) NetworkCreate 

func (c *Client) NetworkCreate(ctx context.Context, opts NetworkCreateOpts) error

NetworkCreate creates a named network with the given options. Returns ErrNetworkAlreadyExists if a network with the same name already exists.

func (*Client) NetworkInspect 

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

NetworkInspect returns information about a network by name. Returns *NetworkNotFoundError if the network does not exist.

func (*Client) NetworkList 

func (c *Client) NetworkList(ctx context.Context, filters NetworkListFilters) ([]NetworkInfo, error)

NetworkList returns networks matching the given filters. Returns an empty slice (not nil) when no networks match.

func (*Client) Ping 

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

Ping checks if the Docker daemon is reachable. Returns *DaemonUnreachableError when it is not; nil when it is.

func (*Client) SetLogger 

func (c *Client) SetLogger(logger *slog.Logger)

SetLogger replaces the client's logger used for structured diagnostics.

func (*Client) VolumeCreate 

func (c *Client) VolumeCreate(ctx context.Context, opts VolumeCreateOpts) error

VolumeCreate creates a named volume with the given options.

func (*Client) VolumeInspect 

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

VolumeInspect returns information about a volume by name. Returns *VolumeNotFoundError if the volume does not exist.

func (*Client) VolumeList 

func (c *Client) VolumeList(ctx context.Context, filters VolumeListFilters) ([]VolumeInfo, error)

VolumeList returns volumes matching the given filters. Returns an empty slice (not nil) when no volumes match.

type ConnectedContainer 

type ConnectedContainer struct {
	ID   string
	Name string
}

ConnectedContainer identifies a container attached to a network.

type ContainerInfo 

type ContainerInfo struct {
	ID       string
	Name     string
	Image    string
	Status   string // e.g. "running", "exited"
	Labels   map[string]string
	Mounts   []MountInfo
	Networks []string
	Env      []string
}

ContainerInfo holds read-only state of a container.

type ContainerListFilters 

type ContainerListFilters struct {
	Labels     map[string]string // label key=value pairs to match
	NamePrefix string            // container name prefix filter
	Status     string            // e.g. "running", "exited"
}

ContainerListFilters holds filter criteria for listing containers.

type ContainerNotFoundError 

type ContainerNotFoundError struct {
	Name string
}

ContainerNotFoundError indicates a container does not exist in Docker.

func (*ContainerNotFoundError) Error 

func (e *ContainerNotFoundError) Error() string

func (*ContainerNotFoundError) ErrorDetails 

func (e *ContainerNotFoundError) ErrorDetails() map[string]any

ErrorDetails returns structured fields for JSON error output.

func (*ContainerNotFoundError) ErrorType 

func (e *ContainerNotFoundError) ErrorType() string

ErrorType returns the stable snake_case identifier for this error.

type CreateOpts 

type CreateOpts struct {
	Image         string
	Name          string
	Network       string
	Ports         []string
	Env           map[string]string
	Labels        map[string]string
	BindMounts    []BindMount
	VolumeMounts  []VolumeMount
	RestartPolicy string
	TTY           bool
	Workdir       string
	Cmd           []string
	Entrypoint    []string
	User          string
	CPUs          int
	Memory        string
	MemorySwap    string
	AutoRemove    bool
}

CreateOpts holds parameters for creating a container.

type DaemonInfo 

type DaemonInfo struct {
	ServerVersion string
	APIVersion    string
}

DaemonInfo holds metadata about the Docker daemon.

type DaemonUnreachableError 

type DaemonUnreachableError struct {
	Host string
}

DaemonUnreachableError indicates the Docker daemon cannot be contacted.

func (*DaemonUnreachableError) Error 

func (e *DaemonUnreachableError) Error() string

func (*DaemonUnreachableError) ErrorDetails 

func (e *DaemonUnreachableError) ErrorDetails() map[string]any

ErrorDetails returns structured fields for JSON error output.

func (*DaemonUnreachableError) ErrorType 

func (e *DaemonUnreachableError) ErrorType() string

ErrorType returns the stable snake_case identifier for this error.

type ExecOpts 

type ExecOpts struct {
	Cmd          []string     // Command and arguments to execute
	Env          []string     // Environment variables (KEY=VALUE)
	Workdir      string       // Working directory inside the container
	User         string       // User to run the command as
	OnStderrLine func(string) // Optional callback for incremental stderr lines
}

ExecOpts holds parameters for a non-interactive one-shot exec.

type ExecResult 

type ExecResult struct {
	ExitCode int    // Process exit code
	Stdout   []byte // Captured stdout bytes
	Stderr   []byte // Captured stderr bytes
}

ExecResult holds the outcome of a non-interactive exec. A non-zero ExitCode is not an error — only exec-plumbing failures return errors.

type ImageBuildError 

type ImageBuildError struct {
	Tag    string
	Detail string
}

ImageBuildError indicates that a Docker image build failed.

func (*ImageBuildError) Error 

func (e *ImageBuildError) Error() string

func (*ImageBuildError) ErrorDetails 

func (e *ImageBuildError) ErrorDetails() map[string]any

ErrorDetails returns structured fields for JSON error output.

func (*ImageBuildError) ErrorType 

func (e *ImageBuildError) ErrorType() string

ErrorType returns the stable snake_case identifier for this error.

type ImageInfo 

type ImageInfo struct {
	ID        string
	Tag       string
	CreatedAt string
}

ImageInfo holds read-only metadata about a Docker image.

type ImageNotFoundError 

type ImageNotFoundError struct {
	Name string
}

ImageNotFoundError indicates a Docker image does not exist locally.

func (*ImageNotFoundError) Error 

func (e *ImageNotFoundError) Error() string

func (*ImageNotFoundError) ErrorDetails 

func (e *ImageNotFoundError) ErrorDetails() map[string]any

ErrorDetails returns structured fields for JSON error output.

func (*ImageNotFoundError) ErrorType 

func (e *ImageNotFoundError) ErrorType() string

ErrorType returns the stable snake_case identifier for this error.

type MountInfo 

type MountInfo struct {
	Source string
	Target string
	Type   string // e.g. "bind", "volume"
	Mode   string // e.g. "rw", "ro"
}

MountInfo describes a mount attached to a container.

type NetworkCreateOpts 

type NetworkCreateOpts struct {
	Name   string
	Labels map[string]string
}

NetworkCreateOpts holds parameters for creating a network.

type NetworkInfo 

type NetworkInfo struct {
	Name                string
	ID                  string
	Driver              string
	ConnectedContainers []ConnectedContainer
}

NetworkInfo holds read-only state of a Docker network.

type NetworkListFilters 

type NetworkListFilters struct {
	NamePrefix string // network name prefix filter
}

NetworkListFilters holds filter criteria for listing networks.

type NetworkNotFoundError 

type NetworkNotFoundError struct {
	Name string
}

NetworkNotFoundError indicates a Docker network does not exist.

func (*NetworkNotFoundError) Error 

func (e *NetworkNotFoundError) Error() string

func (*NetworkNotFoundError) ErrorDetails 

func (e *NetworkNotFoundError) ErrorDetails() map[string]any

ErrorDetails returns structured fields for JSON error output.

func (*NetworkNotFoundError) ErrorType 

func (e *NetworkNotFoundError) ErrorType() string

ErrorType returns the stable snake_case identifier for this error.

type RemoveOpts 

type RemoveOpts struct {
	Force         bool
	RemoveVolumes bool
}

RemoveOpts holds parameters for removing a container.

type StopOpts 

type StopOpts struct {
	Timeout int // seconds
}

StopOpts holds parameters for stopping a container.

type VolumeCreateOpts 

type VolumeCreateOpts struct {
	Name   string
	Labels map[string]string
}

VolumeCreateOpts holds parameters for creating a volume.

type VolumeInfo 

type VolumeInfo struct {
	Name       string
	Driver     string
	Labels     map[string]string
	Mountpoint string
	CreatedAt  string
}

VolumeInfo holds read-only state of a Docker volume.

type VolumeListFilters 

type VolumeListFilters struct {
	Labels     map[string]string // label key=value pairs to match
	NamePrefix string            // volume name prefix filter
}

VolumeListFilters holds filter criteria for listing volumes.

type VolumeMount 

type VolumeMount struct {
	Name   string
	Target string
}

VolumeMount represents a named volume mount.

type VolumeNotFoundError 

type VolumeNotFoundError struct {
	Name string
}

VolumeNotFoundError indicates a Docker volume does not exist.

func (*VolumeNotFoundError) Error 

func (e *VolumeNotFoundError) Error() string

func (*VolumeNotFoundError) ErrorDetails 

func (e *VolumeNotFoundError) ErrorDetails() map[string]any

ErrorDetails returns structured fields for JSON error output.

func (*VolumeNotFoundError) ErrorType 

func (e *VolumeNotFoundError) ErrorType() string

ErrorType returns the stable snake_case identifier for this error.

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.