docker-api-ng 0.3.0

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The networks on a daemon.
+    class Networks < Collection
+      # @param filters [Hash, nil] daemon-side filters
+      # @return [Array<Docker::API::Network>] partial resources
+      def all(filters: nil)
+        operations.network_list(filters: filters)
+          .json!.map { |payload| Network.new(client: client, raw: payload, partial: true) }
+      end
+
+      # @param id [String] a name or id
+      # @param verbose [Boolean] include service details
+      # @param scope [String, nil] "swarm", "global" or "local"
+      # @return [Docker::API::Network]
+      # @raise [Docker::API::NotFound] if there is no such network
+      def get(id, verbose: false, scope: nil)
+        Network.new(
+          client: client,
+          raw: operations.network_inspect(id: id, verbose: verbose, scope: scope).json,
+          partial: false
+        )
+      end
+
+      # Create a network.
+      #
+      # @param name [String] the network's name
+      # @param driver [String, nil] "bridge", "overlay", and so on
+      # @param ipv6 [Boolean] enable IPv6 addressing
+      # @param internal [Boolean] withhold external access
+      # @param attachable [Boolean] allow manual container attachment
+      # @param labels [Hash, nil] labels for the network
+      # @param ipam [Hash, nil] an IPAM configuration
+      # @param options [Hash, nil] driver-specific options
+      # @param attributes [Hash] any further body attributes
+      # @return [Docker::API::Network]
+      #
+      # @example
+      #   client.networks.create("dokken", ipv6: true,
+      #     ipam: { "Config" => [{ "Subnet" => "fd00::/64" }] })
+      def create(name, driver: nil, ipv6: false, internal: false, attachable: false,
+        labels: nil, ipam: nil, options: nil, **attributes)
+        body = Body.build(attributes).merge(
+          "Name" => name, "Driver" => driver, "EnableIPv6" => ipv6,
+          "Internal" => internal, "Attachable" => attachable,
+          "Labels" => labels, "IPAM" => ipam, "Options" => options
+        ).compact
+
+        get(operations.network_create(body: body).json!["Id"])
+      end
+
+      # Fetch a network by name, creating it if it does not exist.
+      #
+      # Two processes racing to create the same shared network is ordinary
+      # rather than exceptional -- parallel test suites do it constantly -- so
+      # losing that race is treated as success and the winner's network is
+      # returned.
+      #
+      # @param name [String] the network's name
+      # @param attributes [Hash] passed to {#create} when creating
+      # @return [Docker::API::Network]
+      def ensure(name, **attributes)
+        found = find(name)
+        return found if found
+
+        begin
+          create(name, **attributes)
+        rescue Conflict
+          get(name)
+        end
+      end
+
+      # @param filters [Hash, nil] which networks to consider
+      # @return [Hash] what was deleted
+      def prune(filters: nil)
+        operations.network_prune(filters: filters).json
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The daemon itself, rather than the things it holds.
+    #
+    # @example
+    #   client.system.info["ServerVersion"] #=> "29.7.2"
+    #   client.system.ping?                 #=> true
+    class System < Collection
+      # @return [Hash] the daemon's full description of itself
+      def info
+        operations.system_info.json
+      end
+
+      # @return [Hash] versions of the daemon and its components
+      def version
+        operations.system_version.json
+      end
+
+      # The Engine API version in use for this client, after negotiation.
+      #
+      # @return [String, nil]
+      def api_version
+        client.connection.api_version
+      end
+
+      # @return [Boolean] whether the daemon answered
+      def ping?
+        client.connection.ping.success?
+      rescue Error
+        false
+      end
+
+      # @return [Hash] disk usage by images, containers, volumes and cache
+      def data_usage(type: nil, verbose: false)
+        operations.system_data_usage(type: type, verbose: verbose).json
+      end
+
+      # Whether the daemon is Podman wearing Docker's API.
+      #
+      # Worth knowing, because Podman implements most of this API and diverges
+      # in enough places -- notably around networking and rootless behaviour --
+      # that callers sometimes need to branch on it.
+      #
+      # @return [Boolean]
+      def podman?
+        Array(version["Components"]).any? { |c| c["Name"].to_s.include?("Podman") }
+      end
+
+      # @return [Boolean] whether the daemon runs without root privileges
+      def rootless?
+        info["Rootless"] == true
+      end
+
+      # Stream events from the daemon as they happen.
+      #
+      # @param since [String, Integer, nil] where to start in the past
+      # @param until_time [String, Integer, nil] where to stop
+      # @param filters [Hash, nil] which events to report
+      # @yieldparam event [Hash] one event
+      # @return [void]
+      #
+      # @example
+      #   client.system.events(filters: { "type" => ["container"] }) do |event|
+      #     puts "#{event["Action"]} #{event.dig("Actor", "Attributes", "name")}"
+      #   end
+      def events(since: nil, until_time: nil, filters: nil, &block)
+        raise ArgumentError, "events needs a block to yield to" unless block
+
+        stream = Stream::JSONLines.new(&block)
+        operations.system_events(
+          since: since, until_: until_time, filters: filters
+        ) { |chunk| stream << chunk }
+        nil
+      end
+
+      # Check credentials against a registry.
+      #
+      # @param username [String] the account
+      # @param password [String] its password or token
+      # @param serveraddress [String, nil] the registry, or nil for Docker Hub
+      # @return [Hash] the daemon's answer
+      # @raise [Docker::API::Unauthorized] if the registry rejected them
+      def authenticate(username:, password:, serveraddress: nil)
+        operations.system_auth(
+          body: {
+            "username" => username, "password" => password,
+            "serveraddress" => serveraddress || Auth::DOCKER_HUB_KEY
+          }.compact
+        ).json
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+module Docker
+  module API
+    # The volumes on a daemon.
+    class Volumes < Collection
+      # @param filters [Hash, nil] daemon-side filters
+      # @return [Array<Docker::API::Volume>]
+      def all(filters: nil)
+        payload = operations.volume_list(filters: filters).json!
+        Array(payload["Volumes"]).map do |entry|
+          Volume.new(client: client, raw: entry, partial: false)
+        end
+      end
+
+      # @return [Array<String>] names of volumes the daemon could not inspect
+      def warnings(filters: nil)
+        Array(operations.volume_list(filters: filters).json!["Warnings"])
+      end
+
+      # @param name [String] the volume's name
+      # @return [Docker::API::Volume]
+      # @raise [Docker::API::NotFound] if there is no such volume
+      def get(name)
+        Volume.new(client: client, raw: operations.volume_inspect(name: name).json, partial: false)
+      end
+
+      # Create a volume.
+      #
+      # @param name [String, nil] a name, or nil to let the daemon choose one
+      # @param driver [String, nil] the driver to back it with
+      # @param labels [Hash, nil] labels for the volume
+      # @param driver_opts [Hash, nil] driver-specific options
+      # @return [Docker::API::Volume]
+      def create(name = nil, driver: nil, labels: nil, driver_opts: nil)
+        body = {
+          "Name" => name, "Driver" => driver,
+          "Labels" => labels, "DriverOpts" => driver_opts
+        }.compact
+
+        Volume.new(client: client, raw: operations.volume_create(body: body).json, partial: false)
+      end
+
+      # @param filters [Hash, nil] which volumes to consider
+      # @return [Hash] what was deleted and how much space it freed
+      def prune(filters: nil)
+        operations.volume_prune(filters: filters).json
+      end
+    end
+  end
+end

