docker-api-ng 0.3.0

data/lib/docker/api/connection.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Everything between "a socket exists" and "a Ruby value comes back".
+    #
+    # A connection owns request building, API version negotiation, error
+    # mapping, streaming and hijack. It is immutable once built: there is no
+    # setter for the URL or for credentials, which is what lets two connections
+    # address two daemons in one process without interfering.
+    class Connection
+      # Endpoints that must not carry a version prefix, because they are how we
+      # discover which version to use.
+      UNVERSIONED = ["/_ping"].freeze
+
+      # HTTP verbs mapped to the Net::HTTP request classes that implement them.
+      VERBS = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        patch: Net::HTTP::Patch,
+        delete: Net::HTTP::Delete,
+        head: Net::HTTP::Head,
+      }.freeze
+
+      # @return [Docker::API::Transport::Base] the transport in use
+      attr_reader :transport
+
+      # @return [Logger, nil] where request metadata is logged, if anywhere
+      attr_reader :logger
+
+      # @param transport [Docker::API::Transport::Base] how to reach the daemon
+      # @param api_version [String, Symbol] `:negotiate` to ask the daemon,
+      #   a version string 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
+      def initialize(transport:, api_version: :negotiate, logger: nil,
+        read_timeout: 60, open_timeout: 10)
+        @transport = transport
+        @configured_api_version = api_version
+        @logger = logger
+        @read_timeout = read_timeout
+        @open_timeout = open_timeout
+        @version_lock = Mutex.new
+      end
+
+      # The API version this connection prefixes its requests with.
+      #
+      # Negotiation happens once, lazily, on the first request that needs it.
+      #
+      # @return [String, nil] the version, or nil when versioning is disabled
+      # @raise [Docker::API::VersionUnsupported] if the daemon is too old
+      def api_version
+        return @api_version if defined?(@api_version)
+
+        @version_lock.synchronize do
+          @api_version = resolve_api_version unless defined?(@api_version)
+        end
+        @api_version
+      end
+
+      # Ask the daemon whether it is alive. Never version-prefixed.
+      #
+      # @return [Docker::API::Response]
+      def ping
+        request(:get, "/_ping", operation: "ping")
+      end
+
+      # Send a request and interpret the answer.
+      #
+      # @param method [Symbol] one of :get, :post, :put, :patch, :delete, :head
+      # @param path [String] the path, without a version prefix
+      # @param query [Hash] query parameters in Ruby types
+      # @param body [Hash, Array, String, IO, nil] the request body. Hashes and
+      #   arrays are JSON-encoded; strings and IOs are sent as-is.
+      # @param headers [Hash] additional request headers
+      # @param expects [Array<Integer>] statuses that mean success
+      # @param operation [String, Symbol, nil] names this call in errors and logs
+      # @param content_type [String, nil] overrides the computed content type
+      # @yieldparam chunk [String] successive body chunks, when streaming
+      # @return [Docker::API::Response] with an empty body when streamed
+      # @raise [Docker::API::Error] for any status outside `expects`
+      def request(method, path, query: {}, body: nil, headers: {}, expects: [200],
+        operation: nil, content_type: nil, &block)
+        full_path = build_path(path, query)
+        payload, computed_type = encode_body(body)
+        request_headers = build_headers(headers, content_type || computed_type, payload)
+
+        log(method, full_path, operation)
+
+        response = perform(method, full_path, payload, request_headers, expects, &block)
+        return response if expects.include?(response.status)
+
+        raise Error.for(status: response.status, operation: operation, response: response)
+      end
+
+      # Take over the socket after an upgrade, for interactive exec and attach.
+      #
+      # This deliberately does not go through Net::HTTP. An interactive session
+      # needs the socket itself, and `Net::BufferedIO` may already have read
+      # ahead past the response headers. Rather than prise a buffered socket
+      # back out of the stdlib -- the problem that produced docker-api's custom
+      # Excon middleware -- this writes the request itself and hands back the
+      # socket with nothing consumed but the response head.
+      #
+      # @param method [Symbol] the HTTP verb
+      # @param path [String] the path, without a version prefix
+      # @param query [Hash] query parameters
+      # @param body [Hash, String, nil] the request body
+      # @param headers [Hash] additional headers
+      # @param operation [String, Symbol, nil] names this call in errors
+      # @return [IO] the bidirectional socket, positioned at the stream body
+      # @raise [Docker::API::Error] if the daemon refused to upgrade
+      def hijack(method, path, query: {}, body: nil, headers: {}, operation: nil)
+        io = transport.connect
+        full_path = build_path(path, query)
+        payload, computed_type = encode_body(body)
+
+        write_raw_request(io, method, full_path, payload, headers, computed_type)
+        status, response_headers = read_raw_response_head(io)
+
+        unless [101, 200].include?(status)
+          error_body = io.read.to_s
+          io.close unless io.closed?
+          raise Error.for(
+            status: status, operation: operation,
+            response: Response.new(status: status, headers: response_headers, body: error_body)
+          )
+        end
+
+        io
+      rescue Errno::EPIPE, Errno::ECONNRESET, EOFError => e
+        io&.close unless io.nil? || io.closed?
+        raise ConnectionError.new("the daemon closed the connection during #{operation}: #{e.message}")
+      end
+
+      # @return [String]
+      def to_s
+        "#<Docker::API::Connection transport=#{transport} api_version=#{
+          defined?(@api_version) ? @api_version : "unnegotiated"}>"
+      end
+      alias_method :inspect, :to_s
+
+      private
+
+      # @return [String, nil]
+      def resolve_api_version
+        case @configured_api_version
+        when :none then nil
+        when :negotiate then negotiate_api_version
+        else @configured_api_version.to_s.sub(/\Av/, "")
+        end
+      end
+
+      # Ask the daemon what it speaks and meet it in the middle.
+      #
+      # Pinning to the daemon's version when it is older keeps us inside what
+      # it understands; capping at what this gem vendors keeps us inside what
+      # the generated layer knows how to ask for.
+      #
+      # @return [String]
+      # @raise [Docker::API::VersionUnsupported]
+      def negotiate_api_version
+        response = ping
+        daemon = response["api-version"]
+
+        return MAX_API_VERSION if daemon.nil? || daemon.empty?
+
+        if Gem::Version.new(daemon) < Gem::Version.new(MIN_API_VERSION)
+          raise VersionUnsupported.new(
+            "the daemon speaks Engine API v#{daemon}, but docker-api-ng requires " \
+            "at least v#{MIN_API_VERSION}. Upgrade Docker, or pin an older release of this gem."
+          )
+        end
+
+        [Gem::Version.new(daemon), Gem::Version.new(MAX_API_VERSION)].min.to_s
+      end
+
+      # @param path [String]
+      # @param query [Hash]
+      # @return [String]
+      def build_path(path, query)
+        prefix = if UNVERSIONED.include?(path) || api_version.nil?
+                   ""
+                 else
+                   "/v#{api_version}"
+                 end
+        "#{prefix}#{path}#{Query.encode(query)}"
+      end
+
+      # Encode a body and work out what to call it.
+      #
+      # Every raw body in this API is an archive: a build context, a container
+      # filesystem, an image tarball. Structured bodies are JSON. There is no
+      # third case, so a body-bearing request never goes out unlabelled.
+      #
+      # That matters more than it looks. The daemon rejects the wrong content
+      # type on its archive endpoints -- docker-api carries a middleware that
+      # retries after parsing "Content-Type: application/json is not
+      # supported. Should be application/x-tar" out of an error body -- and an
+      # absent type is at the mercy of whatever the HTTP layer decides to
+      # guess.
+      #
+      # @param body [Object]
+      # @return [Array(String, IO, nil, String, nil)] the payload and its content type
+      def encode_body(body)
+        case body
+        when nil then [nil, nil]
+        when Hash, Array then [JSON.generate(body), "application/json"]
+        else [body, "application/x-tar"]
+        end
+      end
+
+      # @param headers [Hash]
+      # @param content_type [String, nil]
+      # @param payload [Object]
+      # @return [Hash{String => String}]
+      def build_headers(headers, content_type, payload)
+        base = {
+          "User-Agent" => "docker-api-ng/#{VERSION} (Ruby #{RUBY_VERSION})",
+          "Accept" => "application/json",
+        }
+        base["Content-Type"] = content_type if content_type && payload
+        base.merge(headers.transform_keys(&:to_s))
+      end
+
+      # @return [Docker::API::Response]
+      def perform(method, full_path, payload, headers, expects, &block)
+        klass = VERBS.fetch(method) { raise ArgumentError, "unsupported HTTP method: #{method.inspect}" }
+        request = klass.new(full_path, headers)
+        attach_payload(request, payload)
+
+        session = Session.new(transport, read_timeout: @read_timeout, open_timeout: @open_timeout)
+        result = nil
+
+        session.start do |http|
+          http.request(request) do |raw|
+            status = raw.code.to_i
+            result = if block && expects.include?(status)
+                       raw.read_body { |chunk| block.call(chunk) }
+                       Response.new(status: status, headers: raw.to_hash, body: nil)
+                     else
+                       Response.new(status: status, headers: raw.to_hash, body: raw.read_body)
+                     end
+          end
+        end
+
+        result
+      # Net::OpenTimeout, Net::ReadTimeout and Net::WriteTimeout all descend
+      # from Timeout::Error, so naming them individually would only shadow it.
+      rescue Timeout::Error => e
+        raise TimeoutError.new("#{transport} did not answer in time: #{e.class}: #{e.message}")
+      # EOFError is an IOError, so listing it separately would only shadow it.
+      rescue Net::HTTPBadResponse, Net::ProtocolError, IOError,
+             SystemCallError, SocketError, OpenSSL::SSL::SSLError => e
+        raise ConnectionError.new("#{transport} failed mid-request: #{e.class}: #{e.message}")
+      end
+
+      # Streamed by capability rather than by class.
+      #
+      # `IO, StringIO` looked exhaustive and is not: Tempfile is a delegator
+      # around File, so `Tempfile.new.is_a?(IO)` is false. A build context
+      # packed to a temporary file would have fallen through to `body = payload`
+      # and been sent as the delegator's to_s -- a string like
+      # `#<Tempfile:...>` where the daemon expected a tar. What Net::HTTP
+      # actually needs from a body stream is `read`, so that is what is asked
+      # for.
+      #
+      # @return [void]
+      def attach_payload(request, payload)
+        case payload
+        when nil then nil
+        when String then request.body = payload
+        else
+          if payload.respond_to?(:read)
+            request.body_stream = payload
+            request["Transfer-Encoding"] = "chunked"
+          else
+            request.body = payload
+          end
+        end
+      end
+
+      # @return [void]
+      def write_raw_request(io, method, full_path, payload, headers, content_type)
+        lines = ["#{method.to_s.upcase} #{full_path} HTTP/1.1"]
+        head = {
+          "Host" => transport.host_header,
+          "User-Agent" => "docker-api-ng/#{VERSION} (Ruby #{RUBY_VERSION})",
+          "Connection" => "Upgrade",
+          "Upgrade" => "tcp",
+          "Content-Length" => (payload ? payload.bytesize : 0).to_s,
+        }
+        head["Content-Type"] = content_type if content_type && payload
+        head.merge!(headers.transform_keys(&:to_s))
+
+        head.each { |key, value| lines << "#{key}: #{value}" }
+        io.write("#{lines.join("\r\n")}\r\n\r\n")
+        io.write(payload) if payload
+        io.flush if io.respond_to?(:flush)
+      end
+
+      # @return [Array(Integer, Hash)]
+      def read_raw_response_head(io)
+        status_line = io.gets
+        raise ConnectionError.new("the daemon closed the connection before answering") if status_line.nil?
+
+        status = status_line[%r{\AHTTP/\d\.\d\s+(\d+)}, 1].to_i
+        headers = {}
+        while (line = io.gets)
+          line = line.chomp
+          break if line.empty?
+
+          key, _, value = line.partition(":")
+          headers[key.strip.downcase] = value.strip
+        end
+        [status, headers]
+      end
+
+      # @return [void]
+      def log(method, full_path, operation)
+        return unless logger
+
+        logger.debug { "docker-api-ng #{operation || "request"} #{method.to_s.upcase} #{full_path}" }
+      end
+    end
+  end
+end

