patient_http 1.6.1 → 1.8.0

data/lib/patient_http/request.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Represents an async HTTP request that will be processed by the async processor.
+  # An HTTP request that a processor runs asynchronously.
   #
-  # @example Creating a request
+  # @example Create a GET request
   #   request = PatientHttp::Request.new(:get, "https://api.example.com/users/123")
   #
-  # @example Creating a POST request with JSON body
+  # @example Create a POST request with a JSON body
   #   request = PatientHttp::Request.new(
   #     :post,
   #     "https://api.example.com/users",
@@ -16,53 +16,71 @@ module PatientHttp
     UNDEFINED = Object.new.freeze
     private_constant :UNDEFINED
 
-    # Valid HTTP methods
+    # The supported HTTP methods.
     VALID_METHODS = %i[get head post put patch delete query].freeze
 
-    # HTTP methods that must not carry a request body
+    # The HTTP methods that can't have a request body.
     BODYLESS_METHODS = %i[get head delete].freeze
 
-    # @return [Symbol] HTTP method (:get, :head, :post, :put, :patch, :delete, :query)
+    # The HTTP methods that can be sent again without changing the result. As in
+    # RFC 9110, POST and PATCH aren't included.
+    IDEMPOTENT_METHODS = [:get, :head, :put, :delete, :query].freeze
+
+    # @return [Symbol] The HTTP method: `:get`, `:head`, `:post`, `:put`, `:patch`,
+    #   `:delete`, or `:query`.
     attr_reader :http_method
 
-    # @return [String] The request URL
+    # @return [String] The request URL.
     attr_reader :url
 
-    # @return [HttpHeaders] Request headers
+    # @return [HttpHeaders] The request headers.
     attr_reader :headers
 
-    # @return [Numeric, nil] Overall timeout in seconds
+    # @return [Numeric, nil] The timeout in seconds for the full request.
     attr_reader :timeout
 
-    # @return [Integer, nil] Maximum number of redirects to follow (nil uses config default, 0 disables)
+    # @return [Numeric, nil] The maximum number of seconds to wait for data from
+    #   the server. The timer covers the wait for the response headers and
+    #   starts again each time a body chunk arrives. If `nil`, the configuration
+    #   value applies.
+    attr_reader :read_timeout
+
+    # @return [Integer, nil] The maximum response body size in bytes for this
+    #   request. If `nil`, the configuration value applies.
+    attr_reader :max_response_size
+
+    # @return [Integer, nil] The maximum number of redirects to follow. If `0`,
+    #   redirects aren't followed. If `nil`, the configuration value applies.
     attr_reader :max_redirects
 
-    # @return [Boolean, nil] Whether a redirect that requires changing the HTTP method
-    #   (for example POST to GET on a 302) may be followed (nil uses config default)
+    # @return [Boolean, nil] Whether to follow a redirect that changes the HTTP
+    #   method, such as POST to GET on a 302. If `nil`, the configuration value
+    #   applies.
     attr_reader :follow_method_changing_redirects
 
-    # @return [Array<String>] Lowercase header names stripped from redirected requests,
-    #   in addition to those configured on the {Configuration}
+    # @return [Array<String>] The lowercase names of headers to remove from
+    #   redirected requests, in addition to the names set in the {Configuration}.
     attr_reader :redirect_strip_headers
 
-    # @return [Hash{String, Symbol => SecretReference}] Query parameters whose values are
-    #   secret references, kept out of the serialized URL and resolved at send time
+    # @return [Hash{String, Symbol => SecretReference}] The query parameters whose
+    #   values are secret references. They aren't in the serialized URL. The
+    #   processor resolves them when it sends the request.
     attr_reader :secret_params
 
-    # @return [Array<String>] Names of preprocessors registered on the configuration
-    #   to apply to the request when it is sent
+    # @return [Array<String>] The names of the registered preprocessors that run
+    #   on the request before it's sent.
     attr_reader :preprocessors
 
-    # @return [String, nil] Name of the processor that should execute the request.
-    #   Integrations use this to route the request to a named processor; nil
-    #   uses the default processor.
+    # @return [String, nil] The name of the processor that runs the request.
+    #   Integrations use this value to send the request to a named processor. If
+    #   `nil`, the default processor runs the request.
     attr_reader :processor
 
     class << self
-      # Reconstruct a Request from a hash
+      # Creates a request from its serialized form.
       #
