patient_http 1.6.1 → 1.7.0

data/lib/patient_http/processor_observer.rb

@@ -1,114 +1,120 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Interface for observing request processing. A process observer can be registered with
-  # a Processor and receive events as requests are processed. Observers should be
-  # lightweight and not do processing other than recording metrics or similar.
+  # The base class for objects that receive processor events. Register an
+  # observer with {Processor#observe}. Subclass it and override the methods for
+  # the events that you need.
   #
-  # Hooks run on different threads depending on where the event originates:
-  # - request_enqueued, request_rejected: the thread calling Processor#enqueue
-  #   (usually an application thread), and the reactor thread for each task
-  #   created to follow a redirect. Work done in these hooks blocks the reactor
-  #   for redirected requests, so keep it off the critical path or accept the
-  #   delay it adds to every other in-flight request
-  # - capacity_exceeded: the thread calling Processor#enqueue (usually an
-  #   application thread)
-  # - request_start: the reactor thread
-  # - request_end, request_error, completion_failed: a completion worker
-  #   thread (request_end also fires on the reactor thread for followed
-  #   redirects, and on the stopping thread for shutdown re-enqueues)
-  # - request_requeued: the stopping thread or the reactor thread
-  # - start, stop: the thread calling Processor#start / Processor#stop
+  # Keep observers lightweight. Use them to record metrics or to track
+  # requests, not to do other work.
   #
-  # Observers must be thread-safe. Hooks are called from several threads, and
-  # the completion-time hooks run on any of the completion worker threads, so
-  # two of them can run at the same time and in an order unrelated to the
-  # order the requests completed. Guard any counter or buffer an observer
-  # shares between calls. Setting completion_threads to 1 serializes the
-  # completion-time hooks but does not serialize them against the hooks that
-  # fire on other threads.
+  # Each method runs on the thread where its event occurs:
+  #
+  # - {#request_enqueued} and {#request_rejected}: The thread that calls
+  #   {Processor#enqueue}, usually an application thread. For a redirect, the
+  #   reactor thread. Slow work in these methods delays every in-flight request
+  #   when a redirect is followed.
+  # - {#capacity_exceeded}: The thread that calls {Processor#enqueue}.
+  # - {#request_start}: The reactor thread.
+  # - {#request_end}, {#request_error}, and {#completion_failed}: A completion
+  #   worker thread. {#request_end} also runs on the reactor thread for a
+  #   followed redirect, and on the stopping thread for a request that's
+  #   re-enqueued at shutdown.
+  # - {#request_requeued}: The stopping thread or the reactor thread.
+  # - {#start} and {#stop}: The thread that calls {Processor#start} or
+  #   {Processor#stop}.
+  #
+  # Observers must be thread-safe. Methods run on several threads, and two
+  # completion worker threads can call methods at the same time, in any order.
+  # Protect any counter or buffer that calls share. If `completion_threads` is
+  # 1, the completion worker calls run one at a time, but they can still run at
+  # the same time as calls on other threads.
   class ProcessorObserver
-    # Called when the processor starts.
+    # Runs when the processor starts.
     #
     # @return [void]
     def start
     end
 
-    # Called when the processor stops.
+    # Runs when the processor stops.
     #
     # @return [void]
     def stop
     end
 
-    # Called when a request cannot be enqueued because the processor is at capacity.
+    # Runs when a request can't be enqueued because the processor is at
+    # `max_connections`.
     #
     # @return [void]
     def capacity_exceeded
     end
 
-    # Called when a request task is handed to the processor, before the task is
-    # visible to the reactor. The notification is guaranteed to arrive before
-    # request_start for the task, so observers can set up durable tracking
-    # (e.g. a crash-recovery registry entry) with no risk that the task
-    # completes first. If the processor does not accept the task,
-    # request_rejected is sent afterward. Unlike other notifications, an error
-    # raised here propagates from Processor#enqueue and rejects the task, so a
-    # failed tracking setup does not let the task be accepted as if it were
-    # durable.
+    # Runs when a task is given to the processor, before the reactor can see
+    # the task.
+    #
+    # This method always runs before {#request_start} for the task. As a
+    # result, an observer can set up durable tracking, such as a crash-recovery
+    # registry entry, before the task can finish. If the processor doesn't
+    # accept the task, {#request_rejected} runs next.
     #
