docker-api-ng 0.3.0

data/lib/docker/api/resources/network.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # A network on the daemon.
+    class Network < Resource
+      # @return [String, nil] the network's name
+      def name
+        detail("Name")
+      end
+
+      # @return [String, nil] "bridge", "overlay", "host", and so on
+      def driver
+        detail("Driver")
+      end
+
+      # @return [Boolean] whether the network has IPv6 enabled
+      def ipv6?
+        detail("EnableIPv6") == true
+      end
+
+      # @return [Hash] containers attached to this network, keyed by id
+      def containers
+        detail("Containers") || {}
+      end
+
+      # @return [Array<Hash>] the network's IPAM configuration
+      def subnets
+        detail("IPAM.Config") || []
+      end
+
+      # @return [self]
+      def reload
+        replace_raw(operations.network_inspect(id: id || name).json)
+      end
+
+      # Attach a container to this network.
+      #
+      # @param container [String, Docker::API::Container] the container
+      # @param aliases [Array<String>] additional names it answers to here
+      # @param ipv4_address [String, nil] a fixed address to assign
+      # @param ipv6_address [String, nil] a fixed address to assign
+      # @return [self]
+      #
+      # @example
+      #   network.connect(container, aliases: %w{web web.local})
+      def connect(container, aliases: [], ipv4_address: nil, ipv6_address: nil)
+        endpoint = {}
+        endpoint["Aliases"] = aliases unless aliases.nil? || aliases.empty?
+        endpoint["IPAMConfig"] = {
+          "IPv4Address" => ipv4_address, "IPv6Address" => ipv6_address
+        }.compact
+        endpoint.delete("IPAMConfig") if endpoint["IPAMConfig"].empty?
+
+        body = { "Container" => container_id(container) }
+        body["EndpointConfig"] = endpoint unless endpoint.empty?
+
+        operations.network_connect(id: id, body: body)
+        self
+      end
+
+      # @param container [String, Docker::API::Container] the container
+      # @param force [Boolean] disconnect even if the container is running
+      # @return [self]
+      def disconnect(container, force: false)
+        operations.network_disconnect(
+          id: id, body: { "Container" => container_id(container), "Force" => force }
+        )
+        self
+      end
+
+      # @return [void]
+      def remove
+        operations.network_delete(id: id)
+        nil
+      end
+
+      private
+
+      # @param container [String, Docker::API::Container]
+      # @return [String]
+      def container_id(container)
+        container.respond_to?(:id) ? container.id : container.to_s
+      end
+    end
+  end
+end

data/lib/docker/api/resources/volume.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # A volume on the daemon.
+    #
+    # Volumes are identified by name rather than by a generated id, so {#id}
+    # and {#name} are the same value.
+    class Volume < Resource
+      # @return [String, nil] the volume's name
+      def name
+        raw["Name"]
+      end
+
+      # @return [String, nil] the volume's name, which is also its identifier
+      def id
+        name
+      end
+
+      # @return [String, nil] the driver backing this volume
+      def driver
+        detail("Driver")
+      end
+
+      # @return [String, nil] where the daemon keeps the volume's contents
+      def mountpoint
+        detail("Mountpoint")
+      end
+
+      # @return [Hash] the volume's labels
+      def labels
+        detail("Labels") || {}
+      end
+
+      # @return [self]
+      def reload
+        replace_raw(operations.volume_inspect(name: name).json)
+      end
+
+      # @param force [Boolean] remove even if the driver objects
+      # @return [void]
+      def remove(force: false)
+        operations.volume_delete(name: name, force: force)
+        nil
+      end
+    end
+  end
+end

