patient_http 1.6.1 → 1.8.0

data/lib/patient_http/client_pool.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Pool of HTTP clients with LRU eviction.
+  # A pool of HTTP clients, one for each host.
   #
-  # Maintains a pool of clients lazily instantiated for each host. The pool
-  # is capped with an LRU algorithm - when a new client is needed and the
-  # pool is at capacity, the least recently used client is closed and removed.
+  # A client is created when a host first needs one. When the pool is full and
+  # a new client is needed, the least recently used client is closed and
+  # removed.
+  #
+  # @api private
   class ClientPool
     # Supported protocol names mapped to their async-http implementations. Forcing
     # :http1 also limits the TLS ALPN advertisement to http/1.1, which avoids
@@ -15,7 +17,40 @@ module PatientHttp
       http2: Async::HTTP::Protocol::HTTP2
     }.freeze
 
-    def initialize(max_size:, connection_timeout: nil, proxy_url: nil, retries: 3, protocol: nil, connection_limit: nil)
+    class << self
+      # Builds a pool with the connection settings from a configuration.
+      #
+      # @param config [Configuration] The configuration to read settings from.
+      # @return [ClientPool] The new pool.
+      def from_config(config)
+        new(
+          max_size: config.connection_pool_size,
+          connection_timeout: config.connection_timeout,
+          proxy_url: config.proxy_url,
+          retries: config.retries,
+          protocol: config.protocol,
+          connection_limit: config.max_connections_per_host,
+          tcp_keepalive: config.tcp_keepalive,
+          tcp_user_timeout: config.tcp_user_timeout
+        )
+      end
+    end
+
+    # Creates a client pool.
+    #
+    # @param max_size [Integer] The maximum number of host clients in the pool.
+    # @param connection_timeout [Numeric, nil] The timeout in seconds to open a
+    #   connection.
+    # @param proxy_url [String, nil] The HTTP or HTTPS proxy URL.
+    # @param retries [Integer] The number of retries for failed requests.
+    # @param protocol [Symbol, nil] The HTTP protocol: `:http1` or `:http2`.
+    # @param connection_limit [Integer, nil] The maximum number of connections
+    #   to each host.
+    # @param tcp_keepalive [Integer, Hash, nil] The TCP keepalive settings.
+    # @param tcp_user_timeout [Numeric, nil] The TCP user timeout in seconds.
+    # @raise [ArgumentError] If the protocol isn't supported.
+    def initialize(max_size:, connection_timeout: nil, proxy_url: nil, retries: 3, protocol: nil,
+      connection_limit: nil, tcp_keepalive: nil, tcp_user_timeout: nil)
       if protocol && !PROTOCOLS.include?(protocol)
         raise ArgumentError.new("protocol must be one of #{PROTOCOLS.keys.inspect}, got: #{protocol.inspect}")
       end
@@ -23,20 +58,26 @@ module PatientHttp
       @clients = {}
       @max_size = max_size
       @connection_timeout = connection_timeout
+      @tcp_keepalive = tcp_keepalive.is_a?(Numeric) ? {idle: tcp_keepalive} : tcp_keepalive
+      @tcp_user_timeout = tcp_user_timeout
       @proxy_url = proxy_url
       @retries = retries
       @protocol = protocol
       @connection_limit = connection_limit
       @mutex = Mutex.new
       @proxy_client = nil
+      @closing_tasks = []
+      @closing_mutex = Mutex.new
     end
 
-    attr_reader :max_size, :connection_timeout, :proxy_url, :retries, :protocol, :connection_limit
+    # @return [Object] The connection settings that the pool was created with.
+    attr_reader :max_size, :connection_timeout, :proxy_url, :retries, :protocol, :connection_limit,
+      :tcp_keepalive, :tcp_user_timeout
 
-    # Get or create a client for the given endpoint.
+    # Returns or creates a client for the given endpoint.
     #
-    # @param endpoint [Async::HTTP::Endpoint] the target endpoint
-    # @return [Async::HTTP::Client] the client for the endpoint's host
+    # @param endpoint [Async::HTTP::Endpoint] The target endpoint.
+    # @return [Async::HTTP::Client] The client for the endpoint's host.
     def client_for(endpoint)
       key = host_key(endpoint)
 
@@ -53,17 +94,20 @@ module PatientHttp
       end
     end
 
-    # Make a request.
+    # Makes a request.
     #
