patient_http 1.6.1 → 1.7.0

data/VERSION

@@ -1 +1 @@
-1.6.1
+1.7.0

data/lib/patient_http/callback_args.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Container for callback arguments that are passed to completion and error callbacks.
+  # The callback arguments that a request passes to its `on_complete` and
+  # `on_error` callbacks.
   #
-  # CallbackArgs provides a structured way to access arguments passed from the original
-  # job to the callback workers. Arguments are stored with string keys internally
-  # (for JSON serialization compatibility) but can be accessed using either strings
-  # or symbols. All hash keys, including nested hashes and hashes within arrays, are
-  # deeply converted to strings.
+  # The arguments are stored with string keys, so they can be serialized to
+  # JSON. You can read them with string or symbol keys. The keys of nested
+  # hashes, including hashes in arrays, are converted to strings.
   #
-  # @example Basic usage
+  # @example Read arguments
   #   args = CallbackArgs.new(user_id: 123, action: "fetch")
   #   args[:user_id]      # => 123
   #   args["user_id"]     # => 123
@@ -17,30 +16,34 @@ module PatientHttp
   #   args.include?(:user_id)  # => true
   #   args.to_h           # => {user_id: 123, action: "fetch"}
   #
-  # @example Nested hashes
+  # @example Read a nested hash
   #   args = CallbackArgs.new(metadata: {tags: ["a", "b"], level: 1})
   #   args[:metadata]     # => {"tags" => ["a", "b"], "level" => 1}
   #
-  # @example From a response object
+  # @example Read arguments from a response
   #   response.callback_args[:user_id]
   class CallbackArgs
-    # JSON-native types that are allowed as values
+    # The JSON-native types that are allowed as values, in addition to `Array`
+    # and `Hash`.
     ALLOWED_TYPES = [NilClass, TrueClass, FalseClass, String, Integer, Float].freeze
 
     class << self
-      # Reconstruct a CallbackArgs from a hash (used during deserialization).
+      # Creates callback arguments from their serialized form. The values aren't
+      # validated.
       #
-      # @param hash [Hash, nil] hash with string keys
-      # @return [CallbackArgs] reconstructed CallbackArgs
+      # @param hash [Hash, nil] The hash from {#as_json}.
+      # @return [CallbackArgs] The callback arguments.
       def load(hash)
         new(hash || {}, validate: false)
       end
 
-      # Validate that a value is a JSON-native type (recursively for arrays and hashes).
+      # Validates that a value is a JSON-native type. Arrays and hashes are
+      # validated recursively.
       #
-      # @param value [Object] the value to validate
-      # @param path [String] the path to the value (for error messages)
-      # @raise [ArgumentError] if the value is not a JSON-native type
+      # @param value [Object] The value to validate.
+      # @param path [String] The path to the value, for the error message.
+      # @raise [ArgumentError] If the value isn't a JSON-native type, or if a hash
+      #   key isn't a String or Symbol.
       # @return [void]
       def validate_value!(value, path = "value")
         case value
@@ -63,10 +66,11 @@ module PatientHttp
         end
       end
 
-      # Deep convert all hash keys to strings, including nested hashes and hashes in arrays.
+      # Converts all hash keys to strings, including the keys of nested hashes
+      # and of hashes in arrays.
       #
-      # @param value [Object] the value to convert
-      # @return [Object] the converted value with all hash keys as strings
+      # @param value [Object] The value to convert.
+      # @return [Object] The value with string keys.
       def deep_stringify_keys(value)
         case value
         when Hash
@@ -79,12 +83,14 @@ module PatientHttp
       end
     end
 
-    # Initialize a CallbackArgs with a hash.
+    # Creates callback arguments.
     #
-    # @param args [Hash, nil] arguments to store (keys will be deeply converted to strings)
-    # @param validate [Boolean] whether to validate values are JSON-native types
-    # @raise [ArgumentError] if args is not nil and doesn't respond to to_h
-    # @raise [ArgumentError] if any value is not a JSON-native type (when validate is true)
+    # @param args [Hash, nil] The arguments. All keys are converted to strings.
+    # @param validate [Boolean] Whether to validate that the values are JSON-native
+    #   types.
+    # @raise [ArgumentError] If `args` isn't `nil` and doesn't respond to `to_h`.
+    # @raise [ArgumentError] If `validate` is `true` and a value isn't a
+    #   JSON-native type.
     def initialize(args = nil, validate: true)
       if args.nil?
         @data = {}
