docker-api-ng 0.3.0

data/lib/docker/api/auth.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+require "English"
+
+module Docker
+  module API
+    # Registry credentials, resolved per call.
+    #
+    # There is no credential store on this module and no way to set one
+    # globally. Credentials are looked up for the registry a particular request
+    # is talking to and travel on that request as `X-Registry-Auth`, so pulling
+    # from two registries in one process needs no coordination.
+    module Auth
+      # Docker Hub's canonical auth key, which is not the hostname you pull from.
+      DOCKER_HUB_KEY = "https://index.docker.io/v1/"
+
+      module_function
+
+      # Find credentials for a registry and encode them for the daemon.
+      #
+      # Every failure mode here is soft. A missing config file, an unreadable
+      # one, or a credential helper that is not installed all mean "no
+      # credentials", because anonymous pulls of public images must keep
+      # working on a machine that has never run `docker login`.
+      #
+      # @param registry [String, nil] a registry hostname, or nil for Docker Hub
+      # @param config_path [String, nil] path to config.json, for tests
+      # @return [String, nil] a base64 `X-Registry-Auth` value, or nil
+      def resolve(registry = nil, config_path: nil)
+        key = registry_key(registry)
+        config = read_config(config_path)
+        return nil if config.nil?
+
+        credentials = from_helper(config, key) || from_auths(config, key)
+        return nil if credentials.nil?
+
+        encode(credentials)
+      end
+
+      # Encode a credential hash the way the daemon expects it: base64url of a
+      # JSON document, in a header.
+      #
+      # Encoded with pack rather than with the base64 library, deliberately.
+      # `base64` stopped being a default gem in Ruby 3.4, so requiring it makes
+      # this a gem with a runtime dependency it does not declare -- which fails
+      # at `require` time for anyone whose bundle does not happen to carry it
+      # for another reason. `pack("m0")` is the same transform with no
+      # newlines, and tr maps the standard alphabet onto the URL-safe one the
+      # daemon expects.
+      #
+      # @param credentials [Hash] with :username, :password, :serveraddress
+      # @return [String]
+      def encode(credentials)
+        [JSON.generate(credentials)].pack("m0").tr("+/", "-_")
+      end
+
+      # Docker Hub is stored under a URL key rather than its hostname, and an
+      # empty registry means Hub. Everything else is keyed by hostname.
+      #
+      # @param registry [String, nil]
+      # @return [String]
+      def registry_key(registry)
+        return DOCKER_HUB_KEY if registry.nil? || registry.empty?
+        return DOCKER_HUB_KEY if ["docker.io", "index.docker.io", "registry-1.docker.io"].include?(registry)
+
+        registry
+      end
+
+      # @param path [String, nil]
+      # @return [Hash, nil]
+      def read_config(path)
+        path ||= File.join(Dir.home, ".docker", "config.json")
+        return nil unless File.readable?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError, SystemCallError, ArgumentError
+        nil
+      end
+
+      # @param config [Hash]
+      # @param key [String]
+      # @return [Hash, nil]
+      def from_auths(config, key)
+        entry = config.dig("auths", key)
+        return nil if entry.nil?
+
+        if entry["auth"] && !entry["auth"].empty?
+          # unpack1("m") is Base64.decode64: lenient, ignoring newlines and
+          # any character outside the alphabet, which is what these values
+          # arrive as when a config.json has been hand-edited or line-wrapped.
+          username, _, password = entry["auth"].unpack1("m").partition(":")
+          return { username: username, password: password, serveraddress: key }
+        end
+
+        return nil if entry["username"].nil?
+
+        { username: entry["username"], password: entry["password"], serveraddress: key }
+      end
+
+      # A helper named for this specific registry wins over the catch-all
+      # store, which is how `credHelpers` is specified to behave.
+      #
+      # @param config [Hash]
+      # @param key [String]
+      # @return [Hash, nil]
+      def from_helper(config, key)
+        helper = config.dig("credHelpers", key) ||
+          config.dig("credHelpers", URI(key).host.to_s) ||
+          config["credsStore"]
+        return nil if helper.nil? || helper.empty?
+
+        run_helper(helper, key)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      # Invoke `docker-credential-<helper> get`, which reads the registry on
+      # stdin and writes JSON on stdout.
+      #
+      # The command is passed as an argument array, never a shell string, so a
+      # helper name from a config file cannot become a shell injection.
+      #
+      # @param helper [String] the helper's short name
+      # @param key [String] the registry to ask about
+      # @return [Hash, nil]
+      def run_helper(helper, key)
+        output = IO.popen(["docker-credential-#{helper}", "get"], "r+") do |io|
+          io.write(key)
+          io.close_write
+          io.read
+        end
+        return nil unless $CHILD_STATUS.nil? || $CHILD_STATUS.success?
+
+        parsed = JSON.parse(output.to_s)
+        secret = parsed["Secret"]
+        return nil if secret.nil? || secret.empty?
+
+        # A username of <token> is the helper's way of saying the secret is an
+        # identity token rather than a password.
+        if parsed["Username"] == "<token>"
+          { identitytoken: secret, serveraddress: parsed["ServerURL"] || key }
+        else
+          { username: parsed["Username"], password: secret,
+            serveraddress: parsed["ServerURL"] || key }
+        end
+      rescue Errno::ENOENT, Errno::EACCES, JSON::ParserError, IOError
+        nil
+      end
+    end
+  end
+end

