docker-api-ng 0.3.0

data/lib/docker/api/path.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Escaping for values interpolated into a request path.
+    module Path
+      # Characters that may appear unescaped in a path. This is RFC 3986's
+      # `pchar` set plus the separator itself.
+      #
+      # Keeping "/" and ":" unescaped is the point. Image references are
+      # `registry.example.com/team/image:tag`, and the daemon's router matches
+      # those slashes as path structure -- percent-encoding them turns a valid
+      # reference into a 404. Everything genuinely unsafe (spaces, "?", "#",
+      # "%") is still escaped.
+      SAFE = %r{[^A-Za-z0-9\-._~!$&'()*+,;=:@/]}
+
+      module_function
+
+      # @param value [Object] a value being interpolated into a path
+      # @return [String] the value, safe to place in a path
+      #
+      # @example
+      #   Path.escape("registry.io/team/img:1.0") #=> "registry.io/team/img:1.0"
+      #   Path.escape("weird name")               #=> "weird%20name"
+      def escape(value)
+        URI::DEFAULT_PARSER.escape(value.to_s, SAFE)
+      end
+    end
+  end
+end

data/lib/docker/api/platform.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Platform selectors, in the two encodings the Engine API uses for them.
+    #
+    # The API is not consistent here, and the inconsistency is silent. Some
+    # endpoints want the familiar string:
+    #
+    #   POST /containers/create?platform=linux/arm64
+    #   POST /build?platform=linux/arm64
+    #   POST /images/create?platform=linux/arm64
+    #
+    # while others want a JSON-encoded OCI platform object:
+    #
+    #   GET  /images/{name}/json?platform={"os":"linux","architecture":"arm64"}
+    #   POST /images/{name}/push?platform={"os":"linux","architecture":"arm64"}
+    #   GET  /images/{name}/history?platform={...}
+    #
+    # Sending the string where the object is expected fails with
+    # `400 failed to parse platform: invalid character 'l'`, which does not
+    # obviously mean "wrong encoding" to anyone reading it for the first time.
+    #
+    # Callers of this gem write `"linux/arm64"` everywhere and the ergonomic
+    # layer encodes whichever form the endpoint in question wants.
+    module Platform
+      module_function
+
+      # Parse a platform into its OCI object form.
+      #
+      # @param value [String, Hash, nil] "os/arch", "os/arch/variant", an
+      #   already-built OCI hash, or nil
+      # @return [Hash, nil] with "os", "architecture" and optionally "variant"
+      #
+      # @example
+      #   Platform.oci("linux/arm64")   #=> {"os"=>"linux", "architecture"=>"arm64"}
+      #   Platform.oci("linux/arm/v7")  #=> {"os"=>"linux", "architecture"=>"arm", "variant"=>"v7"}
+      def oci(value)
+        return nil if value.nil?
+        return value if value.is_a?(Hash)
+
+        os, architecture, variant = value.to_s.split("/", 3)
+        return nil if os.nil? || os.empty?
+
+        { "os" => os, "architecture" => architecture, "variant" => variant }.compact
+      end
+
+      # Render a platform in the `os[/arch[/variant]]` string form.
+      #
+      # @param value [String, Hash, nil]
+      # @return [String, nil]
+      #
+      # @example
+      #   Platform.string("os" => "linux", "architecture" => "arm64") #=> "linux/arm64"
+      def string(value)
+        return nil if value.nil?
+        return value if value.is_a?(String)
+
+        [value["os"] || value[:os],
+         value["architecture"] || value[:architecture],
+         value["variant"] || value[:variant]].compact.join("/")
+      end
+    end
+  end
+end

data/lib/docker/api/query.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Turns Ruby values into the query strings the Engine API expects.
+    #
+    # Docker's conventions are specific enough to be worth centralising, and
+    # they are not uniform:
+    #
+    # * Booleans travel as the literal strings "true" and "false".
+    # * Structured parameters such as `filters` are declared in the API
+    #   specification as strings holding a JSON document, so a Hash becomes one
+    #   JSON-encoded value.
+    # * A handful of parameters -- the `platform` and `type` parameters of the
+    #   image and system endpoints -- are declared as arrays with
+    #   `collectionFormat: multi`, so an Array becomes a repeated key rather
+    #   than one JSON value.
+    #
+    # Getting this wrong does not raise: the daemon ignores a parameter it
+    # cannot parse and quietly does something else, which is the failure mode
+    # that makes it worth encoding in one place.
+    module Query
+      module_function
+
+      # Encode a parameter hash as a URL query fragment.
+      #
+      # Nil values are dropped rather than sent empty, because an empty value
+      # is not the same as an absent one to the daemon: `?all=` is a parse
+      # error where omitting `all` is a default.
+      #
+      # @param params [Hash] parameters in Ruby types
+      # @return [String] a fragment beginning with "?", or "" when nothing
+      #   survived, so callers can concatenate unconditionally
+      #
+      # @example A boolean and a JSON-encoded filter
+      #   Query.encode(all: true, filters: { "status" => ["running"] })
+      #   #=> "?all=true&filters=%7B%22status%22%3A%5B%22running%22%5D%7D"
+      #
+      # @example An array parameter, repeated rather than JSON-encoded
+      #   Query.encode(platform: ["linux/amd64", "linux/arm64"])
+      #   #=> "?platform=linux%2Famd64&platform=linux%2Farm64"
+      def encode(params)
+        pairs = (params || {}).reject { |_, value| value.nil? }
+          .flat_map { |key, value| pairs_for(key.to_s, value) }
+
+        return "" if pairs.empty?
+
+        "?#{URI.encode_www_form(pairs)}"
+      end
+
+      # @param key [String] the wire parameter name
+      # @param value [Object] the Ruby value
+      # @return [Array<Array(String, String)>] one or more key/value pairs
+      # @api private
+      def pairs_for(key, value)
+        return value.map { |element| [key, serialize(element)] } if value.is_a?(Array)
+
+        [[key, serialize(value)]]
+      end
+
+      # @param value [Object]
+      # @return [String] the daemon's expected wire form for a single value
+      # @api private
+      def serialize(value)
+        case value
+        when true, false then value.to_s
+        when Hash then JSON.generate(value)
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/docker/api/resource.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Shared behaviour for the objects the daemon describes: containers,
+    # images, networks and volumes.
+    #
+    # The Engine API returns different shapes for the same object depending on
+    # how you asked. `GET /containers/json` answers with `Names: ["/web"]`;
+    # `GET /containers/{id}/json` answers with `Name: "/web"`. A client that
+    # simply exposes whichever payload it happened to receive pushes that
+    # difference onto every caller, which is why code written against such a
+    # client ends up reading `info["Names"]` in one place and `[:Name]` in
+    # another and breaking when the two are swapped.
+    #
+    # Resources here normalise. {#name} answers the same thing regardless of
+    # origin, and 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 letting the caller guess why.
+    #
+    # @abstract Subclass and implement {#reload}.
+    class Resource
+      # @return [Docker::API::Client] the client this resource came from
+      attr_reader :client
+
+      # @param client [Docker::API::Client] the client to issue further calls on
+      # @param raw [Hash] the daemon's payload
+      # @param partial [Boolean] whether the payload came from a list endpoint
+      def initialize(client:, raw:, partial: false)
+        @client = client
+        @raw = raw || {}
+        @partial = partial
+        @reloaded = false
+        @stale = false
+      end
+
+      # The daemon's payload, exactly as it arrived.
+      #
+      # Always available, so nothing this gem does not model is out of reach.
+      #
+      # @return [Hash]
+      attr_reader :raw
+
+      # @return [Boolean] whether this came from a list and may lack detail
+      def partial?
+        @partial
+      end
+
+      # @return [String, nil] the object's id
+      def id
+        raw["Id"] || raw["ID"]
+      end
+
+      # Read a key straight from the payload, with no normalisation.
+      #
+      # @param key [String] a key as the daemon spells it
+      # @return [Object, nil]
+      def [](key)
+        raw[key]
+      end
+
+      # @return [Boolean] whether an action has changed this object since the
+      #   payload in hand was fetched
+      def stale?
+        @stale
+      end
+
+      # Re-fetch this object from the daemon.
+      #
+      # @return [self]
+      def reload
+        raise NotImplementedError, "#{self.class} must implement #reload"
+      end
+
+      # @return [String]
+      def to_s
+        "#<#{self.class.name} id=#{id.to_s[0, 12]}#{partial? ? " partial" : ""}>"
+      end
+      alias_method :inspect, :to_s
+
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) && !id.nil? && id == other.id
+      end
+      alias_method :eql?, :==
+
+      # @return [Integer]
+      def hash
+        [self.class, id].hash
+      end
+
+      private
+
+      # Read the first of several possible keys, fetching detail if needed.
+      #
+      # Every key is tried against the payload already in hand before any
+      # request is considered. That ordering is the whole point: a container
+      # from a list carries its name under "Names", so asking for
+      # `detail("Name", "Names")` must answer from memory rather than spending
+      # a round trip rediscovering what it was already told.
+      #
+      # A partial resource reloads at most once, no matter how many accessors
+      # ask for something it does not have. A complete resource never reloads:
+      # if the daemon did not report the field, it is genuinely absent, and a
+      # second identical request would only confirm that more slowly.
+      #
+      # @param keys [Array<String>] keys to try, in order of preference
+      # @return [Object, nil]
+      def detail(*keys)
+        refresh_if_stale
+        found = first_present(keys)
+        return found unless found.nil?
+        return nil unless partial? && !@reloaded
+
+        @reloaded = true
+        reload
+        first_present(keys)
+      end
+
+      # Note that an action just changed this object on the daemon.
+      #
+      # Starting a container does not update the payload we are holding, so
+      # without this a caller who starts a container and then asks its state is
+      # told "created" -- true when we fetched it, and useless now. The refresh
+      # is deferred rather than immediate, so an action followed by no question
+      # still costs one request rather than two.
+      #
+      # @return [self]
+      def mark_stale
+        @stale = true
+        self
+      end
+
+      # @return [void]
+      def refresh_if_stale
+        return unless @stale
+
+        @stale = false
+        @reloaded = false
+        reload
+      end
+
+      # @param keys [Array<String>]
+      # @return [Object, nil]
+      def first_present(keys)
+        keys.each do |key|
+          value = key.include?(".") ? raw.dig(*key.split(".")) : raw[key]
+          return value unless value.nil?
+        end
+        nil
+      end
+
+      # Replace the payload after a re-fetch.
+      #
+      # @param payload [Hash]
+      # @return [self]
+      def replace_raw(payload)
+        @raw = payload || {}
+        @partial = false
+        @stale = false
+        self
+      end
+
+      # @return [Docker::API::Operations]
+      def operations
+        client.operations
+      end
+    end
+  end
+end