@@ -101,11 +107,11 @@ module PatientHttp
       end
     end
 
-    # Access an argument by key.
+    # Returns the value for a key.
     #
-    # @param key [String, Symbol] the key to access
-    # @return [Object] the value
-    # @raise [KeyError] if the key does not exist
+    # @param key [String, Symbol] The key.
+    # @return [Object] The value.
+    # @raise [KeyError] If the key doesn't exist.
     def [](key)
       string_key = key.to_s
       unless @data.include?(string_key)
@@ -115,60 +121,59 @@ module PatientHttp
       @data[string_key]
     end
 
-    # Access an argument by key with an optional default.
+    # Returns the value for a key, or a default value if the key doesn't exist.
     #
-    # @param key [String, Symbol] the key to access
-    # @param default [Object] the default value to return if key doesn't exist
-    # @return [Object] the value or default
+    # @param key [String, Symbol] The key.
+    # @param default [Object] The value to return if the key doesn't exist.
+    # @return [Object] The value, or the default value.
     def fetch(key, default = nil)
       @data.fetch(key.to_s, default)
     end
 
-    # Check if a key exists.
+    # Returns whether a key exists.
     #
-    # @param key [String, Symbol] the key to check
-    # @return [Boolean] true if the key exists
+    # @param key [String, Symbol] The key.
+    # @return [Boolean] `true` if the key exists.
     def include?(key)
       @data.include?(key.to_s)
     end
 
-    # Convert to a hash with symbol keys (shallow).
+    # Returns the arguments as a hash with symbol keys. Only the top-level keys
+    # are symbols. The keys of nested hashes stay strings.
     #
-    # Only top-level keys are symbolized. Nested hash keys remain as strings.
-    #
-    # @return [Hash] hash with symbol keys
+    # @return [Hash] The arguments.
     def to_h
       @data.transform_keys(&:to_sym)
     end
 
-    # Convert to hash with string keys for serialization.
+    # Returns the arguments as a JSON-compatible hash with string keys.
     #
-    # @return [Hash] hash with string keys
+    # @return [Hash] The serialized arguments.
     def as_json
       @data.dup
     end
 
     alias_method :dump, :as_json
 
-    # Check if there are no arguments.
+    # Returns whether there are no arguments.
     #
-    # @return [Boolean] true if empty
+    # @return [Boolean] `true` if there are no arguments.
     def empty?
       @data.empty?
     end
 
-    # Return the number of arguments.
+    # Returns the number of arguments.
     #
-    # @return [Integer] the count
+    # @return [Integer] The number of top-level keys.
     def size
       @data.size
     end
 
     alias_method :length, :size
 
-    # Return the keys.
+    # Returns the top-level keys.
     #
-    # @return [Array<String>] the keys
+    # @return [Array<String>] The keys.
     def keys
       @data.keys
     end

data/lib/patient_http/callback_validator.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 module PatientHttp
+  # Validates callback service classes and callback arguments.
+  #
+  # @api private
   module CallbackValidator
     class << self
-      # Validate that the callback class defines the required methods.
+      # Validates that the callback class defines the required methods.
       #
-      # @param callback [Class, String] the callback class or its name
+      # @param callback [Class, String] The callback service class, or its name.
       # @return [void]
-      # @raise [ArgumentError] if the callback class is invalid
+      # @raise [ArgumentError] If the class doesn't define `on_complete` and
+      #   `on_error` instance methods that take one argument.
       def validate!(callback)
         callback_class = callback.is_a?(Class) ? callback : ClassHelper.resolve_class_name(callback)
 
@@ -15,11 +19,11 @@ module PatientHttp
         validate_callback_method!(callback_class, :on_error)
       end
 
-      # Validate callback_args and convert to a hash with string keys.
+      # Validates the callback arguments and converts them to a hash with string keys.
       #
-      # @param callback_args [#to_h, nil] the callback arguments
-      # @return [Hash, nil] validated hash with string keys, or nil
-      # @raise [ArgumentError] if callback_args is invalid
+      # @param callback_args [#to_h, nil] The callback arguments.
+      # @return [Hash, nil] Validated hash with string keys, or nil.
+      # @raise [ArgumentError] If callback_args is invalid.
       def validate_callback_args(callback_args)
         return nil if callback_args.nil?
 

data/lib/patient_http/class_helper.rb

@@ -1,18 +1,17 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Helper module for class-related operations.
+  # Resolves class names to classes.
   #
