docker-api-ng 0.3.0

data/lib/docker/api/transport/fake.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    module Transport
+      # A scripted daemon for tests, served over a real socket pair.
+      #
+      # 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 a double the production code could never actually drive.
+      # `Socket.pair` gives real socket semantics with no network, so the
+      # connection layer is exercised exactly as it runs against a daemon --
+      # including chunked bodies, keep-alive and connection upgrades.
+      #
+      # @example Scripting one response
+      #   fake = Docker::API::Transport::Fake.new([
+      #     "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok",
+      #   ])
+      #   client = Docker::API::Client.new(transport: fake, api_version: "1.55")
+      #   client.system.info
+      #   fake.requests.first #=> "GET /v1.55/info HTTP/1.1\r\n..."
+      class Fake < Base
+        # @return [Array<String>] raw request bytes, in the order received
+        attr_reader :requests
+
+        # @param responses [Array<String>] raw HTTP responses to serve, in order
+        def initialize(responses = [])
+          super()
+          @responses = Array(responses).dup
+          @requests = []
+          @mutex = Mutex.new
+          @threads = []
+        end
+
+        # Add another scripted response.
+        #
+        # @param response [String] raw HTTP response bytes
+        # @return [self]
+        def <<(response)
+          @mutex.synchronize { @responses << response }
+          self
+        end
+
+        # @return [IO] the client end of a socket pair with a server behind it
+        def connect
+          ours, theirs = Socket.pair(:UNIX, :STREAM)
+          thread = Thread.new { serve(theirs) }
+          thread.report_on_exception = false
+          @threads << thread
+          ours
+        end
+
+        # Wait for the scripted server to finish, so assertions about recorded
+        # requests do not race the thread that records them.
+        #
+        # @return [void]
+        def finish
+          @threads.each { |thread| thread.join(2) }
+          self
+        end
+
+        # @return [String]
+        def to_s
+          "#<Docker::API::Transport::Fake scripted=#{@responses.size}>"
+        end
+        alias_method :inspect, :to_s
+
+        private
+
+        # Serve requests until the client goes away or the script runs out.
+        #
+        # Hanging up once the last scripted response has been written is what
+        # lets a client that reads to end-of-stream finish. A server that
+        # politely waited for another request would leave every such read
+        # blocked forever, which is a hang rather than a failure and therefore
+        # far more annoying to diagnose.
+        #
+        # @param io [IO] the server end of the pair
+        # @return [void]
+        def serve(io)
+          loop do
+            request = read_request(io)
+            break if request.nil?
+
+            @mutex.synchronize { @requests << request }
+            response, remaining = @mutex.synchronize { [@responses.shift, @responses.size] }
+            break if response.nil?
+
+            io.write(response)
+            break if remaining == 0
+          end
+        rescue IOError, SystemCallError
+          nil
+        ensure
+          begin
+            io.close unless io.closed?
+          rescue IOError, SystemCallError
+            nil
+          end
+        end
+
+        # Read one complete HTTP request: the head, then the body, however
+        # the client chose to frame it.
+        #
+        # Chunked bodies matter here rather than being pedantry. A build
+        # context is streamed from an IO, so Net::HTTP sends it chunked with no
+        # Content-Length. A fake that stops after the head leaves the body in
+        # the socket, reads it as if it were the next request, and quietly
+        # consumes the response scripted for the call after this one.
+        #
+        # @param io [IO] the server end of the pair
+        # @return [String, nil] raw request bytes, or nil at end of stream
+        def read_request(io)
+          head = +""
+          until head.end_with?("\r\n\r\n")
+            line = io.gets
+            return nil if line.nil?
+
+            head << line
+          end
+
+          return head + read_chunked_body(io) if head.match?(/^Transfer-Encoding:\s*chunked/i)
+
+          length = head[/^Content-Length:\s*(\d+)/i, 1]
+          return head if length.nil?
+
+          head + io.read(Integer(length)).to_s
+        end
+
+        # @param io [IO] the server end of the pair
+        # @return [String] the decoded body
+        def read_chunked_body(io)
+          body = +""
+          loop do
+            size_line = io.gets
+            break if size_line.nil?
+
+            size = size_line.strip.split(";").first.to_i(16)
+            break if size == 0
+
+            body << io.read(size).to_s
+            io.read(2) # the CRLF that terminates the chunk
+          end
+          io.gets # the blank line after the terminating chunk
+          body
+        end
+      end
+    end
+  end
+end