-    # @param request_task [RequestTask] the request task that was enqueued
+    # Unlike the other methods, an error raised here isn't caught.
+    # {Processor#enqueue} raises the error and rejects the task. As a result,
+    # the processor never accepts a task whose tracking failed.
+    #
+    # @param request_task [RequestTask] The task.
     # @return [void]
     def request_enqueued(request_task)
     end
 
-    # Called when a request task announced with request_enqueued was not
-    # accepted by the processor (not running or at capacity). Observers should
-    # tear down anything they set up in request_enqueued; the caller owns the
-    # request again once this is sent.
+    # Runs when the processor doesn't accept a task after {#request_enqueued},
+    # because the processor isn't running or is at capacity. Remove anything
+    # that {#request_enqueued} set up. After this call, the caller owns the
+    # request again.
     #
-    # @param request_task [RequestTask] the request task that was rejected
+    # @param request_task [RequestTask] The task.
     # @return [void]
     def request_rejected(request_task)
     end
 
-    # Called when an incomplete request task was re-enqueued through its task
-    # handler (processor shutdown or reactor failure). The task handler's job
-    # system owns the request again once this is sent, so observers should
-    # tear down any durable tracking for the task.
+    # Runs when a task that didn't finish is re-enqueued through its task
+    # handler, because the processor stopped or the reactor failed. After this
+    # call, the job system owns the request again, so remove any durable
+    # tracking for the task.
     #
-    # @param request_task [RequestTask] the request task that was re-enqueued
+    # @param request_task [RequestTask] The task.
     # @return [void]
     def request_requeued(request_task)
     end
 
-    # Called when a request starts processing.
+    # Runs when a request starts.
     #
-    # @param request_task [RequestTask] the request task that started
+    # @param request_task [RequestTask] The task.
     # @return [void]
     def request_start(request_task)
     end
 
-    # Called when a request finishes processing.
+    # Runs when a request finishes and its result is delivered.
     #
-    # @param request_task [RequestTask] the request task that ended
+    # @param request_task [RequestTask] The task.
     # @return [void]
     def request_end(request_task)
     end
 
-    # Called when a request encounters an error.
+    # Runs when a request fails with an error.
     #
-    # @param error [StandardError] the error that occurred
+    # @param error [StandardError] The error.
     # @return [void]
     def request_error(error)
     end
 
-    # Called when a finished result could not be delivered to the task handler
-    # after all retries. request_end is NOT sent for the task, so durable
-    # tracking set up in request_enqueued stays in place and an external
-    # recovery process (e.g. an orphan collector) can re-enqueue the request.
+    # Runs when the task handler can't take a result after all retries.
+    #
+    # {#request_end} doesn't run for the task. As a result, durable tracking
+    # from {#request_enqueued} stays in place, and a recovery process, such as
+    # an orphan collector, can re-enqueue the request.
     #
-    # @param request_task [RequestTask] the request task whose result was not delivered
-    # @param error [StandardError] the delivery failure
+    # @param request_task [RequestTask] The task.
+    # @param error [StandardError] The error from the last delivery attempt.
     # @return [void]
     def completion_failed(request_task, error)
     end

data/lib/patient_http/rails/engine.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
-# This file must be explicitly required to enable Rails integration.
-# Usage: require "patient_http/rails/engine"
+# Require this file to add the Rails integration:
 #
-# This will allow you to install migrations using:
-#   rails patient_http:install:migrations
+#   require "patient_http/rails/engine"
+#
+# Then install the migrations:
+#
+#   bin/rails patient_http:install:migrations
 
 require "rails/engine"
 
 module PatientHttp
+  # The Rails integration.
   module Rails
+    # A Rails engine that makes the gem's migrations available to the
+    # application. It isn't loaded by default.
+    #
+    # @example Install the migrations
+    #   bin/rails patient_http:install:migrations
+    #   bin/rails db:migrate
     class Engine < ::Rails::Engine
       engine_name "patient_http"
