Add unix:/// base_url support for Docker socket transportFeat/unix socket base url (#15)

* Add unix socket support for unix:/// base_url

* Document unix socket base_url usage

* Fix unix socket Net::HTTP initializer compatibility

Author: corsicanec82

README.md

@@ -37,6 +37,18 @@ create_response = docker.containers.create(name: "sample-container")
 puts(create_response.Id)
 ```
 
+### Using a Unix socket
+
+You can connect to a local Docker daemon over a Unix socket by setting `base_url` to a `unix:///...` path:
+
+```ruby
+docker = DockerEngineRuby::Client.new(
+  base_url: "unix:///var/run/docker.sock"
+)
+```
+
+When `base_url` uses `unix:///`, TLS-related options are not used. TLS/mTLS configuration applies to HTTPS daemon endpoints (for example, `https://localhost:2376`).
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `DockerEngineRuby::Errors::APIError` will be thrown:

lib/docker_engine_ruby/internal/transport/base_client.rb

@@ -212,7 +212,13 @@ def initialize(
           tls_client_cert_path: nil,
           tls_client_key_path: nil
         )
+          parsed_base_url = DockerEngineRuby::Internal::Util.parse_uri(base_url)
+          @unix_socket_path = parsed_base_url[:scheme] == "unix" ? parsed_base_url[:path] : nil
+          if parsed_base_url[:scheme] == "unix" && @unix_socket_path.to_s.empty?
+            raise ArgumentError.new("base_url unix:// must include an absolute socket path")
+          end
           @requester = DockerEngineRuby::Internal::Transport::PooledNetRequester.new(
+            unix_socket_path: @unix_socket_path,
             tls_ca_cert_path: tls_ca_cert_path,
             tls_client_cert_path: tls_client_cert_path,
             tls_client_key_path: tls_client_key_path
@@ -226,8 +232,13 @@ def initialize(
             },
             headers
           )
-          @base_url_components = DockerEngineRuby::Internal::Util.parse_uri(base_url)
-          @base_url = DockerEngineRuby::Internal::Util.unparse_uri(@base_url_components)
+          @base_url_components =
+            if @unix_socket_path
+              DockerEngineRuby::Internal::Util.parse_uri("http://localhost")
+            else
+              parsed_base_url
+            end
+          @base_url = base_url
           @idempotency_header = idempotency_header&.to_s&.downcase
           @timeout = timeout
           @max_retries = max_retries