data/lib/docker/api/transport/named_pipe.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    module Transport
+      # A daemon reached over a Windows named pipe, which is how Docker Desktop
+      # for Windows exposes the Engine API by default.
+      #
+      # Windows named pipes present as files, so a binary-mode File is a
+      # bidirectional stream that behaves closely enough to a socket for the
+      # layer above. This is the transport the docker-api gem never grew, which
+      # is why kitchen-dokken carries a standing TODO about Windows support.
+      class NamedPipe < Base
+        # The pipe Docker Desktop for Windows publishes by default.
+        DEFAULT_PIPE = "//./pipe/docker_engine"
+
+        # @return [String] the pipe path
+        attr_reader :path
+
+        # @param path [String] the pipe path
+        def initialize(path: DEFAULT_PIPE)
+          super()
+          @path = path
+        end
+
+        # @return [IO] the opened pipe
+        # @raise [Docker::API::ConnectionError]
+        def connect
+          dial("npipe://#{path}") do
+            pipe = File.open(windows_path, "r+b")
+            pipe.sync = true
+            pipe
+          end
+        end
+
+        # @return [String]
+        def to_s
+          "#<Docker::API::Transport::NamedPipe path=#{path}>"
+        end
+        alias_method :inspect, :to_s
+
+        private
+
+        # Accept both the forward-slash form that appears in DOCKER_HOST and
+        # the backslash form Windows itself uses, rather than making callers
+        # care which one they happen to have.
+        #
+        # @return [String]
+        def windows_path
+          path.tr("/", "\\")
+        end
+      end
+    end
+  end
+end

data/lib/docker/api/transport/tcp.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    module Transport
+      # A daemon reached over plain TCP. Unencrypted, so appropriate only on a
+      # trusted network or a loopback address.
+      class Tcp < Base
+        # @return [String] the host
+        attr_reader :host
+
+        # @return [Integer] the port
+        attr_reader :port
+
+        # @param host [String] the host to dial
+        # @param port [Integer] the port to dial
+        # @param open_timeout [Numeric] seconds to wait for the connection
+        def initialize(host:, port:, open_timeout: 10)
+          super()
+          @host = host
+          @port = Integer(port)
+          @open_timeout = open_timeout
+        end
+
+        # @return [IO] a connected TCP socket
+        # @raise [Docker::API::ConnectionError]
+        def connect
+          dial("tcp://#{host}:#{port}") do
+            Socket.tcp(host, port, connect_timeout: @open_timeout)
+          end
+        end
+
+        # @return [String]
+        def host_header
+          "#{host}:#{port}"
+        end
+
+        # @return [String]
+        def to_s
+          "#<Docker::API::Transport::Tcp host=#{host} port=#{port}>"
+        end
+        alias_method :inspect, :to_s
+      end
+    end
+  end
+end