-
-      # Migrations will be picked up automatically from db/migrate
-      # when the engine is loaded. Users can copy them using:
-      #   rails patient_http:install:migrations
     end
   end
 end

data/lib/patient_http/redirect_error.rb

@@ -1,31 +1,32 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Base class for redirect-related errors.
-  # These errors occur when redirect handling fails due to too many redirects
-  # or a redirect loop.
+  # The base class for redirect errors. A redirect error occurs when a request
+  # exceeds the redirect limit or finds a redirect loop.
   class RedirectError < Error
-    # @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 [Array<String>] URLs that were visited during redirect chain
+    # @return [Array<String>] The URLs of the redirects that were followed, in
+    #   order.
     attr_reader :redirects
 
     class << self
-      # Reconstruct a RedirectError from a hash
+      # Creates an error from its serialized form.
       #
-      # @param hash [Hash] hash representation
-      # @return [RedirectError] reconstructed error
-      # @raise [ArgumentError] if the serialized error class is not a RedirectError
+      # @param hash [Hash] The hash from {#as_json}.
+      # @return [RedirectError] The error.
+      # @raise [ArgumentError] If the serialized error class isn't a
+      #   `RedirectError`.
       def load(hash)
         error_class = ClassHelper.resolve_class_name(hash["error_class"])
         unless error_class.is_a?(Class) && error_class <= RedirectError
@@ -43,15 +44,16 @@ module PatientHttp
       end
     end
 
-    # Initializes a new RedirectError.
+    # Creates an error.
     #
-    # @param message [String] Error message
-    # @param url [String] Request URL
-    # @param http_method [Symbol, String] HTTP method
-    # @param duration [Float] Request duration in seconds
-    # @param request_id [String] Unique request identifier
-    # @param redirects [Array<String>] URLs visited during redirect chain
-    # @param callback_args [Hash, nil] callback arguments (string keys)
+    # @param message [String] The error message.
+    # @param url [String] The request URL.
+    # @param http_method [Symbol, String] The HTTP method.
+    # @param duration [Float] The request duration in seconds.
+    # @param request_id [String] The unique request ID.
+    # @param redirects [Array<String>] The URLs of the redirects that were
+    #   followed.
+    # @param callback_args [Hash, nil] The callback arguments, with string keys.
     def initialize(message, url:, http_method:, duration:, request_id:, redirects:, callback_args: nil)
       super(message)
       @url = url
@@ -62,28 +64,28 @@ module PatientHttp
       @callback_args_data = callback_args || {}
     end
 
-    # Returns the error type symbol.
+    # Returns the error type.
     #
-    # @return [Symbol] the error type
+    # @return [Symbol] Always `:redirect`.
     def error_type
       :redirect
     end
 
-    # @return [Class] the class of the exception. This is for compatibility with RequestError.
+    # @return [Class] The class of this error.
     def error_class
       self.class
     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
 