data/lib/docker/api/body.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Builds request bodies without making callers shout in PascalCase.
+    module Body
+      module_function
+
+      # Convert top-level snake_case keys to the PascalCase the daemon uses.
+      #
+      # Only the top level is converted, deliberately. Nested structures are
+      # passed through exactly as given, because their keys are frequently data
+      # rather than field names -- `Labels`, `ExposedPorts`, `PortBindings` and
+      # `Sysctls` are all maps whose keys belong to the user. A recursive
+      # converter would mangle `{ "com.example/team" => "infra" }` into
+      # something the daemon has never heard of.
+      #
+      # Keys that already look like the daemon's own are left alone, so a body
+      # copied verbatim out of Docker's documentation keeps working.
+      #
+      # @param attributes [Hash] a body in either convention
+      # @return [Hash] a body in the daemon's convention
+      #
+      # @example
+      #   Body.build(image: "alpine", host_config: { "Binds" => ["/a:/b"] })
+      #   #=> { "Image" => "alpine", "HostConfig" => { "Binds" => ["/a:/b"] } }
+      def build(attributes)
+        (attributes || {}).each_with_object({}) do |(key, value), out|
+          out[camelize(key)] = value unless value.nil?
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @return [String] the daemon's spelling of a field name
+      def camelize(key)
+        name = key.to_s
+        # Already PascalCase, or a literal the caller means verbatim.
+        return name if name.match?(/\A[A-Z]/)
+
+        name.split("_").map { |part| part.sub(/\A(.)/) { Regexp.last_match(1).upcase } }.join
+      end
+    end
+  end
+end