data/lib/docker/api/transport/tls.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    module Transport
+      # A daemon reached over TLS, as `DOCKER_CERT_PATH` configures.
+      #
+      # The handshake happens here rather than in Net::HTTP. That is deliberate:
+      # the layer above receives an already-encrypted socket and does not need
+      # to know whether TLS is in play, which keeps one code path for every
+      # transport.
+      class Tls < Tcp
+        # @param host [String] the host to dial
+        # @param port [Integer] the port to dial
+        # @param ca_file [String, nil] path to the CA bundle
+        # @param cert_file [String, nil] path to the client certificate
+        # @param key_file [String, nil] path to the client key
+        # @param verify [Boolean] whether to verify the daemon's certificate
+        # @param open_timeout [Numeric] seconds to wait for the connection
+        def initialize(host:, port:, ca_file: nil, cert_file: nil, key_file: nil,
+          verify: true, open_timeout: 10)
+          super(host: host, port: port, open_timeout: open_timeout)
+          @ca_file = ca_file
+          @cert_file = cert_file
+          @key_file = key_file
+          @verify = verify
+        end
+
+        # @return [OpenSSL::SSL::SSLSocket] a connected, handshaken socket
+        # @raise [Docker::API::ConnectionError]
+        def connect
+          dial("https://#{host}:#{port}") do
+            # The raw socket is closed by hand if anything between here and a
+            # completed handshake raises. sync_close only ties the two together
+            # once an SSLSocket exists and owns it, so an expired certificate,
+            # a hostname mismatch or an untrusted CA used to leave the
+            # descriptor open until GC got to it -- and a retry loop waiting for
+            # a daemon to come up exhausts descriptors rather than failing.
+            raw = super_socket
+            begin
+              socket = OpenSSL::SSL::SSLSocket.new(raw, ssl_context)
+              socket.hostname = host # SNI, which some proxies in front of a daemon require
+              socket.sync_close = true
+              socket.connect
+              socket
+            rescue StandardError
+              raw.close unless raw.closed?
+              raise
+            end
+          end
+        end
+
+        # @return [String]
+        def to_s
+          "#<Docker::API::Transport::Tls host=#{host} port=#{port} verify=#{@verify}>"
+        end
+        alias_method :inspect, :to_s
+
+        private
+
+        # @return [IO] the underlying TCP socket
+        def super_socket
+          Socket.tcp(host, port, connect_timeout: @open_timeout)
+        end
+
+        # @return [OpenSSL::SSL::SSLContext]
+        def ssl_context
+          context = OpenSSL::SSL::SSLContext.new
+          context.min_version = OpenSSL::SSL::TLS1_2_VERSION
+          context.verify_mode = @verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+          context.ca_file = @ca_file if @ca_file
+          if @cert_file && @key_file
+            context.cert = OpenSSL::X509::Certificate.new(File.read(@cert_file))
+            context.key = OpenSSL::PKey.read(File.read(@key_file))
+          end
+          context
+        end
+      end
+    end
+  end
+end

data/lib/docker/api/transport/unix.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    module Transport
+      # A daemon reached over a unix domain socket, which is how Docker is
+      # reached on Linux and macOS by default.
+      class Unix < Base
+        # @return [String] the socket path
+        attr_reader :path
+
+        # @param path [String] the socket path, e.g. "/var/run/docker.sock"
+        def initialize(path:)
+          super()
+          @path = path
+        end
+
+        # @return [IO] a connected unix socket
+        # @raise [Docker::API::ConnectionError]
+        def connect
+          dial("unix://#{path}") { UNIXSocket.new(path) }
+        end
+
+        # @return [String]
+        def to_s
+          "#<Docker::API::Transport::Unix path=#{path}>"
+        end
+        alias_method :inspect, :to_s
+      end
+    end
+  end
+end

