patient_http 1.6.1 → 1.8.0

data/VERSION

@@ -1 +1 @@
-1.6.1
+1.8.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,40 @@
 # 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
+    # The request timeout limits the full exchange. The read timeout, if set,
+    # limits the wait for the response headers and the wait for each body
+    # chunk.
+    #
+    # @param request [Request] The request to make.
+    # @param request_id [String] Unique request identifier.
+    # @return [Hash] The response data with keys for :status, :headers, :body,
+    #   and :max_response_size. The size limit goes with the data so that
+    #   {#decode_response} applies the same limit to the inflated body.
     def make_request(request, request_id)
       async_response = nil
+      client = nil
 
       begin
         outgoing = @request_preparer.prepare(request, request_id)
@@ -34,32 +42,46 @@ module PatientHttp
         headers = outgoing.headers.to_h
         body = Protocol::HTTP::Body::Buffered.wrap([request.body.to_s]) if request.body
         timeout = request.timeout || config.request_timeout
+        read_timeout = request.read_timeout || config.read_timeout
+        max_response_size = request.max_response_size || config.max_response_size
 
         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 = ResponseReader.with_read_timeout(read_timeout) do
+            request_with_immediate_retries(
+              @client_pool, request, endpoint, headers, body
+            ) { |pooled_client| client = pooled_client }
+          end
           # 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)
-          body = @response_reader.read_raw_body(async_response, headers_hash)
+          body = @response_reader.read_raw_body(
+            async_response,
+            headers_hash,
+            max_response_size: max_response_size,
+            read_timeout: read_timeout
+          )
 
           {
             status: async_response.status,
             headers: headers_hash,
-            body: body
+            body: body,
+            max_response_size: max_response_size
           }
         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,18 +90,23 @@ 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 :status, :headers, and decoded
+    #   :body keys.
+    # @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)
+      body = @response_reader.decode_body(
+        response_data[:body],
+        headers,
+        max_response_size: response_data[:max_response_size]
+      )
       headers = ResponseReader.rewrite_content_encoding(headers)
 
-      response_data.merge(headers: headers, body: body)
+      response_data.except(:max_response_size).merge(headers: headers, body: body)
     end
 
-    # Close all clients and release resources.
+    # Closes all clients and releases their resources.
     #
     # @return [void]
     def close