@@ -328,6 +339,7 @@ def initialize(
           {
             method: method,
             url: url,
+            unix_socket_path: @unix_socket_path,
             headers: headers,
             body: encoded,
             max_retries: opts.fetch(:max_retries, @max_retries),
@@ -590,6 +602,7 @@ def inspect
             {
               method: Symbol,
               url: URI::Generic,
+              unix_socket_path: T.nilable(String),
               headers: T::Hash[String, String],
               body: T.anything,
               max_retries: Integer,

lib/docker_engine_ruby/internal/transport/pooled_net_requester.rb

@@ -7,6 +7,23 @@ module Transport
       class PooledNetRequester
         extend DockerEngineRuby::Internal::Util::SorbetRuntimeSupport
 
+        class UnixSocketHTTP < Net::HTTP
+          # Net::HTTP.new forwards multiple args to #initialize.
+          # We only care about socket_path and ignore the rest.
+          def initialize(socket_path, *_rest)
+            super("localhost", Net::HTTP.http_default_port)
+            @socket_path = socket_path
+          end
+
+          private def connect
+            raise ArgumentError.new("TLS over unix sockets is not supported") if use_ssl?
+
+            @socket = Net::BufferedIO.new(UNIXSocket.new(@socket_path))
+            @last_communicated = nil
+            on_connect
+          end
+        end
+
         # from the golang stdlib
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
@@ -19,10 +36,17 @@ class << self
           # @param cert_store [OpenSSL::X509::Store]
           # @param tls_cert [OpenSSL::X509::Certificate, nil]
           # @param tls_key [OpenSSL::PKey::PKey, nil]
+          # @param unix_socket_path [String, nil]
           # @param url [URI::Generic]
           #
           # @return [Net::HTTP]
-          def connect(cert_store:, tls_cert:, tls_key:, url:)
+          def connect(cert_store:, tls_cert:, tls_key:, unix_socket_path:, url:)
+            if unix_socket_path
+              return UnixSocketHTTP.new(unix_socket_path).tap do
+                _1.use_ssl = false
+                _1.max_retries = 0
+              end
+            end
             port =
               case [url.port, url.scheme]
               in [Integer, _]
@@ -100,18 +124,25 @@ def build_request(request, &blk)
         # @api private
         #
         # @param url [URI::Generic]
+        # @param unix_socket_path [String, nil]
         # @param deadline [Float]
         # @param blk [Proc]
         #
         # @raise [Timeout::Error]
         # @yieldparam [Net::HTTP]
-        private def with_pool(url, deadline:, &blk)
-          origin = DockerEngineRuby::Internal::Util.uri_origin(url)
+        private def with_pool(url, unix_socket_path:, deadline:, &blk)
+          origin = unix_socket_path || DockerEngineRuby::Internal::Util.uri_origin(url)
           timeout = deadline - DockerEngineRuby::Internal::Util.monotonic_secs
           pool =
             @mutex.synchronize do
               @pools[origin] ||= ConnectionPool.new(size: @size) do
-                self.class.connect(cert_store: @cert_store, tls_cert: @tls_cert, tls_key: @tls_key, url: url)
+                self.class.connect(
+                  cert_store: @cert_store,
+                  tls_cert: @tls_cert,
+                  tls_key: @tls_key,
+                  unix_socket_path: unix_socket_path,
+                  url: url
+                )
               end
             end
 
@@ -135,6 +166,7 @@ def build_request(request, &blk)
         # @return [Array(Integer, Net::HTTPResponse, Enumerable<String>)]
         def execute(request)
           url, deadline = request.fetch_values(:url, :deadline)
+          unix_socket_path = request.fetch(:unix_socket_path, @default_unix_socket_path)
 
           req = nil
           finished = false
@@ -143,7 +175,7 @@ def execute(request)
           enum = Enumerator.new do |y|
             next if finished
 
-            with_pool(url, deadline: deadline) do |conn|
+            with_pool(url, unix_socket_path: unix_socket_path, deadline: deadline) do |conn|
               eof = false
               closing = nil
               ::Thread.handle_interrupt(Object => :never) do
@@ -203,14 +235,17 @@ def execute(request)
         # @param tls_ca_cert_path [String, nil]
         # @param tls_client_cert_path [String, nil]
         # @param tls_client_key_path [String, nil]
+        # @param unix_socket_path [String, nil]
         def initialize(
           size: self.class::DEFAULT_MAX_CONNECTIONS,
+          unix_socket_path: nil,
           tls_ca_cert_path: nil,
           tls_client_cert_path: nil,
           tls_client_key_path: nil
         )
           @mutex = Mutex.new
           @size = size
+          @default_unix_socket_path = unix_socket_path
           @cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
           @cert_store.add_file(tls_ca_cert_path) if tls_ca_cert_path
 
@@ -230,7 +265,16 @@ def initialize(
         end
 
         define_sorbet_constant!(:Request) do
-          T.type_alias { {method: Symbol, url: URI::Generic, headers: T::Hash[String, String], body: T.anything, deadline: Float} }
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              unix_socket_path: T.nilable(String),
+              headers: T::Hash[String, String],
+              body: T.anything,
+              deadline: Float
+            }
+          end
         end
       end
     end

test/docker_engine_ruby/client_test.rb

@@ -372,6 +372,36 @@ def test_non_redirect_304_is_treated_as_status_error_for_other_operations
     assert_equal(304, error.status)
   end
 
+  def test_client_unix_base_url_routes_requests_through_unix_socket_path
+    response_class = Struct.new(:headers) do
+      def each_header = headers.each
+    end
+    requester_class = Class.new do
+      attr_reader :last_request
+
+      define_method(:initialize) { |response| @response = response }
+      define_method(:execute) do |request|
+        @last_request = request
+        [200, @response, ["[]"]]
+      end
+    end
+    requester = requester_class.new(response_class.new({"content-type" => "application/json"}))
+
+    docker = DockerEngineRuby::Client.new(base_url: "unix:///var/run/docker.sock")
+    docker.instance_variable_set(:@requester, requester)
+
+    docker.containers.list
+
+    assert_equal("/var/run/docker.sock", requester.last_request[:unix_socket_path])
+    assert_equal("http://localhost/containers/json", requester.last_request[:url].to_s)
+  end
+
+  def test_client_unix_base_url_requires_socket_path
+    assert_raises(ArgumentError) do
+      DockerEngineRuby::Client.new(base_url: "unix://")
+    end
+  end
+
   def test_default_headers
     stub_request(:get, "http://localhost/containers/json").to_return_json(status: 200, body: {})