data/lib/docker/api/context.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+require "digest" unless defined?(Digest)
+
+module Docker
+  module API
+    # Docker's context store, which is where the CLI keeps the daemon it is
+    # pointed at when `DOCKER_HOST` is not set.
+    #
+    # `docker context use colima` does not export anything. It writes
+    # `currentContext` into ~/.docker/config.json, and every later `docker`
+    # command resolves the endpoint out of the store. A client that reads only
+    # `DOCKER_HOST` therefore disagrees with the CLI on the same machine, and
+    # falls back to /var/run/docker.sock -- which Docker Desktop happens to
+    # symlink, and Colima, Rancher Desktop, rootless Docker and Podman
+    # generally do not. The failure is a connection refused with a correct
+    # looking environment, which is a bad way to spend an afternoon.
+    #
+    # The store is a directory per context, named for the SHA-256 of the
+    # context's own name, holding a meta.json:
+    #
+    #   ~/.docker/contexts/meta/<sha256(name)>/meta.json
+    #   ~/.docker/contexts/tls/<sha256(name)>/docker/{ca,cert,key}.pem
+    #
+    # Every failure here is soft. An unreadable store, a malformed meta.json or
+    # a context that no longer exists all mean "no context", because falling
+    # back to the platform default is what the CLI does and is more useful than
+    # refusing to start.
+    module Context
+      # The context name that means "no context": use DOCKER_HOST, or the
+      # platform's default socket. It has no entry in the store.
+      DEFAULT = "default"
+
+      module_function
+
+      # Resolve the endpoint the CLI would use, if any.
+      #
+      # @param env [Hash] the environment to read
+      # @param root [String, nil] the Docker configuration directory
+      # @return [Hash, nil] with :url and optionally :tls, or nil when no
+      #   context applies
+      def resolve(env = ENV, root: nil)
+        root ||= config_root(env)
+        name = current_name(env, root)
+        return nil if name.nil? || name.empty? || name == DEFAULT
+
+        endpoint(name, root)
+      end
+
+      # The active context's name: DOCKER_CONTEXT first, then whatever
+      # `docker context use` last wrote into config.json.
+      #
+      # @param env [Hash]
+      # @param root [String]
+      # @return [String, nil]
+      def current_name(env = ENV, root = config_root(env))
+        from_env = env["DOCKER_CONTEXT"]
+        return from_env unless from_env.nil? || from_env.empty?
+
+        config = read_json(File.join(root, "config.json"))
+        config.is_a?(Hash) ? config["currentContext"] : nil
+      end
+
+      # @param name [String] a context name
+      # @param root [String] the Docker configuration directory
+      # @return [Hash, nil] with :url and optionally :tls
+      def endpoint(name, root = config_root)
+        digest = Digest::SHA256.hexdigest(name)
+        meta = read_json(File.join(root, "contexts", "meta", digest, "meta.json"))
+        host = meta.dig("Endpoints", "docker", "Host") if meta.is_a?(Hash)
+        return nil if host.nil? || host.empty?
+
+        resolved = { url: host }
+        tls = tls_material(root, digest, skip_verify: meta.dig("Endpoints", "docker", "SkipTLSVerify"))
+        resolved[:tls] = tls unless tls.empty?
+        resolved
+      end
+
+      # @param env [Hash]
+      # @return [String] the Docker configuration directory
+      def config_root(env = ENV)
+        configured = env["DOCKER_CONFIG"]
+        return configured unless configured.nil? || configured.empty?
+
+        File.join(Dir.home, ".docker")
+      rescue ArgumentError
+        # Dir.home raises when there is no home to speak of, which happens in
+        # stripped containers and some CI images.
+        ".docker"
+      end
+
+      # A context may carry its own TLS material, which is how `docker context
+      # create --docker host=tcp://...,ca=...,cert=...,key=...` stores it.
+      #
+      # @return [Hash]
+      # @api private
+      def tls_material(root, digest, skip_verify: false)
+        directory = File.join(root, "contexts", "tls", digest, "docker")
+        material = { ca_file: "ca.pem", cert_file: "cert.pem", key_file: "key.pem" }
+          .filter_map { |key, file|
+            path = File.join(directory, file)
+            [key, path] if File.readable?(path)
+          }.to_h
+
+        return {} if material.empty?
+
+        material.merge(verify: !skip_verify)
+      end
+
+      # @return [Object, nil]
+      # @api private
+      def read_json(path)
+        return nil unless File.readable?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/docker/api/errors.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The root of every error this gem raises.
+    #
+    # Nothing beneath the abstraction escapes: no `Errno`, no `OpenSSL`
+    # exception, no `Net::` class and no `JSON::ParserError` reaches a caller's
+    # rescue clause. The original is always retained as {#cause}, so nothing is
+    # lost -- but consumers get to rescue one hierarchy instead of coupling
+    # themselves to whichever HTTP library happens to be underneath.
+    #
+    # @example Rescuing anything this gem can raise
+    #   begin
+    #     client.containers.get("missing")
+    #   rescue Docker::API::Error => e
+    #     warn "#{e.operation} failed: #{e.message}"
+    #   end
+    class Error < StandardError
+      # @return [String, nil] the operation that failed, e.g. "container_start"
+      attr_reader :operation
+
+      # @return [Integer, nil] the HTTP status the daemon returned
+      attr_reader :status
+
+      # @return [Docker::API::Response, nil] the response, when there was one
+      attr_reader :response
+
+      # @param message [String, nil] a message, or nil to compose one
+      # @param operation [String, Symbol, nil] the operation that failed
+      # @param status [Integer, nil] the HTTP status
+      # @param response [Docker::API::Response, nil] the response
+      def initialize(message = nil, operation: nil, status: nil, response: nil)
+        @operation = operation&.to_s
+        @status = status
+        @response = response
+        super(message || compose_message)
+      end
+
+      # Build the error class appropriate to an HTTP status.
+      #
+      # @param status [Integer] the HTTP status the daemon returned
+      # @param operation [String, Symbol, nil] the operation that failed
+      # @param response [Docker::API::Response, nil] the response
+      # @return [Docker::API::Error] an instance of the mapped subclass
+      def self.for(status:, operation: nil, response: nil)
+        klass_for(status).new(nil, operation: operation, status: status, response: response)
+      end
+
+      # @param status [Integer] an HTTP status
+      # @return [Class] the error class that status maps to
+      # @api private
+      def self.klass_for(status)
+        STATUS_MAP.fetch(status) do
+          case status
+          when 400..499 then ClientError
+          when 500..599 then ServerError
+          else Error
+          end
+        end
+      end
+      private_class_method :klass_for
+
+      private
+
+      # Compose the most informative message available: what was attempted,
+      # what the daemon said about it, and the status it said it with.
+      #
+      # @return [String]
+      def compose_message
+        parts = []
+        parts << (operation ? "#{operation} failed" : "request failed")
+        parts << "(HTTP #{status})" if status
+        detail = daemon_message
+        parts << ": #{detail}" if detail && !detail.empty?
+        parts.join(" ").sub(" :", ":")
+      end
+
+      # The daemon reports its own reason in a JSON `message` field. Fall back
+      # to the raw body when the response is not JSON, because an unparsed body
+      # is still more use to a human than nothing at all.
+      #
+      # @return [String, nil]
+      def daemon_message
+        return nil if response.nil?
+
+        body = response.body
+        return nil if body.nil? || body.empty?
+
+        parsed = begin
+          JSON.parse(body)
+                 rescue JSON::ParserError
+                   nil
+        end
+
+        return body.strip unless parsed.is_a?(Hash)
+
+        parsed["message"] || parsed["Message"] || body.strip
+      end
+    end
+
+    # The daemon could not be reached at all: refused, reset, unresolvable, or
+    # a TLS handshake that failed.
+    class ConnectionError < Error; end
+
+    # The daemon accepted the connection but did not answer in time.
+    class TimeoutError < Error; end
+
+    # The request was wrong. 4xx.
+    class ClientError < Error; end
+
+    # 400 -- the daemon could not parse or accept the request.
+    class BadRequest < ClientError; end
+
+    # 401 -- authentication is required or was rejected.
+    class Unauthorized < ClientError; end
+
+    # 403 -- the daemon understood but refuses.
+    class Forbidden < ClientError; end
+
+    # 404 -- no such container, image, network, volume or endpoint.
+    class NotFound < ClientError; end
+
+    # 304 -- the requested change was already true. Docker returns this for,
+    # among others, starting an already-running container, which is why it is
+    # grouped with the client errors rather than treated as a redirect.
+    class NotModified < ClientError; end
+
+    # 409 -- the request conflicts with the daemon's current state, such as a
+    # container name already in use.
+    class Conflict < ClientError; end
+
+    # 5xx -- the daemon failed while handling a request it accepted.
+    class ServerError < Error; end
+
+    # The daemon speaks an API version this gem cannot work with.
+    class VersionUnsupported < Error; end
+
+    # A response stream was malformed, truncated, or not the format the
+    # endpoint promised.
+    class StreamError < Error; end
+
+    # Statuses with a specific meaning worth its own class. Anything else falls
+    # back to ClientError or ServerError by range.
+    #
+    # @api private
+    STATUS_MAP = {
+      304 => NotModified,
+      400 => BadRequest,
+      401 => Unauthorized,
+      403 => Forbidden,
+      404 => NotFound,
+      409 => Conflict,
+    }.freeze
+  end
+end