-      # @param hash [Hash] hash representation
-      # @return [Request] reconstructed request
+      # @param hash [Hash] The hash from {#as_json}.
+      # @return [Request] The request.
       def load(hash)
         new(
           hash["http_method"].to_sym,
@@ -71,6 +89,8 @@ module PatientHttp
           body: Payload.load(hash["body"])&.value,
           params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
+          read_timeout: hash["read_timeout"],
+          max_response_size: hash["max_response_size"],
           max_redirects: hash["max_redirects"],
           follow_method_changing_redirects: hash["follow_method_changing_redirects"],
           redirect_strip_headers: hash["redirect_strip_headers"],
@@ -98,26 +118,42 @@ module PatientHttp
       end
     end
 
-    # Initializes a new Request.
+    # Creates a request.
     #
-    # @param http_method [Symbol, String] HTTP method (:get, :head, :post, :put, :patch, :delete, :query).
+    # @param http_method [Symbol, String] The HTTP method: `:get`, `:head`, `:post`,
+    #   `:put`, `:patch`, `:delete`, or `:query`.
     # @param url [String, URI::Generic] The request URL.
-    # @param headers [Hash, HttpHeaders] Request headers.
-    # @param body [String, nil] Request body.
-    # @param json [Object, nil] JSON body to be serialized (alternative to body).
-    # @param params [Hash, nil] Query parameters to append to the URL.
-    # @param timeout [Numeric, nil] Overall timeout in seconds.
-    # @param max_redirects [Integer, nil] Maximum redirects to follow (nil uses config, 0 disables).
-    # @param follow_method_changing_redirects [Boolean, nil] Whether to follow a redirect that requires changing
-    #   the HTTP method (nil uses config). When false, such a redirect response is returned as the
-    #   result instead of being followed.
-    # @param redirect_strip_headers [String, Array<String>, nil] Header names (case insensitive)
-    #   to strip from redirected requests, in addition to those configured on the
-    #   {Configuration}.
-    # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] Names of preprocessors
-    #   registered on the configuration to apply to the request when it is sent.
-    # @param processor [String, Symbol, nil] Name of the processor that should execute the
-    #   request. Integrations use this to route the request to a named processor.
+    # @param headers [Hash, HttpHeaders] The request headers.
+    # @param body [String, nil] The request body. GET, HEAD, and DELETE requests
+    #   can't have a body.
+    # @param json [Object, nil] An object to send as a JSON body. Can't be combined
+    #   with `body`.
+    # @param params [Hash, nil] The query parameters to add to the URL.
+    # @param timeout [Numeric, nil] The timeout in seconds for the full request.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait
+    #   for data from the server. The timer covers the wait for the response
+    #   headers and starts again each time a body chunk arrives. Use it for
+    #   streamed responses. Do not use it when the server does all of its work
+    #   before it sends the headers. If `nil`, the configuration value applies.
+    # @param max_response_size [Integer, nil] The maximum response body size in
+    #   bytes. For a compressed response, the limit also applies to the
+    #   decompressed body. If `nil`, the configuration value applies.
+    # @param max_redirects [Integer, nil] The maximum number of redirects to
+    #   follow. If `0`, redirects aren't followed. If `nil`, the configuration
+    #   value applies.
+    # @param follow_method_changing_redirects [Boolean, nil] Whether to follow a
+    #   redirect that changes the HTTP method. If `false`, the redirect response is
+    #   the result. If `nil`, the configuration value applies.
+    # @param redirect_strip_headers [String, Array<String>, nil] The names of headers
+    #   to remove from redirected requests, in addition to the names set in the
+    #   {Configuration}. Names are case insensitive.
+    # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] The names of
+    #   the registered preprocessors that run on the request before it's sent.
+    # @param processor [String, Symbol, nil] The name of the processor that runs
+    #   the request. Integrations use this value to send the request to a named
+    #   processor.
+    # @raise [ArgumentError] If the HTTP method, URL, body, `read_timeout`, or
+    #   `max_response_size` isn't valid, or if both `body` and `json` are given.
     def initialize(
       http_method,
       url,
@@ -126,6 +162,8 @@ module PatientHttp
       json: nil,
       params: nil,
       timeout: nil,
+      read_timeout: nil,
+      max_response_size: nil,
       max_redirects: nil,
       follow_method_changing_redirects: nil,
       redirect_strip_headers: nil,
@@ -145,6 +183,8 @@ module PatientHttp
       @headers = headers.is_a?(HttpHeaders) ? headers.dup : HttpHeaders.new(headers)
       @body = (body == "") ? nil : body
       @timeout = timeout
+      @read_timeout = normalized_read_timeout(read_timeout)
+      @max_response_size = normalized_max_response_size(max_response_size)
       @max_redirects = max_redirects
       @follow_method_changing_redirects = normalized_follow_method_changing_redirects(follow_method_changing_redirects)
       @redirect_strip_headers = RedirectHelper.normalize_header_names(redirect_strip_headers)
@@ -165,17 +205,25 @@ module PatientHttp
       @body = UNDEFINED
     end
 
-    # Returns the request body, decoding it from the payload if necessary.
+    # Returns the request body. The body is decoded on first access.
     #
-    # @return [String, nil] The decoded request body or nil if there was no body.
+    # @return [String, nil] The request body, or `nil` if the request has no body.
     def body
       @body = @payload&.value if @body.equal?(UNDEFINED)
       @body
     end
 
-    # Serialize to JSON hash.
+    # Returns whether the request can be sent again without changing the result.
+    # The HTTP method determines the value.
+    #
+    # @return [Boolean] `true` if the HTTP method is idempotent.
+    def idempotent?
+      IDEMPOTENT_METHODS.include?(@http_method)
+    end
+
+    # Returns the request as a JSON-compatible hash.
     #
-    # @return [Hash]
+    # @return [Hash] The serialized request.
     def as_json
       hash = {
         "http_method" => @http_method.to_s,
@@ -186,6 +234,9 @@ module PatientHttp
         "max_redirects" => @max_redirects
       }
 
+      hash["read_timeout"] = @read_timeout if @read_timeout
+      hash["max_response_size"] = @max_response_size if @max_response_size
+
       if @secret_params.any?
         hash["secret_params"] = @secret_params.transform_values(&:as_json)
       end
@@ -219,6 +270,26 @@ module PatientHttp
       raise ArgumentError.new("follow_method_changing_redirects must be true, false, or nil, got: #{value.inspect}")
     end
 
+    # Validate the read timeout is a positive number or nil.
+    def normalized_read_timeout(value)
+      return nil if value.nil?
+      return value if value.is_a?(Numeric) && value > 0
+
+      raise ArgumentError.new(
+        "read_timeout must be a positive number or nil, got: #{value.inspect}"
+      )
+    end
+
+    # Validate the maximum response size is a positive integer or nil.
+    def normalized_max_response_size(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer) && value > 0
+
+      raise ArgumentError.new(
+        "max_response_size must be a positive integer or nil, got: #{value.inspect}"
+      )
+    end
+
     # Normalize the processor name to a frozen string or nil.
     def normalized_processor(processor)
       return nil if processor.nil?

data/lib/patient_http/request_error.rb

@@ -1,36 +1,37 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Error object representing an exception from making an HTTP request. Note that this
-  # is not for HTTP error responses (4xx/5xx), but from actual exceptions raised
-  # during the request (timeouts, connection errors, SSL errors, etc).
+  # The error for an exception that occurs while a request runs, such as a
+  # timeout, a connection failure, or an SSL error. HTTP error responses (4xx
+  # and 5xx) use {HttpError} instead.
   #
-  # This is how errors are passed back to the error continuation jobs for processing.
+  # The error can be serialized, so a job system can pass it to the `on_error`
+  # callback in another process.
   class RequestError < Error
-    # Valid error types
+    # The valid error types.
     ERROR_TYPES = [:timeout, :connection, :ssl, :response_too_large, :unknown].freeze
 
-    # @return [String] Request URL
+    # @return [String] The request URL.
     attr_reader :url
 
-    # @return [Symbol] HTTP method
+    # @return [Symbol] The HTTP method.
     attr_reader :http_method
 
-    # @return [Float] Request duration in seconds
+    # @return [Float] The request duration in seconds.
     attr_reader :duration
 
-    # @return [String] Unique request identifier
+    # @return [String] The unique request ID.
     attr_reader :request_id
 
-    # @return [Symbol] Categorized error type. This provides a higher level categorization
-    # of the error (e.g., :connection is used to group IO and socket errors).
+    # @return [Symbol] The error category, one of {ERROR_TYPES}. For example,
+    #   `:connection` includes I/O and socket errors.
     attr_reader :error_type
 
     class << self
-      # Reconstruct a RequestError from a hash
+      # Creates an error from its serialized form.
       #
-      # @param hash [Hash] hash representation
-      # @return [RequestError] reconstructed error
+      # @param hash [Hash] The hash from {#as_json}.
+      # @return [RequestError] The error.
       def load(hash)
         new(
           class_name: hash["class_name"],
@@ -45,15 +46,15 @@ module PatientHttp
         )
       end
 
-      # Create a RequestError from an exception using pattern matching
+      # Creates an error from an exception.
       #
-      # @param exception [Exception] the exception to convert
-      # @param duration [Float] request duration in seconds
-      # @param request_id [String] the request ID
-      # @param url [String] the request URL
-      # @param http_method [Symbol, String] the HTTP method
-      # @param callback_args [Hash, nil] callback arguments (string keys)
-      # @return [RequestError] the error object
+      # @param exception [Exception] The exception that the request raised.
+      # @param duration [Float] The request duration in seconds.
+      # @param request_id [String] The request ID.
+      # @param url [String] The request URL.
+      # @param http_method [Symbol, String] The HTTP method.
+      # @param callback_args [Hash, nil] The callback arguments, with string keys.
+      # @return [RequestError] The error.
       def from_exception(exception, duration:, request_id:, url:, http_method:, callback_args: nil)
         type = error_type(exception)
 
@@ -70,13 +71,16 @@ module PatientHttp
         )
       end
 
-      # Determine error type from exception.
+      # Returns the error type for an exception.
       #
-      # @param exception [Exception] the exception to categorize
-      # @return [Symbol] the error type
+      # `IO::TimeoutError` is a subclass of `IOError`, but its type is `:timeout`,
+      # not `:connection`.
+      #
+      # @param exception [Exception] The exception.
+      # @return [Symbol] The error type, one of {ERROR_TYPES}.
       def error_type(exception)
         case exception
-        in Async::TimeoutError
+        in Async::TimeoutError | IO::TimeoutError
           :timeout
         in OpenSSL::SSL::SSLError
           :ssl
@@ -92,17 +96,17 @@ module PatientHttp
       end
     end
 
-    # Initializes a new RequestError.
+    # Creates an error.
     #
-    # @param class_name [String] Name of the exception class
-    # @param message [String] Exception message
-    # @param backtrace [Array<String>] Exception backtrace
-    # @param error_type [Symbol] Categorized error type
-    # @param duration [Float] Request duration in seconds
-    # @param request_id [String] Unique request identifier
-    # @param url [String] Request URL
-    # @param http_method [Symbol, String] HTTP method
-    # @param callback_args [Hash, nil] callback arguments (string keys)
+    # @param class_name [String] The name of the exception class.
+    # @param message [String] The exception message.
+    # @param backtrace [Array<String>] The exception backtrace.
+    # @param error_type [Symbol] The error type, one of {ERROR_TYPES}.
+    # @param duration [Float] The request duration in seconds.
+    # @param request_id [String] The unique request ID.
+    # @param url [String] The request URL.
+    # @param http_method [Symbol, String] The HTTP method.
+    # @param callback_args [Hash, nil] The callback arguments, with string keys.
     def initialize(class_name:, message:, backtrace:, error_type:, duration:, request_id:, url:, http_method:,
       callback_args: nil)
       super(message)
@@ -116,9 +120,9 @@ module PatientHttp
       @callback_args_data = callback_args || {}
     end
 
-    # Convert to hash with string keys for serialization
+    # Returns the error as a JSON-compatible hash.
     #
-    # @return [Hash] hash representation
+    # @return [Hash] The serialized error.
     def as_json
       {
         "class_name" => @class_name,
@@ -133,16 +137,17 @@ module PatientHttp
       }
     end
 
-    # Get the actual Exception class constant from the class_name
+    # Returns the class of the exception that caused the error.
     #
-    # @return [Class, nil] the exception class or nil if not found
+    # @return [Class, nil] The exception class, or `nil` if the class isn't
+    #   defined in this process.
     def error_class
       ClassHelper.resolve_class_name(@class_name)
     end
 
-    # Returns the callback arguments as a CallbackArgs object.
+    # Returns the callback arguments that were passed with the request.
     #
-    # @return [CallbackArgs] the callback arguments
+    # @return [CallbackArgs] The callback arguments.
     def callback_args
       @callback_args ||= CallbackArgs.load(@callback_args_data)
     end