data/lib/docker/api/client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # A connection to one Docker daemon, and the way in to everything else.
+    #
+    # A client owns its configuration and its connection. There is no global
+    # state behind it: two clients addressing two daemons share nothing, so a
+    # process can talk to a local daemon and a remote builder at the same time
+    # without either one noticing.
+    #
+    # @example The local daemon
+    #   client = Docker::API::Client.new
+    #   client.system.info["ServerVersion"]
+    #
+    # @example A remote daemon over TLS
+    #   client = Docker::API::Client.new(
+    #     url: "tcp://build.internal:2376",
+    #     tls: { ca_file: "ca.pem", cert_file: "cert.pem", key_file: "key.pem" }
+    #   )
+    #
+    # @example Reaching an endpoint with no ergonomic wrapper
+    #   client.operations.container_prune(filters: { "until" => ["24h"] })
+    class Client
+      # @return [Docker::API::Config] this client's frozen configuration
+      attr_reader :config
+
+      # @return [Docker::API::Connection] the connection in use
+      attr_reader :connection
+
+      # @param url [String, nil] the daemon URL. Falls back to `DOCKER_HOST`,
+      #   then to the platform's default socket.
+      # @param tls [Hash, nil] TLS material: `:ca_file`, `:cert_file`,
+      #   `:key_file`, `:verify`. Falls back to `DOCKER_CERT_PATH`.
+      # @param api_version [String, Symbol] `:negotiate` to ask the daemon what
+      #   it speaks, a version such as `"1.44"` to pin, or `:none` to send
+      #   unprefixed paths
+      # @param logger [Logger, nil] receives one debug line per request
+      # @param read_timeout [Numeric] seconds to wait for response data
+      # @param open_timeout [Numeric] seconds to wait for a connection
+      # @param transport [Docker::API::Transport::Base, nil] a transport to use
+      #   instead of building one from the URL. Mainly for tests, where
+      #   {Docker::API::Transport::Fake} stands in for a daemon.
+      # @param env [Hash] the environment to resolve defaults from
+      def initialize(url: nil, tls: nil, api_version: :negotiate, logger: nil,
+        read_timeout: 60, open_timeout: 10, transport: nil, env: ENV)
+        @config = Config.from_env(
+          env,
+          url: url, api_version: api_version,
+          read_timeout: read_timeout, open_timeout: open_timeout,
+          **(tls.nil? ? {} : { tls: tls })
+        )
+
+        @connection = Connection.new(
+          transport: transport || Transport.for(
+            url: config.url, tls: config.tls, open_timeout: config.open_timeout
+          ),
+          api_version: config.api_version,
+          logger: logger,
+          read_timeout: config.read_timeout,
+          open_timeout: config.open_timeout
+        )
+      end
+
+      # Every Engine API operation, one method each.
+      #
+      # This is public API rather than an escape hatch. The ergonomic
+      # collections below cover what most code needs; anything they have not
+      # grown sugar for is reachable here, fully documented and typed, with no
+      # loss of capability.
+      #
+      # @return [Docker::API::Operations]
+      def operations
+        @operations ||= Operations.new(connection)
+      end
+
+      # @return [Docker::API::Containers]
+      def containers
+        @containers ||= Containers.new(self)
+      end
+
+      # @return [Docker::API::Images]
+      def images
+        @images ||= Images.new(self)
+      end
+
+      # @return [Docker::API::Networks]
+      def networks
+        @networks ||= Networks.new(self)
+      end
+
+      # @return [Docker::API::Volumes]
+      def volumes
+        @volumes ||= Volumes.new(self)
+      end
+
+      # @return [Docker::API::System]
+      def system
+        @system ||= System.new(self)
+      end
+
+      # @return [String, nil] the negotiated Engine API version
+      def api_version
+        connection.api_version
+      end
+
+      # @return [String]
+      def to_s
+        "#<Docker::API::Client url=#{config.url}>"
+      end
+      alias_method :inspect, :to_s
+    end
+  end
+end

data/lib/docker/api/collection.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Shared behaviour for the collections hanging off a {Docker::API::Client}.
+    #
+    # Collections are thin by design: each method is one call into the
+    # generated operations layer plus whatever wrapping makes the result
+    # pleasant. Keeping them thin is what stops the ergonomic layer from
+    # drifting away from the API it is supposed to be sugar for.
+    #
+    # @abstract
+    class Collection
+      # @return [Docker::API::Client] the client this collection belongs to
+      attr_reader :client
+
+      # @param client [Docker::API::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      # Fetch one object, or nil if the daemon has never heard of it.
+      #
+      # The distinction from `get` is deliberate. Asking for something by a
+      # name a user typed is a question; asking for something you just created
+      # is an assertion. `find` answers the question, `get` makes the
+      # assertion and raises when it turns out to be false.
+      #
+      # @param id [String] a name or id
+      # @return [Docker::API::Resource, nil]
+      def find(id)
+        get(id)
+      rescue NotFound
+        nil
+      end
+
+      # @param id [String] a name or id
+      # @return [Boolean] whether the object exists
+      def exist?(id)
+        !find(id).nil?
+      end
+
+      # @return [String]
+      def to_s
+        "#<#{self.class.name}>"
+      end
+      alias_method :inspect, :to_s
+
+      private
+
+      # @return [Docker::API::Operations]
+      def operations
+        client.operations
+      end
+    end
+  end
+end