-    # @param http_method [String, Symbol] HTTP method
-    # @param url [String] request URL
-    # @param headers [Hash] request headers
-    # @param body [String, nil] request body
-    # @param block [Proc] optional block to process the response
-    # @return [Protocol::HTTP::Response] the response
-    def request(http_method, url, headers, body, &block)
-      endpoint = Async::HTTP::Endpoint.parse(url)
-      client = client_for(endpoint)
+    # @param http_method [String, Symbol] HTTP method.
+    # @param url [String, Async::HTTP::Endpoint] Request URL, or the endpoint
+    #   already parsed from it.
+    # @param headers [Hash] Request headers.
+    # @param body [String, nil] Request body.
+    # @param client [Async::HTTP::Client, nil] The pooled client to send through,
+    #   normally the one {#client_for} returned for the URL; nil looks it up.
+    # @param block [Proc] Optional block to process the response.
+    # @return [Protocol::HTTP::Response] The response.
+    def request(http_method, url, headers, body, client: nil, &block)
+      endpoint = url.is_a?(Async::HTTP::Endpoint) ? url : Async::HTTP::Endpoint.parse(url)
+      client ||= client_for(endpoint)
 
       verb = http_method.to_s.upcase
 
@@ -86,7 +130,10 @@ module PatientHttp
       end
     end
 
-    # Close all clients and release resources.
+    # Closes all clients and releases their resources.
+    #
+    # Clients evicted earlier whose close is still waiting for their in-flight
+    # requests are waited on as well, so no connection outlives the pool.
     #
     # @return [void]
     def close
@@ -105,29 +152,39 @@ module PatientHttp
         end
         @proxy_client = nil
       end
+
+      pending = @closing_mutex.synchronize { @closing_tasks.dup }
+      pending.each do |task|
+        task.wait
+      rescue StandardError, Async::Stop
+        nil
+      end
     end
 
-    # Evict and close the client for the given URL.
+    # Evicts and closes the client for the host of a URL.
     #
     # This forces a new connection to be established on the next request to this host.
+    # When the client that failed is given, only that client is evicted: a
+    # replacement installed for the host after an earlier eviction is left alone,
+    # so a late failure on the old client cannot discard a healthy new one.
     #
-    # @param url [String] the request URL whose host client should be evicted
+    # @param url [String] The request URL whose host client should be evicted.
+    # @param client [Async::HTTP::Client, nil] The client that failed, or nil to
+    #   evict whichever client the pool currently holds for the host.
     # @return [void]
-    def evict(url)
+    def evict(url, client = nil)
       endpoint = Async::HTTP::Endpoint.parse(url)
       key = host_key(endpoint)
 
-      @mutex.synchronize do
-        client = @clients.delete(key)
-        begin
-          client&.close
-        rescue
-          nil
+      evicted = @mutex.synchronize do
+        if client.nil? || @clients[key].equal?(client)
+          @clients.delete(key)
         end
       end
+      close_later(evicted) if evicted
     end
 
-    # @return [Integer] number of clients in the pool
+    # @return [Integer] Number of clients in the pool.
     def size
       @mutex.synchronize { @clients.size }
     end
@@ -139,10 +196,29 @@ module PatientHttp
       return unless lru_key
 
       @clients.delete(lru_key)
-      begin
-        lru_client.close
+      close_later(lru_client)
+    end
+
+    # Closing a client waits for its in-flight requests to finish before closing
+    # their connections. Evictions run on a request task while other requests are
+    # waiting to be dispatched, so the close runs in its own task and neither the
+    # evicting request nor the pool mutex waits for it. Outside a reactor the
+    # block runs inline.
+    #
+    # The task is transient so it does not hold the evicting request's task
+    # open, and it is tracked so {#close} can wait for it. The tracking list has
+    # its own mutex because evictions spawn the task while holding the pool mutex.
+    def close_later(client)
+      task = Async(transient: true) do |current|
+        client.close
       rescue
         nil
+      ensure
+        @closing_mutex.synchronize { @closing_tasks.delete(current) }
+      end
+
+      unless task.finished?
+        @closing_mutex.synchronize { @closing_tasks << task }
       end
     end
 
@@ -158,12 +234,16 @@ module PatientHttp
       # Response bodies are decoded by ResponseReader on a completion worker
       # thread instead of a Protocol::HTTP::AcceptEncoding wrapper, so the
       # reactor thread never pays for inflating compressed bodies.
+      #
+      # Each client makes a single attempt per request. Retries, bounded by the
+      # pool's retries setting, are applied by ImmediateRetries so that only
+      # one layer decides when a request is sent again.
       @proxy_url ? make_proxied_client(endpoint) : make_direct_client(endpoint)
     end
 
     def make_direct_client(endpoint)
-      configured_endpoint = configure_endpoint(endpoint)
-      Async::HTTP::Client.new(configured_endpoint, retries: @retries, **client_options)
+      configured_endpoint = connectable_endpoint(configure_endpoint(endpoint))
+      Async::HTTP::Client.new(configured_endpoint, retries: 1, **client_options)
     end
 
     def make_proxied_client(endpoint)
@@ -173,7 +253,8 @@ module PatientHttp
       configured_endpoint = configure_endpoint(endpoint)
 
       proxy = @proxy_client.proxy(configured_endpoint)
-      Async::HTTP::Client.new(proxy.wrap_endpoint(configured_endpoint), retries: @retries, **client_options)
+      tunneled_endpoint = connectable_endpoint(proxy.wrap_endpoint(configured_endpoint))
+      Async::HTTP::Client.new(tunneled_endpoint, retries: 1, **client_options)
     end
 
     def client_options