data/lib/docker/api/transport.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Transports know how to reach a daemon, and nothing else.
+    #
+    # Every transport answers {Base#connect} with a connected IO. That single
+    # responsibility is what lets the same connection code drive a unix socket
+    # in development, TLS in CI and a Windows named pipe on a laptop.
+    module Transport
+      # Build the transport a Docker host URL calls for.
+      #
+      # @param url [String] a Docker host URL. Understands `unix://`, `tcp://`,
+      #   `http://`, `https://`, `npipe://`, and a bare path (taken as a unix
+      #   socket), matching what `DOCKER_HOST` may contain.
+      # @param tls [Hash, nil] TLS material: `:ca_file`, `:cert_file`,
+      #   `:key_file`, `:verify`. Any of these upgrades a `tcp://` URL to TLS.
+      # @param open_timeout [Numeric] seconds to wait for a connection
+      # @return [Docker::API::Transport::Base]
+      # @raise [Docker::API::ConnectionError] if the scheme is not one we speak
+      #
+      # @example
+      #   Transport.for(url: "unix:///var/run/docker.sock")
+      #   Transport.for(url: "tcp://build:2376", tls: { ca_file: "ca.pem" })
+      def self.for(url:, tls: nil, open_timeout: 10)
+        scheme, rest = split(url.to_s)
+        tls = nil if tls.respond_to?(:empty?) && tls.empty?
+
+        case scheme
+        when "unix"
+          Unix.new(path: rest)
+        when "npipe"
+          NamedPipe.new(path: rest)
+        when "https"
+          tcp_transport(rest, tls || {}, open_timeout, secure: true)
+        when "tcp", "http"
+          tcp_transport(rest, tls, open_timeout, secure: !tls.nil?)
+        else
+          raise ConnectionError.new(
+            "cannot reach a Docker daemon over '#{scheme}' (from #{url.inspect}); " \
+            "expected one of unix, tcp, http, https or npipe"
+          )
+        end
+      end
+
+      # Split a host URL into a scheme and the remainder.
+      #
+      # Hand-parsed rather than handed to URI, because `unix:///var/run/x.sock`
+      # and `npipe:////./pipe/docker_engine` are not URLs that URI's generic
+      # parser handles the way Docker means them.
+      #
+      # @param url [String]
+      # @return [Array(String, String)] the scheme and the remainder
+      # @api private
+      def self.split(url)
+        if (match = url.match(%r{\A(?<scheme>[a-z][a-z0-9+.-]*)://(?<rest>.*)\z}i))
+          scheme = match[:scheme].downcase
+          rest = match[:rest]
+          # unix and npipe carry a path, and the leading slash is part of it.
+          rest = "/#{rest}" if %w{unix npipe}.include?(scheme) && !rest.start_with?("/")
+          [scheme, rest]
+        elsif url.start_with?("/", "\\") || url.empty?
+          # A bare path is what a daemon on a unix socket looks like.
+          ["unix", url.empty? ? "/var/run/docker.sock" : url]
+        else
+          ["tcp", url]
+        end
+      end
+      private_class_method :split
+
+      # @param authority [String] "host:port" or "host"
+      # @param tls [Hash, nil] TLS material
+      # @param open_timeout [Numeric]
+      # @param secure [Boolean]
+      # @return [Docker::API::Transport::Tcp, Docker::API::Transport::Tls]
+      # @api private
+      def self.tcp_transport(authority, tls, open_timeout, secure:)
+        host, port = split_authority(authority, secure: secure)
+
+        return Tcp.new(host: host, port: port, open_timeout: open_timeout) unless secure
+
+        tls ||= {}
+        Tls.new(
+          host: host, port: port, open_timeout: open_timeout,
+          ca_file: tls[:ca_file], cert_file: tls[:cert_file], key_file: tls[:key_file],
+          verify: tls.fetch(:verify, true)
+        )
+      end
+      private_class_method :tcp_transport
+
+      # @param authority [String]
+      # @param secure [Boolean]
+      # @return [Array(String, Integer)]
+      # @api private
+      def self.split_authority(authority, secure:)
+        authority = authority.sub(%r{/.*\z}, "")
+        default_port = secure ? 2376 : 2375
+        # `tcp://` with nothing after it means localhost, which is what the
+        # Docker CLI does with a bare scheme.
+        return ["localhost", default_port] if authority.empty?
+
+        host, _, port = authority.rpartition(":")
+        return [authority, default_port] if host.empty?
+
+        [host, port.empty? ? default_port : Integer(port)]
+      end
+      private_class_method :split_authority
+    end
+  end
+end

data/lib/docker/api/version.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The gem's own version.
+    VERSION = "0.3.0"
+
+    # The newest Engine API version this gem vendors a specification for.
+    # Requests are never made against a version above this, even when the
+    # daemon offers one, because the generated layer only knows this shape.
+    MAX_API_VERSION = "1.55"
+
+    # The oldest Engine API version this gem will talk to. Docker 20.10 is the
+    # oldest release still plausibly in service; below it, enough of the API
+    # differs that failing loudly beats failing mysteriously.
+    MIN_API_VERSION = "1.41"
+  end
+end

data/lib/docker/api.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+require "json" unless defined?(JSON)
+require "net/http" unless defined?(Net::HTTP)
+require "openssl" unless defined?(OpenSSL)
+require "socket" unless defined?(Socket)
+require "stringio" unless defined?(StringIO)
+require "uri" unless defined?(URI)
+
+# The `docker-api` gem also owns the `Docker` namespace. This gem reopens it
+# additively and defines nothing directly on it, so both can be loaded into one
+# process -- which is what makes a gradual migration possible rather than a
+# flag day.
+module Docker
+  # A Ruby client for the modern Docker Engine API.
+  #
+  # The complete API surface is generated from Docker's own OpenAPI
+  # specification and reachable through {Client#operations}; an ergonomic
+  # hand-written layer of collections and resources sits on top of it.
+  #
+  # @example Talking to the local daemon
+  #   client = Docker::API::Client.new
+  #   client.system.info["ServerVersion"]
+  #
+  # @example Two daemons at once, with no shared state
+  #   local = Docker::API::Client.new
+  #   build = Docker::API::Client.new(url: "tcp://build.internal:2376")
+  module API
+    require_relative "api/version"
+    require_relative "api/errors"
+    require_relative "api/response"
+    require_relative "api/query"
+    require_relative "api/path"
+    require_relative "api/body"
+    require_relative "api/platform"
+    require_relative "api/tar"
+    require_relative "api/transport/base"
+    require_relative "api/transport/unix"
+    require_relative "api/transport/tcp"
+    require_relative "api/transport/tls"
+    require_relative "api/transport/named_pipe"
+    require_relative "api/transport/fake"
+    require_relative "api/transport"
+    require_relative "api/session"
+    require_relative "api/stream"
+    require_relative "api/connection"
+    require_relative "api/context"
+    require_relative "api/config"
+    require_relative "api/auth"
+    require_relative "api/operations"
+    require_relative "api/collection"
+    require_relative "api/resource"
+    require_relative "api/resources/exec"
+    require_relative "api/resources/container"
+    require_relative "api/resources/image"
+    require_relative "api/resources/network"
+    require_relative "api/resources/volume"
+    require_relative "api/collections/containers"
+    require_relative "api/collections/images"
+    require_relative "api/collections/networks"
+    require_relative "api/collections/volumes"
+    require_relative "api/collections/system"
+    require_relative "api/client"
+  end
+end

data/sig/docker/api/core.rbs

@@ -0,0 +1,109 @@
+# Hand-written signatures for the layers the generated operations depend on.
+#
+# Kept deliberately narrow: enough to type-check the generated file against the
+# connection it calls, without pinning down internals that are free to change.
+
+module Docker
+  module API
+    VERSION: String
+    MAX_API_VERSION: String
+    MIN_API_VERSION: String
+
+    class Error < StandardError
+      attr_reader operation: String?
+      attr_reader status: Integer?
+      attr_reader response: Docker::API::Response?
+
+      def initialize: (?String? message, ?operation: (String | Symbol)?, ?status: Integer?, ?response: Docker::API::Response?) -> void
+      def self.for: (status: Integer, ?operation: (String | Symbol)?, ?response: Docker::API::Response?) -> Docker::API::Error
+    end
+
+    class ConnectionError < Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class ClientError < Error
+    end
+
+    class BadRequest < ClientError
+    end
+
+    class Unauthorized < ClientError
+    end
+
+    class Forbidden < ClientError
+    end
+
+    class NotFound < ClientError
+    end
+
+    class NotModified < ClientError
+    end
+
+    class Conflict < ClientError
+    end
+
+    class ServerError < Error
+    end
+
+    class VersionUnsupported < Error
+    end
+
+    class StreamError < Error
+    end
+
+    class Response
+      attr_reader status: Integer
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String
+
+      def initialize: (status: Integer, ?headers: Hash[untyped, untyped], ?body: String?) -> void
+      def json: () -> untyped
+      def success?: () -> bool
+      def []: ((String | Symbol) name) -> String?
+    end
+
+    class Connection
+      UNVERSIONED: Array[String]
+
+      def initialize: (transport: untyped, ?api_version: (String | Symbol), ?logger: untyped?, ?read_timeout: Numeric, ?open_timeout: Numeric) -> void
+      def api_version: () -> String?
+      def ping: () -> Docker::API::Response
+      def request: (
+        Symbol http_method,
+        String path,
+        ?query: Hash[untyped, untyped],
+        ?body: untyped,
+        ?headers: Hash[untyped, untyped],
+        ?expects: Array[Integer],
+        ?operation: (String | Symbol)?,
+        ?content_type: String?
+      ) ?{ (String) -> void } -> Docker::API::Response
+      def hijack: (
+        Symbol http_method,
+        String path,
+        ?query: Hash[untyped, untyped],
+        ?body: untyped,
+        ?headers: Hash[untyped, untyped],
+        ?operation: (String | Symbol)?
+      ) -> IO
+    end
+
+    module Path
+      SAFE: Regexp
+
+      def self.escape: (untyped value) -> String
+    end
+
+    module Query
+      def self.encode: (Hash[untyped, untyped]? params) -> String
+    end
+
+    module Platform
+      def self.oci: (untyped value) -> Hash[String, String]?
+      def self.string: (untyped value) -> String?
+    end
+  end
+end