data/lib/docker/api/collections/containers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The containers on a daemon.
+    #
+    # @example
+    #   client.containers.all(all: true)
+    #   client.containers.create(image: "alpine:3.20", name: "scratch", cmd: %w{sleep 30})
+    class Containers < Collection
+      # List containers.
+      #
+      # @param all [Boolean] include containers that are not running
+      # @param limit [Integer, nil] return only the most recent N
+      # @param size [Boolean] include the filesystem size of each
+      # @param filters [Hash, nil] daemon-side filters, e.g. `{ "status" => ["running"] }`
+      # @return [Array<Docker::API::Container>] partial resources; accessors
+      #   that need detail the list did not carry will fetch it
+      def all(all: false, limit: nil, size: false, filters: nil)
+        operations.container_list(all: all, limit: limit, size: size, filters: filters)
+          .json!.map { |payload| Container.new(client: client, raw: payload, partial: true) }
+      end
+
+      # Fetch one container.
+      #
+      # @param id [String] a name or id
+      # @param size [Boolean] include filesystem size information
+      # @return [Docker::API::Container]
+      # @raise [Docker::API::NotFound] if there is no such container
+      def get(id, size: false)
+        Container.new(
+          client: client,
+          raw: operations.container_inspect(id: id, size: size).json,
+          partial: false
+        )
+      end
+
+      # Create a container.
+      #
+      # Body attributes may be given in snake_case and are converted to the
+      # daemon's spelling; keys already in the daemon's convention are passed
+      # through untouched, so a configuration copied out of Docker's own
+      # documentation works as-is. Only top-level keys are converted -- nested
+      # maps such as `Labels` and `PortBindings` have keys that are data.
+      #
+      # @param name [String, nil] a name for the container
+      # @param platform [String, nil] "os[/arch[/variant]]" to create for
+      # @param attributes [Hash] the container configuration
+      # @return [Docker::API::Container]
+      #
+      # @example
+      #   client.containers.create(
+      #     image: "alpine:3.20",
+      #     name: "worker",
+      #     cmd: %w{sleep 3600},
+      #     env: ["LOG_LEVEL=debug"],
+      #     host_config: { "Binds" => ["/data:/data:ro"] }
+      #   )
+      def create(name: nil, platform: nil, **attributes)
+        response = operations.container_create(
+          body: Body.build(attributes), name: name, platform: platform
+        )
+        get(response.json!["Id"])
+      end
+
+      # Remove stopped containers.
+      #
+      # @param filters [Hash, nil] which containers to consider
+      # @return [Hash] what was deleted and how much space it freed
+      def prune(filters: nil)
+        operations.container_prune(filters: filters).json
+      end
+    end
+  end
+end

