docker-api-ng 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b5f85c245e02ac2d11b5225e5a89b49b4a9ec9bfd2631e44536cb3c57322538
+  data.tar.gz: b6256d3d50edc2ae22b6402959b8480e5f9f36ac4b6ea1901030f82bc4306550
+SHA512:
+  metadata.gz: 57dc554cbea32034ba42e6d76b565d4fa1dcf5fc145aa3471a091caf233e57d407e80d3fb0fff99f934f3e94fe7f3ada0d539cbdf876fa47eece895b4237f089
+  data.tar.gz: d5e3feab0727f4528cb036681753389c8d9c3463939ad2614821bab65a9bea20d1138a77d6209865446fb3f40e3fb14b5efcbf189e7f35a407c0b4c5062b09cc

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/NOTICE

@@ -0,0 +1,12 @@
+docker-api-ng
+Copyright 2026 Tim Smith
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+This product includes a vendored copy of the Docker Engine API
+specification (data/swagger/), which is part of the Moby Project and is
+licensed under the Apache License, Version 2.0.

data/README.md

@@ -0,0 +1,278 @@
+# docker-api-ng
+
+A Ruby client for the modern Docker Engine API.
+
+- **No runtime dependencies.** Everything it needs ships with Ruby.
+- **Complete API coverage, by construction.** All 108 Engine API operations are
+  generated from Docker's own OpenAPI specification, so nothing is missing and
+  keeping up with Docker is a reviewable diff rather than manual archaeology.
+- **An ergonomic layer on top.** Collections and resource objects for the things
+  you touch every day, with the generated layer underneath whenever you need
+  something it has not grown sugar for.
+- **Testable without a daemon.** The whole client can be driven by a scripted
+  transport, so tests are fast, hermetic and honest.
+
+```ruby
+require "docker/api"
+
+client = Docker::API::Client.new
+
+client.images.pull("alpine:3.20")
+container = client.containers.create(image: "alpine:3.20", name: "hello", cmd: %w{sleep 60})
+container.start
+
+result = container.exec(%w{cat /etc/alpine-release})
+result.stdout   #=> "3.20.3\n"
+result.exit_code #=> 0
+
+container.remove(force: true)
+```
+
+## Installation
+
+```ruby
+gem "docker-api-ng"
+```
+
+Requires Ruby 3.1 or newer and a daemon speaking Engine API v1.41 or newer
+(Docker 20.10+).
+
+## Connecting
+
+With no arguments, a client resolves its daemon the way the `docker` CLI does:
+`DOCKER_HOST`, then the active Docker context (`DOCKER_CONTEXT`, then
+`currentContext` in `~/.docker/config.json`), falling back to the platform's
+default socket. TLS material comes from `DOCKER_CERT_PATH` and
+`DOCKER_TLS_VERIFY`, or from the context itself.
+
+```ruby
+client = Docker::API::Client.new
+
+client = Docker::API::Client.new(url: "unix:///var/run/docker.sock")
+client = Docker::API::Client.new(url: "npipe:////./pipe/docker_engine")   # Windows
+client = Docker::API::Client.new(
+  url: "tcp://build.internal:2376",
+  tls: { ca_file: "ca.pem", cert_file: "cert.pem", key_file: "key.pem" }
+)
+```
+
+A client owns its configuration and its connection, and there is no global
+state behind it. Two clients talking to two daemons share nothing:
+
+```ruby
+local = Docker::API::Client.new
+build = Docker::API::Client.new(url: "tcp://build.internal:2376")
+```
+
+See [docs/connecting.md](docs/connecting.md) for version negotiation, timeouts,
+logging and TLS in detail.
+
+## Containers
+
+```ruby
+client.containers.all(all: true)          # => [Container]
+client.containers.get("web")              # => Container, raises NotFound
+client.containers.find("web")             # => Container or nil
+
+container = client.containers.create(
+  image: "alpine:3.20",
+  name: "worker",
+  cmd: %w{sleep 3600},
+  env: ["LOG_LEVEL=debug"],
+  host_config: { "Binds" => ["/data:/data:ro"] }
+)
+
+container.start
+container.stop(timeout: 10)
+container.remove(force: true, volumes: true)
+```
+
+Body attributes may be written in snake_case and are translated to the daemon's
+spelling. Keys already in Docker's convention pass through untouched, so a
+configuration copied out of Docker's documentation works as-is.
+
+### Resources answer the same question the same way
+
+`GET /containers/json` reports `Names: ["/web"]`. `GET /containers/{id}/json`
+reports `Name: "/web"`. Resources here normalise that, so code does not have to
+know which call produced the object it is holding:
+
+```ruby
+listed    = client.containers.all.first    # from a list
+inspected = client.containers.get("web")   # from an inspect
+
+listed.name    == inspected.name    # => true
+listed.state   == inspected.state   # => true
+listed.ports   == inspected.ports   # => true
+```
+
+An object built from a list marks itself `partial?`. The first accessor that
+needs detail the list did not carry fetches it once, rather than returning nil
+and leaving you to guess why. The untouched payload is always available as
+`#raw`.
+
+## Running commands
+
+```ruby
+result = container.exec(%w{chef-client -z}, env: { "TERM" => "xterm" }) do |stream, chunk|
+  logger << chunk if stream == :stdout
+end
+
+result.stdout
+result.stderr
+result.exit_code
+result.success?
+```
+
+Without a TTY the daemon multiplexes both streams down one connection with an
+eight-byte frame header. That is decoded for you, so `:stdout` and `:stderr`
+arrive separately instead of interleaved. A non-zero exit is returned rather
+than raised — whether a failing command is an error depends on why you ran it.
+Use `result.check!` when it is.
+
+## Images
+
+```ruby
+client.images.pull("alpine:3.20", platform: "linux/arm64") { |event| puts event["status"] }
+client.images.build(context: "./app", tag: "app:dev") { |event| print event["stream"] }
+client.images.build(dockerfile: "FROM alpine\nRUN apk add curl\n", tag: "curl:dev")
+client.images.ensure("alpine:3.20")   # pull only if absent
+```
+
+Registry credentials are resolved per call from `~/.docker/config.json`,
+including `credsStore` and `credHelpers`, so pulling from two private
+registries in one process needs no setup between calls.
+
+## Networks and volumes
+
+```ruby
+network = client.networks.ensure("dokken", ipv6: true)
+network.connect(container, aliases: %w{web})
+network.disconnect(container)
+
+volume = client.volumes.create("cache", labels: { "team" => "infra" })
+volume.remove
+```
+
+`ensure` treats losing a creation race as success, because two processes
+racing to create the same shared network is ordinary rather than exceptional.
+
+## The daemon itself
+
+```ruby
+client.system.info
+client.system.version
+client.system.ping?      # => true / false, never raises
+client.system.podman?    # Podman wearing Docker's API
+client.system.rootless?
+
+client.system.events(filters: { "type" => ["container"] }) do |event|
+  puts "#{event["Action"]} #{event.dig("Actor", "Attributes", "name")}"
+end
+```
+
+## Everything else
+
+The generated layer is public API, not an escape hatch. Every one of the 108
+Engine API operations is there, documented, typed, and named after the
+specification's own `operationId`:
+
+```ruby
+client.operations.container_prune(filters: { "until" => ["24h"] })
+client.operations.swarm_init(body: { "ListenAddr" => "0.0.0.0:2377" })
+client.operations.service_list(filters: { "name" => ["web"] })
+client.operations.node_list
+client.operations.secret_create(body: { "Name" => "token", "Data" => encoded })
+client.operations.plugin_list
+```
+
+The ergonomic collections above cover what most code reaches for. Anything they
+have not grown sugar for is reachable here with no loss of capability, and the
+list of ergonomic wrappers grows over time without ever being a coverage
+bottleneck.
+
+## Errors
+
+Everything this gem raises descends from `Docker::API::Error`, and nothing from
+beneath the abstraction escapes — no `Errno`, no `OpenSSL`, no `Net::` class
+reaches your rescue clause. The original is always kept as `#cause`.
+
+```ruby
+begin
+  client.containers.get("missing")
+rescue Docker::API::NotFound => e
+  e.operation  #=> "container_inspect"
+  e.status     #=> 404
+  e.message    #=> "container_inspect failed (HTTP 404): No such container: missing"
+rescue Docker::API::ConnectionError => e
+  e.cause      #=> #<Errno::ENOENT ...>
+end
+```
+
+See [docs/errors.md](docs/errors.md) for the full hierarchy.
+
+## Testing code that uses this gem
+
+`Docker::API::Transport::Fake` scripts a daemon over a real socket pair, so
+tests exercise the actual request path with no network and no daemon:
+
+```ruby
+fake = Docker::API::Transport::Fake.new([
+  "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: 26\r\n\r\n" \
+  '{"Id":"abc","Name":"/web"}',
+])
+client = Docker::API::Client.new(transport: fake, api_version: "1.55")
+
+client.containers.get("web").name  #=> "web"
+fake.requests.first                #=> "GET /v1.55/containers/web/json HTTP/1.1\r\n..."
+```
+
+The socket is genuine on purpose: `Net::BufferedIO` calls `read_nonblock`,
+`write` and `to_io` on whatever it is handed, and a StringIO does not honour
+that contract. Faking it produces tests that pass against something the real
+code could never drive.
+
+## How it stays current
+
+The API surface is generated from `data/swagger/v1.55.yaml`, a vendored copy of
+Docker's own specification:
+
+```console
+$ bundle exec rake api:sync[1.56]     # fetch a newer spec and regenerate
+$ git diff --stat                     # review what changed
+```
+
+A new endpoint appears as a new method. A removed parameter vanishes from the
+signature and the type checker names every caller that still passes it.
+Generated files are committed, so installing the gem needs no toolchain, and
+upgrading the supported API version is a pull request somebody reads.
+
+See [docs/extending.md](docs/extending.md).
+
+## Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Connecting](docs/connecting.md) | URLs, TLS, named pipes, version negotiation, timeouts, logging |
+| [Errors](docs/errors.md) | The hierarchy, what each one means, retrying |
+| [Running commands](docs/exec.md) | exec, attach, logs, stream multiplexing |
+| [Building images](docs/building-images.md) | Build contexts, .dockerignore, build args, registries |
+| [Streaming](docs/streaming.md) | The three wire formats and how they are decoded |
+| [Extending](docs/extending.md) | The generator, adding ergonomics, upgrading the API version |
+| [Migrating from docker-api](docs/migrating-from-docker-api.md) | A call-by-call table |
+
+## Relationship to the docker-api gem
+
+This is not a fork and keeps no compatibility with
+[docker-api](https://github.com/upserve/docker-api). It was written because a
+few of that gem's design decisions are difficult to work around from outside:
+process-global connection and credential state, hand-transcribed parameters
+that silently drop what they miss, `Excon` exceptions reaching callers, and no
+Windows named pipe support.
+
+Everything here lives under `Docker::API` and nothing is added to `::Docker`,
+so both gems can be loaded into one process while a migration is in progress.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

data/docker-api-ng.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/docker/api/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "docker-api-ng"
+  spec.version       = Docker::API::VERSION
+  spec.authors       = ["Tim Smith"]
+  spec.email         = ["tsmith84@proton.me"]
+  spec.summary       = "A Ruby client for the modern Docker Engine API"
+  spec.description   = <<~DESC
+    A dependency-free Ruby client for the Docker Engine API. The complete API
+    surface is generated from Docker's own OpenAPI specification, so keeping up
+    with the daemon is a reviewable diff rather than manual archaeology, and an
+    ergonomic hand-written layer sits on top of it.
+  DESC
+  spec.homepage      = "https://github.com/test-kitchen/docker-api-ng"
+  spec.license       = "Apache-2.0"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{spec.homepage}/blob/main/README.md",
+    "source_code_uri" => spec.homepage,
+  }
+
+  spec.required_ruby_version = ">= 3.1"
+
+  # data/swagger/*.yaml is deliberately not packaged. It is a build-time input:
+  # `rake api:generate` reads it to emit lib/docker/api/operations.rb, which is
+  # committed. Nothing loads the specification at runtime, and the generator
+  # that consumes it lives in tools/, which is not shipped either -- so packaging
+  # it added 471 KB, about four fifths of the gem, that no installed copy can
+  # use. It stays in the repository, where the generator and reviewers want it.
+  spec.files = %w{LICENSE NOTICE README.md docker-api-ng.gemspec} +
+    Dir.glob("lib/**/*.rb") +
+    Dir.glob("sig/**/*.rbs") +
+    Dir.glob("docs/*.md")
+  spec.require_paths = ["lib"]
+
+  # No runtime dependencies. Everything this gem needs ships with Ruby.
+end