@@ -182,15 +263,29 @@ module PatientHttp
 
     def create_proxy_client
       proxy_endpoint = Async::HTTP::Endpoint.parse(@proxy_url)
-      if @connection_timeout
-        proxy_endpoint = Async::HTTP::Endpoint.new(proxy_endpoint.url, timeout: @connection_timeout)
+      Async::HTTP::Client.new(connectable_endpoint(proxy_endpoint))
+    end
+
+    # The connection timeout is enforced by the wrapper around establishing the
+    # connection rather than passed to the endpoint, which would set it as an IO
+    # timeout on every read and write for the life of the connection. The
+    # wrapper also applies the TCP keepalive and user timeout settings to each
+    # new socket.
+    def connectable_endpoint(endpoint)
+      unless @connection_timeout || @tcp_keepalive || @tcp_user_timeout
+        return endpoint
       end
-      Async::HTTP::Client.new(proxy_endpoint)
+
+      ConnectionEndpoint.new(
+        endpoint,
+        connection_timeout: @connection_timeout,
+        tcp_keepalive: @tcp_keepalive,
+        tcp_user_timeout: @tcp_user_timeout
+      )
     end
 
     def configure_endpoint(endpoint)
       options = {}
-      options[:timeout] = @connection_timeout if @connection_timeout
       options[:protocol] = PROTOCOLS.fetch(@protocol) if @protocol
       return endpoint if options.empty?
 

data/lib/patient_http/completion_executor.rb

@@ -10,13 +10,13 @@ module PatientHttp
   #
   # @api private
   class CompletionExecutor
-    # Initialize the executor and start its worker threads.
+    # Creates the executor and starts its worker threads.
     #
-    # @param threads [Integer] number of worker threads
-    # @param logger [Logger, nil] logger for unexpected job errors
-    # @param thread_name_prefix [String] prefix for worker thread names
-    # @param on_finished [#call, nil] invoked after each job completes, outside
-    #   any executor lock, so the owner can re-check idle conditions
+    # @param threads [Integer] Number of worker threads.
+    # @param logger [Logger, nil] Logger for unexpected job errors.
+    # @param thread_name_prefix [String] Prefix for worker thread names.
+    # @param on_finished [#call, nil] Invoked after each job completes, outside
+    #   any executor lock, so the owner can re-check idle conditions.
     def initialize(threads:, logger: nil, thread_name_prefix: "patient-http-completion", on_finished: nil)
       @queue = Thread::Queue.new
       @logger = logger
@@ -34,10 +34,10 @@ module PatientHttp
       end
     end
 
-    # Enqueue a job for execution.
+    # Enqueues a job for execution.
     #
-    # @param job [#call] the job to run
-    # @raise [ClosedQueueError] if the executor has been shut down
+    # @param job [#call] The job to run.
+    # @raise [ClosedQueueError] If the executor has been shut down.
     # @return [void]
     def enqueue(job)
       @mutex.synchronize { @outstanding += 1 }
@@ -50,30 +50,30 @@ module PatientHttp
       nil
     end
 
-    # Check whether the executor has no queued or running jobs.
+    # Returns whether the executor has no queued or running jobs.
     #
     # @return [Boolean]
     def idle?
       @mutex.synchronize { @outstanding == 0 }
     end
 
-    # Check whether the given thread is one of this executor's workers.
+    # Returns whether the given thread is one of this executor's workers.
     #
-    # @param thread [Thread] the thread to check
+    # @param thread [Thread] The thread to check.
     # @return [Boolean]
     def worker_thread?(thread = Thread.current)
       @threads.include?(thread)
     end
 
-    # Shut down the executor: close the queue so workers drain remaining jobs
-    # and exit, then join them within the timeout. Workers still alive after
-    # the deadline are killed; their tasks remain durably tracked and are
-    # recovered by the owner's re-enqueue logic.
+    # Shuts down the executor. The queue is closed, so the workers run the
+    # remaining jobs and exit. The executor waits for the workers until the
+    # timeout, and then kills the workers that are still alive. Their tasks
+    # stay tracked, and the owner re-enqueues them.
     #
-    # Safe to call more than once and from a worker thread itself (the
-    # current thread is never joined or killed).
+    # You can call this method more than once, and from a worker thread. The
+    # current thread is never joined or killed.
     #
-    # @param timeout [Numeric] seconds to wait for workers to drain
+    # @param timeout [Numeric] Seconds to wait for workers to drain.
     # @return [void]
     def shutdown(timeout: 5)
       @queue.close
@@ -96,7 +96,7 @@ module PatientHttp
 
     private
 
-    # Drop jobs left in the closed queue by workers that were killed at the
+    # Drops jobs left in the closed queue by workers that were killed at the
     # shutdown deadline. Those jobs can never run, so they must stop counting
     # against the outstanding total or the executor would never report itself
     # idle again.