data/lib/docker/api/response.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # What the daemon said, before anything has interpreted it.
+    #
+    # The status is kept alongside the body because Docker uses it to carry
+    # meaning: 204 for a successful delete, 304 for "already in that state".
+    # A layer that returned only a parsed body would throw that away.
+    class Response
+      # @return [Integer] the HTTP status
+      attr_reader :status
+
+      # @return [Hash{String => String}] response headers, downcased keys
+      attr_reader :headers
+
+      # @return [String] the raw body. Empty when the body was streamed to a
+      #   block instead of buffered.
+      attr_reader :body
+
+      # @param status [Integer] the HTTP status
+      # @param headers [Hash] response headers in any casing
+      # @param body [String, nil] the raw body
+      def initialize(status:, headers: {}, body: nil)
+        @status = Integer(status)
+        @headers = normalize(headers)
+        @body = body.to_s
+      end
+
+      # The body parsed as JSON.
+      #
+      # @return [Hash, Array, nil] the parsed body, or nil when there was none
+      # @raise [Docker::API::StreamError] if the body is not valid JSON
+      def json
+        return @json if defined?(@json)
+
+        @json = if body.empty?
+                  nil
+                else
+                  begin
+                    JSON.parse(body)
+                  rescue JSON::ParserError => e
+                    raise StreamError.new(
+                      "expected JSON from the daemon but could not parse it: #{e.message}",
+                      status: status, response: self
+                    )
+                  end
+                end
+      end
+
+      # The body parsed as JSON, when a document is required rather than
+      # merely hoped for.
+      #
+      # {#json} answers nil for an empty body, which is right: 204 and 304 are
+      # ordinary Docker answers and carry nothing. But most callers immediately
+      # index the result -- `.json["Id"]`, `.json["StatusCode"]` -- and against
+      # an empty body that is `NoMethodError: undefined method '[]' for nil`, a
+      # bare Ruby error escaping the hierarchy this gem promises is the only
+      # thing a caller has to rescue.
+      #
+      # Reaching this means a daemon, proxy or API-compatible shim answered a
+      # documented-success status with no body, so name that rather than
+      # letting a nil propagate to whichever accessor touches it first.
+      #
+      # @return [Hash, Array] the parsed body
+      # @raise [Docker::API::StreamError] if the body was empty or unparseable
+      def json!
+        parsed = json
+        return parsed unless parsed.nil?
+
+        raise StreamError.new(
+          "the daemon answered HTTP #{status} with an empty body, but this call needs a JSON document",
+          status: status, response: self
+        )
+      end
+
+      # @return [Boolean] whether the status is in the 2xx range
+      def success?
+        (200..299).cover?(status)
+      end
+
+      # @return [String, nil] the value of a header, case-insensitively
+      def [](name)
+        headers[name.to_s.downcase]
+      end
+
+      # @return [String]
+      def to_s
+        "#<Docker::API::Response status=#{status} bytes=#{body.bytesize}>"
+      end
+      alias_method :inspect, :to_s
+
+      private
+
+      # Header casing is not guaranteed by anything, so it is normalised once
+      # here rather than being guessed at every call site.
+      #
+      # @param headers [Hash]
+      # @return [Hash{String => String}]
+      def normalize(headers)
+        headers.each_with_object({}) do |(key, value), out|
+          out[key.to_s.downcase] = value.is_a?(Array) ? value.first : value
+        end.freeze
+      end
+    end
+  end
+end

data/lib/docker/api/session.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # A Net::HTTP that connects through a {Docker::API::Transport} rather than
+    # by dialling a hostname itself.
+    #
+    # Overriding `#connect` is the whole trick, and it is what makes a
+    # dependency-free client practical: the stdlib keeps doing the tedious,
+    # well-tested parts -- chunked transfer decoding, keep-alive, header
+    # parsing, 100-continue -- while we retain ownership of the socket. That
+    # ownership is what unix sockets, TLS and Windows named pipes all need, and
+    # it is why none of them requires an HTTP library that knows about Docker.
+    #
+    # @api private
+    class Session < Net::HTTP
+      class << self
+        # Net::HTTP.new is not a plain allocator: it resolves proxy settings
+        # and then re-dispatches to Class#new with its own positional
+        # arguments, which do not match ours. A session connects through a
+        # transport and never proxies, so that work is not merely unnecessary,
+        # it actively gets in the way.
+        #
+        # @param transport [Docker::API::Transport::Base] the transport to dial through
+        # @param read_timeout [Numeric] seconds to wait for response data
+        # @param open_timeout [Numeric] seconds to wait for the connection
+        # @return [Docker::API::Session]
+        def new(transport, read_timeout: 60, open_timeout: 10)
+          allocate.tap do |session|
+            session.send(:initialize, transport,
+              read_timeout: read_timeout, open_timeout: open_timeout)
+          end
+        end
+      end
+
+      # @param transport [Docker::API::Transport::Base] the transport to dial through
+      # @param read_timeout [Numeric] seconds to wait for response data
+      # @param open_timeout [Numeric] seconds to wait for the connection
+      def initialize(transport, read_timeout: 60, open_timeout: 10)
+        super(transport.host_header, 80)
+        @transport = transport
+        self.read_timeout = read_timeout
+        self.open_timeout = open_timeout
+      end
+
+      private
+
+      # Use the transport's socket instead of opening one.
+      #
+      # When TLS is in play the transport has already completed the handshake,
+      # so `use_ssl` stays false and Net::HTTP never tries to negotiate a
+      # second session over the top of the first.
+      #
+      # @return [void]
+      def connect
+        @socket = Net::BufferedIO.new(
+          @transport.connect,
+          read_timeout: @read_timeout,
+          write_timeout: @write_timeout,
+          continue_timeout: @continue_timeout,
+          debug_output: @debug_output
+        )
+        on_connect
+      end
+    end
+  end
+end

