github.com/moby/moby/client

Purpose

A Go HTTP client for the Engine API. The Docker CLI uses it; so can any third-party tool. The package is small, dependency-light, and tagged independently as client/v1.x.x.

Hello world

From client/README.md:

import "github.com/moby/moby/client"

apiClient, err := client.New(
    client.FromEnv,
    client.WithUserAgent("my-application/1.0.0"),
)
if err != nil { panic(err) }
defer apiClient.Close()

ctrs, err := apiClient.ContainerList(ctx, client.ContainerListOptions{All: true})

client.FromEnv reads DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY. API version negotiation is on by default.

Layout

client/
├── go.mod
├── client.go              # Client struct, New, options
├── client_options.go      # WithHost, WithVersion, WithHTTPClient, etc.
├── client_interfaces.go   # The "*API" interfaces (ContainerAPIClient, ...)
├── request.go             # Low-level HTTP request helpers
├── hijack.go              # Connection hijacking for attach/exec/build/grpc
├── envvars.go             # FromEnv loader
├── errors.go, filters.go, utils.go, version.go
├── ping.go                # /_ping support
├── login.go               # /auth helper
├── container_*.go         # Per-endpoint methods
├── image_*.go
├── network_*.go
├── volume_*.go
├── service_*.go, task_*.go, node_*.go, secret_*.go, config_*.go
├── swarm_*.go
├── plugin_*.go
├── checkpoint_*.go
├── distribution_inspect.go
├── system_*.go            # info, events, disk usage
├── internal/              # client-only helpers (not exported)
├── pkg/                   # client-only utility packages
├── testdata/
└── releases/

Method shape

Each Engine API endpoint maps to a method on Client. Per-endpoint files keep the package navigable. Examples:

• ContainerCreate(ctx, config, hostConfig, networkingConfig, platform, name)
• ContainerStart(ctx, ContainerStartOptions{ID: ...})
• ImagePull(ctx, ref, ImagePullOptions{...}) (io.ReadCloser, error)
• Events(ctx, EventsOptions{...}) (<-chan events.Message, <-chan error)
• BuildCancel(ctx, id)

Streaming endpoints (logs, attach, exec start, events, pull/push, build) return either an io.ReadCloser over the chunked HTTP response or a hijacked net.Conn/bufio.Reader pair. The hijack helpers are in hijack.go.

Interfaces

client_interfaces.go declares per-resource interfaces (ContainerAPIClient, ImageAPIClient, SwarmAPIClient, ...). The concrete Client satisfies all of them, but tests can mock individual ones cheaply. client_mock_test.go provides a hand-written mock used by the package's own tests.

Version negotiation

When WithAPIVersionNegotiation is on (default), the first call probes /_ping and downgrades to the daemon's max version if the client was compiled against a newer one. This makes a single binary work against a range of daemons.

Errors

Errors are wrapped with helpers in errors.go. client.IsErrNotFound, client.IsErrConnectionFailed, etc. are the public predicates clients should use.

Testing

client_test.go runs against a fake HTTP server. Each per-endpoint file has a sibling _test.go with table-driven cases. request_test.go covers the low-level transport.

Stability

client follows SemVer in its own tag stream (client/v1.x.x). Major bumps are reserved for breaking changes; option-struct additions are non-breaking.

See also

• api for the request/response types.
• API endpoints for the daemon-side perspective.
• client/README.md for the canonical example.