data/lib/docker/api/collections/images.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The images on a daemon.
+    #
+    # @example
+    #   client.images.pull("alpine:3.20", platform: "linux/arm64")
+    #   client.images.build(context: "./app", tag: "app:dev")
+    class Images < Collection
+      # List images.
+      #
+      # @param all [Boolean] include intermediate layers
+      # @param filters [Hash, nil] daemon-side filters
+      # @param digests [Boolean] include repository digests
+      # @return [Array<Docker::API::Image>] partial resources
+      def all(all: false, filters: nil, digests: false)
+        operations.image_list(all: all, filters: filters, digests: digests)
+          .json!.map { |payload| Image.new(client: client, raw: payload, partial: true) }
+      end
+
+      # Fetch one image.
+      #
+      # @param name [String] a reference, id or digest
+      # @param platform [String, Hash, nil] which platform's image to describe,
+      #   as "linux/arm64" or an OCI platform hash
+      # @return [Docker::API::Image]
+      # @raise [Docker::API::NotFound] if there is no such image
+      def get(name, platform: nil)
+        Image.new(
+          client: client,
+          # This endpoint wants the OCI object form, unlike pull and build,
+          # which want the string. See Docker::API::Platform.
+          raw: operations.image_inspect(name: name, platform: Platform.oci(platform)).json,
+          partial: false
+        )
+      end
+
+      # Whether an image is present locally.
+      #
+      # @param name [String] a reference, id or digest
+      # @param platform [String, nil] which platform to ask about
+      # @return [Boolean]
+      def exist?(name, platform: nil)
+        !get(name, platform: platform).nil?
+      rescue NotFound
+        false
+      end
+
+      # Fetch an image, pulling it first if the daemon does not have it.
+      #
+      # @param reference [String] the image to ensure is present
+      # @param platform [String, Hash, nil] the platform to select or pull
+      # @param auth [String, nil] an X-Registry-Auth value
+      # @yieldparam event [Hash] pull progress, when a pull is needed
+      # @return [Docker::API::Image]
+      def ensure(reference, platform: nil, auth: nil, &block)
+        get(reference, platform: platform)
+      rescue NotFound
+        pull(reference, platform: platform, auth: auth, &block)
+      end
+
+      # Pull an image from a registry.
+      #
+      # Credentials are resolved for the registry in the reference, so pulling
+      # from two private registries in one process needs no setup between
+      # calls. Pass `auth:` to override.
+      #
+      # @param reference [String] "alpine:3.20", "registry.io/team/app:1.0"
+      # @param platform [String, Hash, nil] the platform to pull, as
+      #   "linux/arm64" or an OCI platform hash
+      # @param auth [String, nil] an X-Registry-Auth value
+      # @yieldparam event [Hash] progress events as they arrive
+      # @return [Docker::API::Image]
+      #
+      # @example Watching progress
+      #   client.images.pull("alpine:3.20") { |event| puts event["status"] }
+      def pull(reference, platform: nil, auth: nil, &block)
+        repo, tag = Image.split_reference(reference)
+        credentials = auth || Auth.resolve(Image.registry_for(repo))
+
+        stream = block ? Stream::JSONLines.new(&block) : nil
+        # Pull wants the string form; inspect below wants the object form.
+        operations.image_create(
+          from_image: repo, tag: tag, platform: Platform.string(platform),
+          x_registry_auth: credentials
+        ) { |chunk| stream << chunk if stream }
+
+        # Reassembled rather than reusing the caller's string, because the tag
+        # may have been defaulted to "latest" along the way -- and because a
+        # digest has to go back together with "@" rather than ":".
+        get(Image.join_reference(repo, tag), platform: platform)
+      end
+
+      # Build an image.
+      #
+      # The context may be a directory, which is tarred honouring its
+      # .dockerignore, or a Dockerfile given as a string for the common case of
+      # a short generated build with no accompanying files.
+      #
+      # @param context [String, IO, nil] a directory path, or tar bytes
+      # @param dockerfile [String, nil] Dockerfile contents, when there is no
+      #   directory, or the name of the Dockerfile within the context
+      # @param tag [String, nil] the reference to give the result
+      # @param platform [String, Hash, nil] the platform to build for
+      # @param nocache [Boolean] ignore the layer cache
+      # @param rm [Boolean] remove intermediate containers
+      # @param pull [Boolean] always re-pull the base image
+      # @param buildargs [Hash, nil] --build-arg values
+      # @param labels [Hash, nil] labels for the resulting image
+      # @param target [String, nil] which stage of a multi-stage build to stop at
+      # @yieldparam event [Hash] build output as it arrives
+      # @return [Docker::API::Image]
+      # @raise [Docker::API::Error] if the daemon reports a build failure
+      #
+      # @example Building from a directory
+      #   client.images.build(context: "./app", tag: "app:dev") do |event|
+      #     print event["stream"]
+      #   end
+      #
+      # @example Building from a Dockerfile in memory
+      #   client.images.build(dockerfile: "FROM alpine\nRUN apk add curl\n", tag: "curl:dev")
+      def build(context: nil, dockerfile: nil, tag: nil, platform: nil, nocache: false,
+        rm: true, pull: false, buildargs: nil, labels: nil, target: nil, &block)
+        archive, dockerfile_name = build_context(context, dockerfile)
+        image_id = nil
+        failure = nil
+
+        stream = Stream::JSONLines.new do |event|
+          image_id ||= event.dig("aux", "ID")
+          failure ||= event["error"]
+          block&.call(event)
+        end
+
+        operations.image_build(
+          body: archive, content_type: "application/x-tar",
+          t: tag, platform: Platform.string(platform), nocache: nocache, rm: rm, pull: pull,
+          dockerfile: dockerfile_name, target: target,
+          buildargs: buildargs, labels: labels
+        ) { |chunk| stream << chunk }
+
+        # The daemon reports build failures inside a 200 response rather than
+        # as a status code, so a build that failed looks like a success to
+        # anything that only checks HTTP.
+        raise Error.new("image build failed: #{failure}", operation: "image_build") if failure
+
+        get(built_reference(tag, image_id))
+      end
+
+      # Remove unused images.
+      #
+      # @param filters [Hash, nil] which images to consider
+      # @return [Hash] what was deleted and how much space it freed
+      def prune(filters: nil)
+        operations.image_prune(filters: filters).json
+      end
+
+      # Search Docker Hub.
+      #
+      # @param term [String] what to search for
+      # @param limit [Integer, nil] how many results to return
+      # @param filters [Hash, nil] search filters
+      # @return [Array<Hash>]
+      def search(term, limit: nil, filters: nil)
+        operations.image_search(term: term, limit: limit, filters: filters).json
+      end
+
+      private
+
+      # What to inspect once a build has finished.
+      #
+      # A tag is the reliable answer. The image id only turns up if the daemon
+      # emitted an `aux.ID` event, which the classic builder does and BuildKit
+      # does not always -- so an untagged build could reach here with neither,
+      # and `get(nil)` asked the daemon for `GET /v1.55/images//json`. That
+      # comes back as a 404 about a missing image, which points at everything
+      # except the actual problem.
+      #
+      # @param tag [String, nil]
+      # @param image_id [String, nil]
+      # @return [String]
+      # @raise [Docker::API::Error]
+      def built_reference(tag, image_id)
+        reference = tag || image_id
+        return reference if reference
+
+        raise Error.new(
+          "the build succeeded but produced nothing to look up: no tag: was given and the " \
+          "daemon reported no image id. Pass tag: to name the result, which BuildKit needs " \
+          "in order to report one.",
+          operation: "image_build"
+        )
+      end
+
+      # @return [Array(IO, String, nil)] the archive and the Dockerfile name
+      def build_context(context, dockerfile)
+        return [Tar.pack_dockerfile(dockerfile), "Dockerfile"] if context.nil? && dockerfile
+
+        raise ArgumentError, "build needs a context: or a dockerfile:" if context.nil?
+        return [context, dockerfile] unless context.is_a?(String) && File.directory?(context)
+
+        # dockerfile: means two different things depending on whether there is
+        # a context, and getting them the wrong way round is silent: the whole
+        # Dockerfile source goes out as the `dockerfile=` query parameter, and
+        # the daemon simply reports that it cannot find that file. A newline is
+        # the tell -- a filename inside a build context does not contain one.
+        if dockerfile.is_a?(String) && dockerfile.include?("\n")
+          raise ArgumentError,
+            "dockerfile: names a file inside context: -- it looks like you passed the file's " \
+            "contents. Drop context: to build from a Dockerfile given inline, or pass the name " \
+            "of a Dockerfile within #{context.inspect}."
+        end
+
+        [Tar.pack_directory(context), dockerfile]
+      end
+    end
+  end
+end