data/lib/docker/api/stream.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # Decoders for the three wire formats the Engine API streams in.
+    #
+    # All three are stateful accumulators, and that is the important part. HTTP
+    # hands us chunks at byte boundaries that have nothing to do with Docker's
+    # framing: a frame header can be split across two chunks and a JSON object
+    # can be split mid-string. A decoder that assumes a chunk is a message
+    # passes its tests and then interleaves garbage in production, which is
+    # precisely the bug class that makes `exec` output untrustworthy.
+    module Stream
+      # Docker's multiplexed frame header is eight bytes: a stream id, three
+      # bytes of padding, then a big-endian payload length.
+      HEADER_SIZE = 8
+
+      # Stream ids as they appear in the first header byte.
+      STREAM_NAMES = { 0 => :stdin, 1 => :stdout, 2 => :stderr }.freeze
+
+      # Splits Docker's multiplexed stdout/stderr framing back into named
+      # streams.
+      #
+      # Used whenever a container was created without a TTY. With a TTY the
+      # daemon sends unframed bytes instead, which is what {Raw} is for.
+      #
+      # @example
+      #   demux = Stream::Demultiplexer.new { |name, chunk| $stdout << chunk if name == :stdout }
+      #   demux << first_chunk << second_chunk
+      class Demultiplexer
+        # @yieldparam name [Symbol] one of :stdin, :stdout, :stderr
+        # @yieldparam chunk [String] the payload, in UTF-8
+        def initialize(&block)
+          raise ArgumentError, "Demultiplexer needs a block to yield frames to" unless block
+
+          @block = block
+          @buffer = +"".b
+        end
+
+        # Feed bytes in. Complete frames are yielded; a partial frame is held
+        # until the rest of it arrives.
+        #
+        # @param chunk [String] any number of bytes, at any boundary
+        # @return [self]
+        def <<(chunk)
+          @buffer << chunk.to_s.b
+          emit_frames
+          self
+        end
+
+        # @return [Boolean] whether bytes are being held back for a partial frame
+        def pending?
+          !@buffer.empty?
+        end
+
+        private
+
+        # @return [void]
+        def emit_frames
+          loop do
+            break if @buffer.bytesize < HEADER_SIZE
+
+            length = @buffer.byteslice(4, 4).unpack1("N")
+            break if @buffer.bytesize < HEADER_SIZE + length
+
+            stream = STREAM_NAMES.fetch(@buffer.getbyte(0), :unknown)
+            payload = @buffer.byteslice(HEADER_SIZE, length)
+            @buffer = @buffer.byteslice(HEADER_SIZE + length..) || +"".b
+
+            @block.call(stream, payload.force_encoding(Encoding::UTF_8))
+          end
+        end
+      end
+
+      # Parses the newline-delimited JSON that pull, push, build and /events
+      # stream their progress in.
+      #
+      # @example
+      #   lines = Stream::JSONLines.new { |event| puts event["status"] }
+      #   lines << chunk
+      class JSONLines
+        # @yieldparam object [Hash] one decoded JSON document
+        def initialize(&block)
+          raise ArgumentError, "JSONLines needs a block to yield objects to" unless block
+
+          @block = block
+          @buffer = +""
+        end
+
+        # @param chunk [String] any number of bytes, at any boundary
+        # @return [self]
+        # @raise [Docker::API::StreamError] if a complete line is not valid JSON
+        def <<(chunk)
+          @buffer << chunk.to_s
+          emit_lines
+          self
+        end
+
+        private
+
+        # @return [void]
+        def emit_lines
+          while (index = @buffer.index("\n"))
+            line = @buffer.slice!(0, index + 1).strip
+            next if line.empty?
+
+            @block.call(parse(line))
+          end
+        end
+
+        # @param line [String]
+        # @return [Hash]
+        def parse(line)
+          JSON.parse(line)
+        rescue JSON::ParserError => e
+          raise StreamError.new("the daemon sent a line that is not valid JSON: #{e.message}")
+        end
+      end
+
+      # Passes bytes straight through, for TTY-enabled streams and for raw
+      # archive downloads where there is no framing to undo.
+      class Raw
+        # @yieldparam chunk [String]
+        def initialize(&block)
+          raise ArgumentError, "Raw needs a block to yield chunks to" unless block
+
+          @block = block
+        end
+
+        # @param chunk [String]
+        # @return [self]
+        def <<(chunk)
+          @block.call(chunk)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/docker/api/tar.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+require "rubygems/package" unless defined?(Gem::Package)
+require "tempfile" unless defined?(Tempfile)
+
+module Docker
+  module API
+    # Packs a build context into the tar archive the daemon expects.
+    #
+    # RubyGems ships `Gem::Package::TarWriter` with every Ruby, so building a
+    # context needs no dependency and no shelling out to `tar` -- which also
+    # means the behaviour is identical on Windows, where there may be no `tar`
+    # to shell out to.
+    module Tar
+      module_function
+
+      # Pack a directory into an uncompressed tar archive.
+      #
+      # Written to a temporary file rather than a String. A build context is
+      # whatever the caller points at -- a Rails application with its assets, a
+      # monorepo subtree, a directory holding a model checkpoint -- and holding
+      # the whole archive in memory to send it costs its full size again on top
+      # of what the daemon is about to receive. The connection layer streams an
+      # IO body chunked, so the archive never has to be resident at all.
+      #
+      # @param directory [String] the build context root
+      # @param ignore [Array<String>, nil] patterns to exclude. Read from the
+      #   context's .dockerignore when not given.
+      # @return [File] the archive, rewound and ready to send
+      #
+      # @example
+      #   Tar.pack_directory("./app")
+      def pack_directory(directory, ignore: nil)
+        root = File.expand_path(directory)
+        raise ArgumentError, "build context #{directory} is not a directory" unless File.directory?(root)
+
+        patterns = ignore || read_dockerignore(root)
+        buffer = Tempfile.new(["docker-api-ng-context", ".tar"])
+        buffer.binmode
+
+        begin
+          Gem::Package::TarWriter.new(buffer) do |tar|
+            each_entry(root, patterns) do |absolute, relative|
+              add_entry(tar, absolute, relative)
+            end
+          end
+        rescue StandardError
+          buffer.close!
+          raise
+        end
+
+        buffer.rewind
+        buffer
+      end
+
+      # Pack a single in-memory Dockerfile into a context of its own.
+      #
+      # Useful for the common case of a short generated Dockerfile with no
+      # accompanying files, where writing a temporary directory first would be
+      # ceremony for its own sake.
+      #
+      # @param contents [String] the Dockerfile
+      # @param files [Hash{String => String}] additional files, path to content
+      # @return [StringIO] the archive, rewound and ready to send
+      def pack_dockerfile(contents, files: {})
+        buffer = StringIO.new(+"".b)
+
+        Gem::Package::TarWriter.new(buffer) do |tar|
+          write_file(tar, "Dockerfile", contents, 0o644)
+          files.each { |path, body| write_file(tar, path, body, 0o644) }
+        end
+
+        buffer.rewind
+        buffer
+      end
+
+      # @param root [String]
+      # @return [Array<String>] patterns from .dockerignore, or an empty list
+      def read_dockerignore(root)
+        path = File.join(root, ".dockerignore")
+        return [] unless File.readable?(path)
+
+        File.readlines(path, chomp: true)
+          .map(&:strip)
+          .reject { |line| line.empty? || line.start_with?("#") }
+      end
+
+      # Docker's ignore rules allow a later "!" pattern to re-include something
+      # an earlier pattern excluded, so the last matching rule wins rather than
+      # the first.
+      #
+      # @param relative [String] a context-relative path
+      # @param patterns [Array<String>]
+      # @return [Boolean] whether the path should be left out
+      def ignored?(relative, patterns)
+        decision = false
+
+        patterns.each do |pattern|
+          negated = pattern.start_with?("!")
+          candidate = negated ? pattern[1..] : pattern
+          decision = !negated if matches?(relative, candidate)
+        end
+
+        decision
+      end
+
+      # @param relative [String]
+      # @param pattern [String]
+      # @return [Boolean]
+      def matches?(relative, pattern)
+        pattern = pattern.chomp("/")
+        return true if File.fnmatch?(pattern, relative, File::FNM_PATHNAME)
+
+        # A directory pattern excludes everything beneath it.
+        File.fnmatch?("#{pattern}/**", relative, File::FNM_PATHNAME) ||
+          relative.start_with?("#{pattern}/")
+      end
+
+      # @return [void]
+      # @api private
+      def each_entry(root, patterns)
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: root).sort.each do |relative|
+          next if [".", ".."].include?(File.basename(relative))
+          next if ignored?(relative, patterns)
+
+          yield File.join(root, relative), relative
+        end
+      end
+
+      # @return [void]
+      # @api private
+      def add_entry(tar, absolute, relative)
+        stat = File.lstat(absolute)
+
+        if stat.directory?
+          tar.mkdir(relative, stat.mode)
+        elsif stat.symlink?
+          tar.add_symlink(relative, File.readlink(absolute), stat.mode)
+        elsif stat.file?
+          tar.add_file_simple(relative, stat.mode, stat.size) do |entry|
+            File.open(absolute, "rb") { |file| IO.copy_stream(file, entry) }
+          end
+        end
+      end
+
+      # @return [void]
+      # @api private
+      def write_file(tar, path, contents, mode)
+        bytes = contents.to_s.b
+        tar.add_file_simple(path, mode, bytes.bytesize) { |entry| entry.write(bytes) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    module Transport
+      # The contract every transport honours: make a socket, say what Host
+      # header requests over it should carry, and describe yourself for logs.
+      #
+      # Transports know how to dial, and nothing else. Keeping them this narrow
+      # is what makes the layer above testable -- {Docker::API::Transport::Fake}
+      # is a drop-in because there is so little to stand in for.
+      #
+      # @abstract Subclass and implement {#connect}.
+      class Base
+        # Open a connection.
+        #
+        # @return [IO] a connected, readable and writable socket
+        # @raise [Docker::API::ConnectionError] if the endpoint cannot be reached
+        def connect
+          raise NotImplementedError, "#{self.class} must implement #connect"
+        end
+
+        # The daemon does not route on Host, but HTTP/1.1 requires the header
+        # and some proxies in front of a daemon do care.
+        #
+        # @return [String]
+        def host_header
+          "localhost"
+        end
+
+        # @return [String] a description safe to put in a log line
+        def to_s
+          "#<#{self.class.name}>"
+        end
+        alias_method :inspect, :to_s
+
+        private
+
+        # Run a block that dials a socket, converting every way the operating
+        # system and OpenSSL report failure into one gem error.
+        #
+        # This is the boundary that stops `Errno::ECONNREFUSED` from appearing
+        # in a caller's rescue clause and coupling them to our plumbing.
+        #
+        # @param endpoint [String] what we were trying to reach, for the message
+        # @yieldreturn [IO]
+        # @return [IO]
+        # @raise [Docker::API::ConnectionError]
+        def dial(endpoint)
+          yield
+        rescue SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError, Timeout::Error => e
+          raise ConnectionError.new(
+            "could not connect to the Docker daemon at #{endpoint}: #{e.class}: #{e.message}"
+          )
+        end
+      end
+    end
+  end
+end