data/docs/building-images.md

@@ -0,0 +1,98 @@
+# Building images
+
+## From a directory
+
+```ruby
+image = client.images.build(context: "./app", tag: "app:dev") do |event|
+  print event["stream"] if event["stream"]
+end
+```
+
+The directory is packed into a tar archive with `Gem::Package::TarWriter`,
+which ships with Ruby — no dependency, no shelling out to `tar`, and identical
+behaviour on Windows where there may be no `tar` to shell out to.
+
+`.dockerignore` is honoured, including `!` negations, where the last matching
+rule wins.
+
+## From a Dockerfile in memory
+
+For a short generated build with no accompanying files, writing a temporary
+directory first is ceremony for its own sake:
+
+```ruby
+client.images.build(
+  dockerfile: <<~DOCKERFILE,
+    FROM alpine:3.20
+    RUN apk add --no-cache curl
+  DOCKERFILE
+  tag: "curl:dev"
+)
+```
+
+## Options
+
+```ruby
+client.images.build(
+  context: "./app",
+  dockerfile: "Dockerfile.ci",           # a path within the context
+  tag: "app:ci",
+  platform: "linux/arm64",
+  buildargs: { "VERSION" => "2026.08" },
+  labels: { "team" => "infra" },
+  target: "runtime",                     # stop at a multi-stage stage
+  nocache: true,
+  pull: true,
+  rm: true
+)
+```
+
+## Build failures
+
+The daemon reports a failed build inside a `200` response, as an `error` key in
+the JSON-lines stream. Anything that only checks the HTTP status concludes the
+build succeeded and then fails confusingly later.
+
+`build` reads the stream and raises:
+
+```ruby
+begin
+  client.images.build(context: ".", tag: "app:dev")
+rescue Docker::API::Error => e
+  e.message  #=> "image build failed: The command '/bin/sh -c apk add nope' returned a non-zero code: 1"
+end
+```
+
+## Pulling
+
+```ruby
+client.images.pull("alpine:3.20")
+client.images.pull("ghcr.io/team/app:1.0", platform: "linux/arm64")
+client.images.ensure("alpine:3.20")     # pull only if it is not already here
+```
+
+Credentials are resolved for the registry in the reference, from
+`~/.docker/config.json`, including `credsStore` and `credHelpers`. Every
+failure in that lookup is soft: a missing config file, an unreadable one, or an
+uninstalled helper all mean "no credentials", because anonymous pulls of public
+images must keep working on a machine that has never run `docker login`.
+
+Pass `auth:` to override:
+
+```ruby
+credentials = Docker::API::Auth.encode(
+  username: "token", password: ENV.fetch("REGISTRY_TOKEN"), serveraddress: "ghcr.io"
+)
+client.images.pull("ghcr.io/team/app:1.0", auth: credentials)
+```
+
+## A note on `platform`
+
+The Engine API asks for platforms in two incompatible encodings depending on
+the endpoint. Build, pull and container-create want the string
+`"linux/arm64"`; inspect, push, history and save want a JSON-encoded OCI
+object. Sending the wrong one fails with
+`400 failed to parse platform: invalid character 'l'`.
+
+Write `"linux/arm64"` everywhere. `Docker::API::Platform` encodes whichever
+form the endpoint in question wants.