data/lib/docker/api/config.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+#
+# Copyright 2026 Tim Smith
+# SPDX-License-Identifier: Apache-2.0
+
+require "rbconfig" unless defined?(RbConfig)
+
+module Docker
+  module API
+    # Where the daemon is and how to reach it, resolved once and then frozen.
+    #
+    # Frozen is the point. The docker-api gem exposes `Docker.url=` and
+    # `Docker.creds=` as process-global setters, so a second caller silently
+    # inherits -- or clobbers -- the first caller's daemon. Configuration here
+    # is a value: two clients hold two of them and cannot interfere.
+    class Config
+      # Where Docker listens by default on Linux and macOS.
+      DEFAULT_UNIX_SOCKET = "unix:///var/run/docker.sock"
+
+      # Where Docker Desktop for Windows listens by default.
+      DEFAULT_WINDOWS_PIPE = "npipe:////./pipe/docker_engine"
+
+      # @return [String] the daemon URL
+      attr_reader :url
+
+      # @return [Hash] TLS material, empty when TLS is not in use
+      attr_reader :tls
+
+      # @return [String, Symbol] `:negotiate`, `:none`, or a pinned version
+      attr_reader :api_version
+
+      # @return [Numeric] seconds to wait for response data
+      attr_reader :read_timeout
+
+      # @return [Numeric] seconds to wait for a connection
+      attr_reader :open_timeout
+
+      # @param url [String, nil] the daemon URL
+      # @param tls [Hash, nil] TLS material
+      # @param api_version [String, Symbol] version handling
+      # @param read_timeout [Numeric] seconds
+      # @param open_timeout [Numeric] seconds
+      def initialize(url: nil, tls: nil, api_version: :negotiate,
+        read_timeout: 60, open_timeout: 10)
+        @url = url || self.class.default_url
+        @tls = (tls || {}).freeze
+        @api_version = api_version
+        @read_timeout = read_timeout
+        @open_timeout = open_timeout
+        freeze
+      end
+
+      # Resolve configuration the way the Docker CLI does.
+      #
+      # @param env [Hash] the environment to read, injectable for tests
+      # @return [Docker::API::Config]
+      #
+      # @example
+      #   Config.from_env("DOCKER_HOST" => "tcp://build:2376",
+      #                   "DOCKER_CERT_PATH" => "/certs",
+      #                   "DOCKER_TLS_VERIFY" => "1")
+      def self.from_env(env = ENV, **overrides)
+        # Ruby permits non-Symbol keys in a **kwargs splat, so
+        # `from_env("DOCKER_HOST" => "tcp://x")` puts the variable in overrides
+        # and quietly reads the real environment instead. Saying so is much
+        # kinder than resolving the wrong daemon and never mentioning it.
+        stray = overrides.keys.grep(String)
+        unless stray.empty?
+          raise ArgumentError,
+            "from_env takes the environment as its first argument: " \
+            "from_env({ #{stray.first.inspect} => ... }). Got #{stray.inspect} as options."
+        end
+
+        # Resolution order, matching the CLI: an explicit argument, then
+        # DOCKER_HOST, then the active context, then the platform default.
+        #
+        # `docker context use` exports nothing -- it writes currentContext into
+        # config.json -- so a client that skips the store disagrees with the
+        # CLI on the same machine and falls back to /var/run/docker.sock, which
+        # Colima, Rancher Desktop, rootless Docker and Podman generally do not
+        # create. The store is only consulted when nothing more explicit has
+        # already answered, so this cannot change what an existing caller resolves.
+        context = if overrides[:url].nil? && blank?(env["DOCKER_HOST"]) && blank?(env["DOCKER_URL"])
+                    Context.resolve(env)
+                  end
+
+        # presence, not a bare ||: an exported-but-empty DOCKER_HOST is truthy
+        # in Ruby, so it would beat the context and then resolve to the default
+        # socket anyway. The CLI treats an empty value as unset.
+        url = overrides[:url] || presence(env["DOCKER_HOST"]) || presence(env["DOCKER_URL"]) ||
+          context&.[](:url) || default_url
+
+        tls = if overrides.key?(:tls)
+                overrides[:tls]
+              else
+                from_env = tls_from_env(env)
+                from_env.empty? ? (context&.[](:tls) || {}) : from_env
+              end
+
+        new(
+          url: url,
+          tls: tls,
+          api_version: overrides.fetch(:api_version, env["DOCKER_API_VERSION"] || :negotiate),
+          read_timeout: overrides.fetch(:read_timeout, 60),
+          open_timeout: overrides.fetch(:open_timeout, 10)
+        )
+      end
+
+      # @return [String] the platform's default daemon URL
+      def self.default_url
+        windows? ? DEFAULT_WINDOWS_PIPE : DEFAULT_UNIX_SOCKET
+      end
+
+      # @return [Boolean]
+      # @api private
+      def self.blank?(value)
+        value.nil? || value.empty?
+      end
+      private_class_method :blank?
+
+      # @return [String, nil] the value, or nil when it is absent or empty
+      # @api private
+      def self.presence(value)
+        blank?(value) ? nil : value
+      end
+      private_class_method :presence
+
+      # @return [Boolean]
+      def self.windows?
+        RbConfig::CONFIG["host_os"].match?(/mswin|mingw|cygwin/)
+      end
+
+      # Build TLS material from `DOCKER_CERT_PATH`, which is the only way the
+      # CLI expresses it.
+      #
+      # `DOCKER_TLS_VERIFY` is a presence flag rather than a boolean: the CLI
+      # treats an empty value as "off", so an exported-but-empty variable does
+      # not silently start verifying.
+      #
+      # @param env [Hash]
+      # @return [Hash]
+      def self.tls_from_env(env)
+        cert_path = env["DOCKER_CERT_PATH"]
+        return {} if cert_path.nil? || cert_path.empty?
+
+        {
+          ca_file: File.join(cert_path, "ca.pem"),
+          cert_file: File.join(cert_path, "cert.pem"),
+          key_file: File.join(cert_path, "key.pem"),
+          verify: !env["DOCKER_TLS_VERIFY"].to_s.empty?,
+        }
+      end
+      private_class_method :tls_from_env
+
+      # @return [String]
+      def to_s
+        "#<Docker::API::Config url=#{url} tls=#{tls.empty? ? "none" : "configured"} " \
+          "api_version=#{api_version}>"
+      end
+      alias_method :inspect, :to_s
+    end
+  end
+end