-  # Provides utilities for resolving class names to class objects,
-  # which is useful for dynamic class loading.
+  # @api private
   module ClassHelper
     extend self
 
-    # Resolve a class from its name class name to the class object.
+    # Returns the class for a class name.
     #
-    # @param class_name [String] the fully qualified class name
-    # @return [Class, nil] the class object or nil if no class_name given
-    # @raise [NameError] if class cannot be found
+    # @param class_name [String] The fully qualified class name.
+    # @return [Class, nil] The class object or nil if no class_name given.
+    # @raise [NameError] If class cannot be found.
     def resolve_class_name(class_name)
       return class_name if class_name.is_a?(Class)
       return nil if class_name.nil? || class_name.empty?

data/lib/patient_http/client.rb

@@ -1,32 +1,34 @@
 # frozen_string_literal: true
 
 module PatientHttp
+  # Sends the requests of a {Processor} through a pool of HTTP clients.
+  #
+  # @api private
   class Client
+    include ImmediateRetries
+
+    # Creates a client for a processor.
+    #
+    # @param processor [Processor] The processor that owns the client.
     def initialize(processor)
       @processor = processor
-      @client_pool = ClientPool.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
-      )
+      @client_pool = ClientPool.from_config(config)
       @response_reader = ResponseReader.new(@processor)
       @request_preparer = RequestPreparer.new(config)
     end
 
-    # Make an asynchronous HTTP request.
+    # Makes an asynchronous HTTP request.
     #
     # The returned body is the array of raw (possibly compressed) body chunks;
     # use {#decode_response} to produce the final body string. Splitting the
     # decode out keeps CPU-bound work off the reactor thread.
     #
-    # @param request [Request] the request to make
-    # @param request_id [String] unique request identifier
-    # @return [Hash] the response data with keys for :status, :headers, and :body
+    # @param request [Request] The request to make.
+    # @param request_id [String] Unique request identifier.
+    # @return [Hash] The response data with keys for :status, :headers, and :body.
     def make_request(request, request_id)
       async_response = nil
+      client = nil
 
       begin
         outgoing = @request_preparer.prepare(request, request_id)
@@ -36,7 +38,10 @@ module PatientHttp
         timeout = request.timeout || config.request_timeout
 
         Async::Task.current.with_timeout(timeout) do
-          async_response = @client_pool.request(request.http_method, url, headers, body)
+          endpoint = Async::HTTP::Endpoint.parse(url)
+          async_response = request_with_immediate_retries(
+            @client_pool, request, endpoint, headers, body
+          ) { |pooled_client| client = pooled_client }
           # Note: headers that appear multiple times (e.g. set-cookie) are
           # flattened to a single joined string value.
           headers_hash = async_response.headers.to_h.transform_values(&:to_s)
@@ -49,17 +54,18 @@ module PatientHttp
           }
         end
       rescue => e
-        # Close the response and evict the client for this host to ensure the
-        # stale connection is not reused for subsequent requests.
+        # Close the response and evict the client that failed so its stale
+        # connections are not reused. Evicting by identity leaves a replacement
+        # client for the host alone.
         async_response&.close
-        if connection_error?(e)
-          @client_pool.evict(request.url)
+        if client && connection_error?(e)
+          @client_pool.evict(url, client)
         end
         raise
       end
     end
 
-    # Decode raw response data into deliverable response data.
+    # Decodes raw response data into deliverable response data.
     #
     # Joins and inflates the raw body chunks, applies the charset, and rewrites
     # the content-encoding header to name only the encodings still applied to
@@ -68,9 +74,9 @@ module PatientHttp
     # response always describes the body it carries. This is CPU-bound work
     # intended to run on a completion worker thread.
     #
-    # @param response_data [Hash] raw response data from {#make_request}
-    # @return [Hash] response data with the decoded body string
-    # @raise [ResponseTooLargeError] if the inflated body exceeds max_response_size
+    # @param response_data [Hash] Raw response data from {#make_request}.
+    # @return [Hash] Response data with the decoded body string.
+    # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
     def decode_response(response_data)
       headers = response_data[:headers]
       body = @response_reader.decode_body(response_data[:body], headers)
@@ -79,7 +85,7 @@ module PatientHttp
       response_data.merge(headers: headers, body: body)
     end
 
-    # Close all clients and release resources.
+    # Closes all clients and releases their resources.
     #
     # @return [void]
     def close

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?