API-Docker
view release on metacpan or search on metacpan
misc/agent-context/.claude/skills/api-docker-core/SKILL.md view on Meta::CPAN
---
name: api-docker-core
description: "Use when working on the API::Docker distribution's client architecture â the HTTP transport role and its socket handling (unix://, tcp://, TLS), a resource API under API::Docker::API::*, how list/inspect wrap a daemon response into a ...
---
# API::Docker â architecture and invariants
A pure-Perl client for the Docker Engine HTTP API. It speaks HTTP/1.1 over the
daemon's socket and never shells out to the `docker` binary, so any engine
serving that API works (Podman's rootless socket needs only `DOCKER_HOST`).
## The three layers
```
API::Docker client; host, api_version, negotiation
ââ with API::Docker::Role::HTTP _request + get/post/put/delete_request
ââ ->images / ->containers / ->networks / ->volumes / ->system / ->exec
API::Docker::API::* one class per resource, holds `client`
ââ _wrap / _wrap_list â from_data($data, client => ...) on an
API::Docker::Type::* class with API::Docker::Role::Entity::* on it
```
**`_request($method, $path, %opts)` is the only way out of the process.** Every
resource method goes through it (usually via `get`/`post`/`put`/`delete_request`).
A new endpoint never opens its own socket.
Options: `body` (JSON-encoded), `raw_body` + `content_type` (tarballs for
`/build`), `params` (query string), `headers` (extra request headers),
`on_event`/`on_frame`/`on_chunk` (streaming callbacks, see below).
`_request` prefixes the path with `/v$api_version`. `around _request` in
`API::Docker` triggers `negotiate_version` on the first call that is not
`/version` â so a mock that replaces `_request` must strip the `/vX.YZ` prefix
itself, which `Test::API::Docker::Mock` does.
## Invariants
- **`list` and `inspect` return generated `API::Docker::Type::*` objects**
(via `_wrap`/`_wrap_list`); everything else returns the raw daemon response.
`Networks`, `Volumes`, `Plugins`, `Secrets` and `Configs` answer both calls
with one class (one swagger definition each â `API::Docker::Type::Network`,
etc.); `Containers` and `Images` have two each â `ContainerSummary` /
`ContainerInspectResponse`, `ImageSummary` / `ImageInspect` (see
`API::Docker::API::Containers/"The two container shapes"`). Which resources
have one class vs. two is read off `spec/v1.51.yaml`, not assumed â a future
swagger could add a second definition to a resource that only has one today.
- **The seven hand-written entity classes are gone (k84)** â
`API::Docker::{Container,Image,Network,Volume,Plugin,Secret,Config}`. The
files still ship, but only as stubs that croak on load and on every method
call (k92), so installing a new release overwrites a stale copy instead of
letting it shadow the release. Never write code against them or treat their
POD as current; the objects the daemon answers with are the
`API::Docker::Type::*` classes above.
- **The composed `client` on an entity is a `weak_ref`**, declared by
`API::Docker::Role::Entity` and composed into every wrapped
`API::Docker::Type::*` alongside its resource-specific
`API::Docker::Role::Entity::*` role. `API::Docker->new->images->list` leaves
every entity with `client => undef`, and the next `$image->remove` dies on an
undefined invocant. The client must stay in a live variable â in library
code, in examples, and in tests.
- **Query-string booleans are normalised to `1`/`0`** (`$opts{all} ? 1 : 0`);
**JSON-body booleans are `\1`/`\0`** (see `Exec::start`), because the engine
type-checks the body but not the query string.
- **A `params` value that is a hashref is JSON-encoded automatically**, but
`filters` specifically goes through `API::Docker::Role::Filters`, which
normalises it into the map-of-string-to-array-of-string shape the engine
wants (wraps a bare scalar in an array, stringifies numbers, turns a JSON or
`\1`/`\0` boolean into `'true'`/`'false'`) and croaks on anything else â another
ref, `undef`, an empty string. Pass `filters => { dangling => ['true'] }` and
let the role do the rest; encoding it by hand double-encodes it.
- **Extra headers go through `headers =>`**, which strips CR/LF. Never
concatenate a header into the request string.
- `_uri_encode` deliberately leaves `/` and `:` raw so image names survive in
the path (`/images/library/nginx:1.25/push`).
- `sub push` and `sub kill` shadow Perl builtins inside their packages â that
is why `namespace::clean` is loaded; always call them as methods.
## Entities: generated types with composed methods, not hand-written classes
`_wrap`/`_wrap_list` build the object with `$class->from_data($data, client =>
$self->client)` â never `new`. A daemon response and a caller-built object are
different name spaces: `from_data` reads only the swagger's own wire names, so
an unrecognised key keeps its own spelling in `unknown_fields` instead of being
misread as an unrelated field's Perl name, and a value that disagrees with the
declared type costs that one field (recorded in `rejected_fields`) instead of
failing the whole response. `new` stays strict and croaks on both â it is what
a caller's own arguments go through. Detail: `API::Docker::Role::Type`.
The convenience methods (`$container->start`, `$image->remove`, `logs`,
`is_running`, ...) are not on the generated classes. They live in
`API::Docker::Role::Entity::*` roles, composed onto the generated
`API::Docker::Type::*` classes at load time
(`Moo::Role->apply_roles_to_package`) â nothing hand-written can live in a
generated file, because it must match `maint/spec-to-type.pl`'s output byte for
byte (`t/spec_to_type.t` enforces it). See `API::Docker::Role::Entity` for why
a role composed onto the class, and not a wrapper class holding one.
Fields carry the swagger's own names in snake_case â `$container->state`, not
`$container->State` â and the model does normalise: a field declared `Bool`
comes back `1`/`0` whatever the daemon sent (measured on `Plugin.enabled`), and
`TO_JSON` writes it back out as a JSON boolean, not the Perl truth value.
## X-Registry-Auth â padded base64url, always sent
The engine requires the header on **every** push, anonymous included, and
decodes it with Go's `base64.URLEncoding`, which **requires the padding**.
Stripping the `=` made every push fail with `failed to parse "X-Registry-Auth"
header ... unexpected EOF` â the anonymous payload `{}` encodes to `e30=`, three
characters and one pad. `_registry_auth_header` produces padded base64url
(`tr{+/}{-_}`, no `=` removal); a bare base64-looking string passed as `auth`
is forwarded untouched.
## Transport behavior that's easy to get wrong
- **Without a callback the whole response is buffered.** Every request sends
`Connection: close`; with none of `on_event`, `on_frame`, `on_chunk` given,
`_request` reads the whole response before parsing â so `/build`,
`/images/create`, `/push`, `/events`, `/containers/*/stats` and `logs(follow)`
block until the daemon closes the connection (rule: `api-docker-hazards`;
detail: `API::Docker::Role::HTTP`'s "Streaming a response as it arrives").
- **The buffered streaming return type is not stable.** `_request` first tries
`decode_json` on the whole body and only falls back to line-by-line NDJSON
parsing (returning an arrayref of events). A stream carrying exactly one JSON
object comes back as that hashref, not a one-element array â callers check
`ref` before iterating.
- **A failed build/pull/push is still HTTP 200.** `_request` croaks on status
>= 400 only; `errorDetail` inside the event stream is the caller's job.
- **TLS is implemented, not stubbed.** `tls => 1` on a `tcp://` connection
(`unix://` never encrypts, and refuses the combination outright) swaps in
`IO::Socket::SSL` in place of the plain socket â same reader, same writer,
same everything above it. `cert_path` names a directory in the `docker`
CLI's own layout (`ca.pem` trust anchor, `cert.pem`+`key.pem` this client's
identity), defaulting from `$ENV{DOCKER_CERT_PATH}`; `tls_insecure => 1`
turns verification off. `IO::Socket::SSL` is a recommended, not required,
dependency, loaded only once a TLS connection is opened. Detail:
`API::Docker::Role::HTTP`'s "TLS on a tcp:// connection".
- **No connection reuse.** Each `_request` calls `_reconnect` and closes
afterwards, streamed or not.
## Tests â `Test::API::Docker::Mock`
`test_docker('GET /images/json' => $fixture_or_coderef, ...)` returns a client
whose `_request` dispatches against the route table (exact key first, then the
key matched as a literal path -- it is `\Q..\E`-escaped, not a regex, so a
metacharacter in a route key means itself). A `GET /version` route is injected
when none is given.
**In live mode `test_docker` ignores the routes entirely** and returns a real
client against `$ENV{API_DOCKER_TEST_HOST}`. An assertion that only holds for
the fixture must sit behind `is_live()`; mutating tests behind `can_write()` /
`skip_unless_write()`, with `register_cleanup` for anything they create.
Fixtures in `t/fixtures/*.json` are captured from a real daemon, so drift stays
detectable â do not hand-roll them. How they were captured is in `api-docker-hazards`.
**A test helper that repairs its input cannot see the defect.** The push-auth
test used to append the missing base64 padding before decoding, so it passed
with and against the bug it existed to catch. Decode exactly what the engine
would receive.
Canonical run: `prove -lr t/` (recursive â plain `prove -l t/` would silently
skip a future subdirectory). Single file: `prove -lv t/images.t`.
## Related
- engine wire formats, response shapes, filters, registry auth â `docker-engine-api`
- traps around the engine, the live tests and the build â `api-docker-hazards`
- the generated model, the DSL, the drift checker â `api-docker-type-model`
- house style, `$VERSION`, cpanfile pinning â `getty-perl-core`, `getty-perl-moo`; POD â `getty-perl-pod`
( run in 0.538 second using v1.01-cache-2.11-cpan-234fa220139 )