-    # 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
       {
         "error_class" => self.class.name,
@@ -97,14 +99,17 @@ module PatientHttp
     end
   end
 
-  # Error raised when too many redirects are encountered.
+  # The error for a request that exceeds the redirect limit.
   class TooManyRedirectsError < RedirectError
-    # @param url [String] The URL that would have been redirected to
-    # @param http_method [Symbol, String] HTTP method
-    # @param duration [Float] Request duration in seconds
-    # @param request_id [String] Unique request identifier
-    # @param redirects [Array<String>] URLs visited during redirect chain
-    # @param callback_args [Hash, nil] callback arguments (string keys)
+    # Creates an error.
+    #
+    # @param url [String] The URL of the redirect that exceeded the limit.
+    # @param http_method [Symbol, String] The HTTP method.
+    # @param duration [Float] The request duration in seconds.
+    # @param request_id [String] The unique request ID.
+    # @param redirects [Array<String>] The URLs of the redirects that were
+    #   followed.
+    # @param callback_args [Hash, nil] The callback arguments, with string keys.
     def initialize(url:, http_method:, duration:, request_id:, redirects:, callback_args: nil)
       super(
         "Too many redirects (#{redirects.size}) while requesting #{http_method.to_s.upcase} #{redirects.first || url}",
@@ -118,14 +123,18 @@ module PatientHttp
     end
   end
 
-  # Error raised when a recursive redirect is detected.
+  # The error for a redirect loop, where a redirect goes to a URL that the
+  # request already visited.
   class RecursiveRedirectError < RedirectError
-    # @param url [String] The URL that caused the loop
-    # @param http_method [Symbol, String] HTTP method
-    # @param duration [Float] Request duration in seconds
-    # @param request_id [String] Unique request identifier
-    # @param redirects [Array<String>] URLs visited during redirect chain
-    # @param callback_args [Hash, nil] callback arguments (string keys)
+    # Creates an error.
+    #
+    # @param url [String] The URL that caused the loop.
+    # @param http_method [Symbol, String] The HTTP method.
+    # @param duration [Float] The request duration in seconds.
+    # @param request_id [String] The unique request ID.
+    # @param redirects [Array<String>] The URLs of the redirects that were
+    #   followed.
+    # @param callback_args [Hash, nil] The callback arguments, with string keys.
     def initialize(url:, http_method:, duration:, request_id:, redirects:, callback_args: nil)
       super(
         "Recursive redirect detected: #{url} was already visited in redirect chain",

data/lib/patient_http/redirect_helper.rb

@@ -8,7 +8,7 @@ module PatientHttp
   # @api private
   module RedirectHelper
     class << self
-      # Determine the HTTP method to use when following a redirect.
+      # Returns the HTTP method to use when following a redirect.
       #
       # The rules follow RFC 9110 and the WHATWG Fetch standard:
       #
@@ -18,9 +18,9 @@ module PatientHttp
       # - 303 preserves GET and HEAD; every other method becomes GET.
       # - 300, 307, and 308 preserve the method.
       #
-      # @param http_method [Symbol] the current request method
-      # @param status [Integer] the redirect status code
-      # @return [Symbol] the method for the redirected request
+      # @param http_method [Symbol] The current request method.
+      # @param status [Integer] The redirect status code.
+      # @return [Symbol] The method for the redirected request.
       def redirect_method(http_method, status)
         case status
         when 301, 302
@@ -32,21 +32,21 @@ module PatientHttp
         end
       end
 
-      # Check if following a redirect requires changing the request method.
+      # Returns whether following a redirect requires changing the request method.
       #
-      # @param http_method [Symbol] the current request method
-      # @param status [Integer] the redirect status code
-      # @return [Boolean] true if the method must change to follow the redirect
+      # @param http_method [Symbol] The current request method.
+      # @param status [Integer] The redirect status code.
+      # @return [Boolean] `true` if the method must change to follow the redirect.
       def method_change_required?(http_method, status)
         redirect_method(http_method, status) != http_method
       end
 
-      # Normalize header names used to strip headers from redirected requests.
+      # Normalizes header names used to strip headers from redirected requests.
       # Names are downcased so they match header names case insensitively.
       #
-      # @param names [String, Symbol, Array<String, Symbol>, nil] header names
-      # @return [Array<String>] frozen lowercase header names
-      # @raise [ArgumentError] if a name is not a string or symbol, or is empty
+      # @param names [String, Symbol, Array<String, Symbol>, nil] Header names.
+      # @return [Array<String>] Frozen lowercase header names.
+      # @raise [ArgumentError] If a name is not a string or symbol, or is empty.
       def normalize_header_names(names)
         Array(names).map do |name|
           unless name.is_a?(String) || name.is_a?(Symbol)
@@ -62,11 +62,11 @@ module PatientHttp
 
     private
 
-    # Check if a redirect response should be followed.
+    # Returns whether a redirect response should be followed.
     #
-    # @param task [RequestTask] the request task
-    # @param response_data [Hash] the response data with status, headers, body
-    # @return [Boolean] true if the redirect should be followed
+    # @param task [RequestTask] The request task.
+    # @param response_data [Hash] The response data with status, headers, body.
+    # @return [Boolean] `true` if the redirect should be followed.
     def should_follow_redirect?(task, response_data)
       status = response_data[:status]
       return false unless FOLLOWABLE_REDIRECT_STATUSES.include?(status)
@@ -82,10 +82,10 @@ module PatientHttp
       true
     end
 
-    # Check if the request may change its method to follow a redirect.
+    # Returns whether the request may change its method to follow a redirect.
     # The request setting takes precedence over the configuration.
     #
-    # @param task [RequestTask] the request task
+    # @param task [RequestTask] The request task.
     # @return [Boolean]
     def follow_method_changing_redirect?(task)
       value = task.request.follow_method_changing_redirects
@@ -93,12 +93,12 @@ module PatientHttp
       value
     end
 
-    # Build the task for following a redirect, applying the configured
+    # Builds the task for following a redirect, applying the configured
     # header stripping rules.
     #
-    # @param task [RequestTask] the request task
-    # @param response_data [Hash] the response data with status, headers, body
-    # @return [RequestTask] the redirect task
+    # @param task [RequestTask] The request task.
+    # @param response_data [Hash] The response data with status, headers, body.
+    # @return [RequestTask] The redirect task.
     def build_redirect_task(task, response_data)
       task.redirect_task(
         location: response_data[:headers]["location"],
@@ -107,11 +107,11 @@ module PatientHttp
       )
     end
 
-    # Check for either too-many-redirects or recursive redirect.
+    # Returns an error if a redirect exceeds the limit or makes a loop.
     #
-    # @param task [RequestTask] the request task
-    # @param response_data [Hash] the response data with status, headers, body
-    # @return [RedirectError, nil] error if redirect should not proceed, nil otherwise
+    # @param task [RequestTask] The request task.
+    # @param response_data [Hash] The response data with status, headers, body.
+    # @return [RedirectError, nil] Error if redirect should not proceed, nil otherwise.
     def check_redirect_error(task, response_data)
       location = response_data[:headers]["location"]
       redirect_url = resolve_redirect_url(task.request.url, location)
@@ -119,11 +119,11 @@ module PatientHttp
       check_too_many_redirects(task, location) || check_recursive_redirect(task, redirect_url)
     end
 
-    # Check if the redirect count has exceeded the maximum.
+    # Returns whether the redirect count has exceeded the maximum.
     #
-    # @param task [RequestTask] the request task
-    # @param location [String] the redirect location URL
-    # @return [TooManyRedirectsError, nil] error if exceeded, nil otherwise
+    # @param task [RequestTask] The request task.
+    # @param location [String] The redirect location URL.
+    # @return [TooManyRedirectsError, nil] Error if exceeded, nil otherwise.
     def check_too_many_redirects(task, location)
       return nil if task.redirects.size < task.max_redirects
 
@@ -137,11 +137,11 @@ module PatientHttp
       )
     end
 
-    # Check if the redirect URL has already been visited (redirect loop).
+    # Returns whether the redirect URL has already been visited (redirect loop).
     #
-    # @param task [RequestTask] the request task
-    # @param redirect_url [String] the resolved redirect URL
-    # @return [RecursiveRedirectError, nil] error if loop detected, nil otherwise
+    # @param task [RequestTask] The request task.
+    # @param redirect_url [String] The resolved redirect URL.
+    # @return [RecursiveRedirectError, nil] Error if loop detected, nil otherwise.
     def check_recursive_redirect(task, redirect_url)
       visited_urls = task.redirects + [task.request.url]
       return nil unless visited_urls.include?(redirect_url)
@@ -156,11 +156,11 @@ module PatientHttp
       )
     end
 
-    # Resolve a redirect URL, handling relative URLs.
+    # Resolves a redirect URL, handling relative URLs.
     #
-    # @param base_url [String] The base URL
-    # @param location [String] The Location header value
-    # @return [String] The resolved absolute URL
+    # @param base_url [String] The base URL.
+    # @param location [String] The Location header value.
+    # @return [String] The resolved absolute URL.
     def resolve_redirect_url(base_url, location)
       base_uri = URI.parse(base_url)
       redirect_uri = URI.parse(location)