patient_http 1.6.0 → 1.7.0

data/lib/patient_http/http_headers.rb

@@ -1,52 +1,69 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Case insensitive HTTP headers.
+  # HTTP headers with case-insensitive names.
   #
-  # This class provides a hash-like interface for HTTP headers with case-insensitive
-  # key access. Header names are normalized to lowercase for storage and lookup.
+  # The interface is like a Hash. Names are stored in lowercase.
+  #
+  # A header with an empty value isn't stored. If you set a header to `nil` or
+  # an empty string, the header is removed. As a result, a request never sends
+  # a header with no value.
   class HttpHeaders
     include Enumerable
 
-    # Initializes a new HttpHeaders instance.
+    # Creates a set of headers. Entries with a `nil` or empty value are skipped.
     #
-    # @param headers [Hash] initial headers to set
+    # @param headers [Hash, HttpHeaders] Initial headers to set.
     def initialize(headers = {})
       @headers = {}
       headers&.each do |key, value|
-        @headers[key.to_s.downcase] = value
+        self[key] = value
       end
     end
 
     # Retrieves the value for a header (case insensitive).
     #
-    # @param key [String, Symbol] header name
-    # @return [String, nil] header value or nil if not found
+    # @param key [String, Symbol] Header name.
+    # @return [String, nil] Header value or nil if not found.
     def [](key)
       @headers[key.to_s.downcase]
     end
 
-    # Sets the value for a header (case insensitive).
+    # Sets the value for a header (case insensitive). Setting a header to `nil`
+    # or an empty string removes it.
     #
-    # @param key [String, Symbol] header name
-    # @param value [String] header value
+    # @param key [String, Symbol] Header name.
+    # @param value [String, nil] Header value.
     def []=(key, value)
-      @headers[key.to_s.downcase] = value
+      name = key.to_s.downcase
+      if empty_value?(value)
+        @headers.delete(name)
+      else
+        @headers[name] = value
+      end
+    end
+
+    # Removes a header (case insensitive).
+    #
+    # @param key [String, Symbol] Header name.
+    # @return [String, nil] The removed value or nil if not found.
+    def delete(key)
+      @headers.delete(key.to_s.downcase)
     end
 
     # Fetches the value for a header with an optional default.
     #
-    # @param key [String, Symbol] header name
-    # @param default [Object] default value if header not found
-    # @return [String, Object] header value or default
+    # @param key [String, Symbol] Header name.
+    # @param default [Object] Default value if header not found.
+    # @return [String, Object] Header value or default.
     def fetch(key, default = nil)
       @headers.fetch(key.to_s.downcase, default)
     end
 
     # Merges another set of headers into a new HttpHeaders instance.
     #
-    # @param other_headers [Hash, HttpHeaders] headers to merge
-    # @return [HttpHeaders] new instance with merged headers
+    # @param other_headers [Hash, HttpHeaders] Headers to merge.
+    # @return [HttpHeaders] New instance with merged headers.
     def merge(other_headers)
       new_headers = dup
       other_headers.each do |key, value|
@@ -57,8 +74,8 @@ module PatientHttp
 
     # Returns a new HttpHeaders without the specified keys (case-insensitive).
     #
-    # @param keys [Array<String, Symbol>] header names to exclude
-    # @return [HttpHeaders] new instance without the specified headers
+    # @param keys [Array<String, Symbol>] Header names to exclude.
+    # @return [HttpHeaders] New instance without the specified headers.
     def except(*keys)
       normalized = keys.map { |k| k.to_s.downcase }
       filtered_headers = @headers.reject { |key, _value| normalized.include?(key) } # rubocop:disable Style/HashExcept
@@ -67,40 +84,54 @@ module PatientHttp
 
     # Converts to a regular hash with lowercase keys.
     #
-    # @return [Hash] hash representation
+    # @return [Hash] Hash representation.
     def to_h
       @headers.dup
     end
 
     # Iterates over each header.
     #
-    # @yield [key, value] yields each header key-value pair
-    # @return [Enumerator] if no block given
+    # @yield [key, value] Yields each header key-value pair.
+    # @return [Enumerator] If no block given.
     def each(&block)
       @headers.each(&block)
     end
 
-    # Checks if a header exists (case insensitive).
+    # Returns whether a header exists (case insensitive).
     #
-    # @param name [String, Symbol] header name
-    # @return [Boolean] true if header exists
+    # @param name [String, Symbol] Header name.
+    # @return [Boolean] `true` if header exists.
     def include?(name)
       @headers.include?(name.to_s.downcase)
     end
 
-    # Ensure copies do not share the underlying storage so that mutating a
+    # Ensures copies do not share the underlying storage so that mutating a
     # copy (for example, via #merge) does not modify the original.
     def initialize_copy(other)
       super
       @headers = @headers.dup
     end
 
+    # Returns whether another object has the same headers.
+    #
+    # @param other [Object] The object to compare.
+    # @return [Boolean] `true` if the headers are equal.
     def eql?(other)
       other.is_a?(HttpHeaders) && @headers.eql?(other.to_h)
     end
 
+    # Returns a hash code based on the headers.
+    #
+    # @return [Integer] The hash code.
     def hash
       @headers.hash
     end
+
+    private
+
+    # A header value is empty when it is nil or a string with no characters.
+    def empty_value?(value)
+      value.nil? || (value.is_a?(String) && value.empty?)
+    end
   end
 end

data/lib/patient_http/immediate_retries.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Retries a request at once when its failure is known to be safe to retry.
+  #
+  # Only failures raised before any response byte arrives are considered; a
+  # failure while reading the body is never retried. The pooled clients make a
+  # single attempt per call, so this module is the only layer that retries and
+  # one limit bounds how many times a request is sent.
+  #
+  # A connection failure evicts the host's pooled client before the retry, so
+  # the retry opens a new connection instead of taking another idle connection
+  # that may have failed the same way. Each attempt looks up the host's client
+  # in the pool, so a retry never runs on a client a concurrent failure evicted.
+  #
+  # The including class must provide a private `config` method returning the
+  # {Configuration}, which supplies the logger.
+  #
+  # @api private
+  module ImmediateRetries
+    # Minimum number of attempts made after a failure that is safe to retry. A
+    # pool `retries` setting above IMMEDIATE_RETRY_LIMIT + 1 allows
+    # `retries - 1` attempts instead.
+    IMMEDIATE_RETRY_LIMIT = 2
+
+    # Errors from a connection that failed before delivering any response byte.
+    # They are ambiguous for a non-idempotent request: the server may have
+    # processed it and then died, or it may never have received it. IOError
+    # covers EOFError and the IO::TimeoutError raised by the connection timeout.
+    # EPIPE means a write failed, but the server may already have read enough of
+    # the request to act on it before closing. ETIMEDOUT is the kernel giving up
+    # on unacknowledged data (see the TCP user timeout), not the request
+    # timeout, which is never retried.
+    CONNECTION_ERRORS = [
+      IOError, SocketError, Errno::ECONNRESET, Errno::ECONNABORTED, Errno::EPIPE, Errno::ETIMEDOUT,
+      ::Protocol::HTTP::RemoteError
+    ].freeze
+
+    private
+
+    # Sends the request through the pool, retrying safe failures at once.
+    #
+    # @param client_pool [ClientPool] The pool to send through.
+    # @param request [Request] The request being sent, used for its method and URL.
+    # @param endpoint [Async::HTTP::Endpoint] The endpoint parsed from the prepared URL.
+    # @param headers [Hash] The prepared request headers.
+    # @param body [Protocol::HTTP::Body::Buffered, nil] The request body.
+    # @yield [client] Each pooled client before a request is sent through it.
+    # @return [Protocol::HTTP::Response] The response with its headers read.
+    def request_with_immediate_retries(client_pool, request, endpoint, headers, body)
+      limit = [client_pool.retries - 1, IMMEDIATE_RETRY_LIMIT].max
+      attempt = 1
+
+      loop do
+        client = client_pool.client_for(endpoint)
+        yield client if block_given?
+        return client_pool.request(request.http_method, endpoint, headers, body, client: client)
+      rescue => e
+        unless attempt <= limit && immediately_retryable?(request, e)
+          raise
+        end
+
+        if client && connection_failure?(e)
+          client_pool.evict(endpoint.url.to_s, client)
+        end
+
+        attempt += 1
+        body&.rewind
+        # The request URL is logged rather than the prepared URL, which carries
+        # resolved secret params.
+        config.logger&.info(
+          "[PatientHttp] Request to #{request.url} failed before a response " \
+          "(#{e.class.name}: #{e.message}); retrying (attempt #{attempt})"
+        )
+      end
+    end
+
+    # A refused request (an HTTP/2 GOAWAY, a pooled connection closed after it was
+    # acquired, or a rejected stream) was never processed by the server, so it is
+    # safe to retry whatever the method. A connection that fails in any other way
+    # before responding may have processed the request, so that failure is
+    # retried only for idempotent methods.
+    def immediately_retryable?(request, error)
+      case error
+      when ::Protocol::HTTP::RefusedError
+        true
+      when *CONNECTION_ERRORS
+        request.idempotent?
+      else
+        false
+      end
+    end
+
+    def connection_failure?(error)
+      CONNECTION_ERRORS.any? { |error_class| error.is_a?(error_class) }
+    end
+  end
+end

data/lib/patient_http/inline_task_handler.rb

@@ -1,28 +1,33 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # No-op task handler used for inline request execution.
+  # The task handler for requests that run inline.
   #
-  # The {SynchronousExecutor} invokes the user callback directly, so the
-  # completion and error hooks here are never exercised in practice; they are
-  # defined as no-ops to satisfy the {TaskHandler} contract. Inline requests
-  # have no job queue, so retrying is not supported.
+  # {SynchronousExecutor} calls the callback service directly, so
+  # {#on_complete} and {#on_error} do nothing. Inline requests have no job
+  # queue, so they can't be retried.
   #
   # @api private
   class InlineTaskHandler < TaskHandler
-    # @param response [Response] the HTTP response object
-    # @param callback [String] callback class name
+    # Does nothing.
+    #
+    # @param response [Response] The HTTP response.
+    # @param callback [String] The callback service class name.
     # @return [void]
     def on_complete(response, callback)
     end
 
-    # @param error [Error] the error object
-    # @param callback [String] callback class name
+    # Does nothing.
+    #
+    # @param error [Error] The error.
+    # @param callback [String] The callback service class name.
     # @return [void]
     def on_error(error, callback)
     end
 
-    # @raise [NotImplementedError] inline requests cannot be retried
+    # Raises an error, because inline requests can't be retried.
+    #
+    # @raise [NotImplementedError] Always.
     def retry
       raise NotImplementedError, "Inline requests cannot be retried"
     end

data/lib/patient_http/lifecycle_manager.rb

@@ -1,20 +1,19 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Manages the lifecycle state of the Processor.
+  # Manages the state of a {Processor}. The state changes are thread-safe.
   #
-  # Handles state transitions and provides predicates for checking the current state.
-  # Thread-safe state management using Concurrent::AtomicReference.
+  # @api private
   class LifecycleManager
     include TimeHelper
 
-    # Valid processor states
+    # Valid processor states.
     STATES = %i[stopped starting running draining stopping].freeze
 
-    # Polling interval during wait operations
+    # Polling interval during wait operations.
     POLL_INTERVAL = 0.01
 
-    # Initialize the lifecycle manager.
+    # Creates the lifecycle manager.
     #
     # @return [void]
     def initialize
@@ -24,53 +23,53 @@ module PatientHttp
       @lock = Mutex.new
     end
 
-    # Get the current state.
+    # Returns the current state.
     #
-    # @return [Symbol] the current state
+    # @return [Symbol] The current state.
     def state
       @state.get
     end
 
-    # Check if processor is starting.
+    # Returns whether the processor is starting.
     #
-    # @return [Boolean] true if starting
+    # @return [Boolean] `true` if starting.
     def starting?
       state == :starting
     end
 
-    # Check if processor is running.
+    # Returns whether the processor is running.
     #
-    # @return [Boolean] true if running
+    # @return [Boolean] `true` if running.
     def running?
       state == :running
     end
 
-    # Check if processor is stopped.
+    # Returns whether the processor is stopped.
     #
-    # @return [Boolean] true if stopped
+    # @return [Boolean] `true` if stopped.
     def stopped?
       state == :stopped
     end
 
-    # Check if processor is draining.
+    # Returns whether the processor is draining.
     #
-    # @return [Boolean] true if draining
+    # @return [Boolean] `true` if draining.
     def draining?
       state == :draining
     end
 
-    # Check if processor is stopping.
+    # Returns whether the processor is stopping.
     #
-    # @return [Boolean] true if stopping
+    # @return [Boolean] `true` if stopping.
     def stopping?
       state == :stopping
     end
 
-    # Transition to starting state. The processor can only be started from
+    # Transitions to starting state. The processor can only be started from
     # the stopped state; in particular, starting a draining processor would
     # spawn a second reactor alongside the one still finishing its drain.
     #
-    # @return [Boolean] true if transition was successful
+    # @return [Boolean] `true` if transition was successful.
     def start!
       @lock.synchronize do
         return false unless stopped?
@@ -83,12 +82,12 @@ module PatientHttp
       true
     end
 
-    # Transition to running state.
+    # Transitions to running state.
     #
     # The transition only occurs from the starting state so that a reactor
     # that already failed and transitioned to stopped is not overwritten.
     #
-    # @return [Boolean] true if transition was successful
+    # @return [Boolean] `true` if transition was successful.
     def running!
       @lock.synchronize do
         return false unless starting?
@@ -99,9 +98,9 @@ module PatientHttp
       true
     end
 
-    # Transition to draining state.
+    # Transitions to draining state.
     #
-    # @return [Boolean] true if transition was successful
+    # @return [Boolean] `true` if transition was successful.
     def drain!
       @lock.synchronize do
         return false unless running?
@@ -112,9 +111,9 @@ module PatientHttp
       true
     end
 
-    # Transition to stopping state.
+    # Transitions to stopping state.
     #
-    # @return [Boolean] true if transition was successful
+    # @return [Boolean] `true` if transition was successful.
     def stop!
       @lock.synchronize do
         return false if stopped? || stopping? || starting?
@@ -126,7 +125,7 @@ module PatientHttp
       true
     end
 
-    # Transition to stopped state.
+    # Transitions to stopped state.
     #
     # Also signals the reactor_ready event to unblock any thread
     # waiting in {#wait_for_reactor} in case the reactor failed
@@ -138,41 +137,41 @@ module PatientHttp
       @reactor_ready.set
     end
 
-    # Signal that the reactor is ready.
+    # Signals that the reactor is ready.
     #
     # @return [void]
     def reactor_ready!
       @reactor_ready.set
     end
 
-    # Wait for the reactor to be ready.
+    # Waits for the reactor to be ready.
     #
-    # @param timeout [Numeric, nil] maximum time to wait in seconds (nil waits forever)
-    # @return [Boolean] true if the reactor is ready, false if the timeout was reached
+    # @param timeout [Numeric, nil] Maximum time to wait in seconds (nil waits forever).
+    # @return [Boolean] `true` if the reactor is ready, false if the timeout was reached.
     def wait_for_reactor(timeout: nil)
       @reactor_ready.wait(timeout)
     end
 
-    # Check if shutdown has been signaled.
+    # Returns whether shutdown has been signaled.
     #
-    # @return [Boolean] true if shutdown is signaled
+    # @return [Boolean] `true` if shutdown is signaled.
     def shutdown_signaled?
       @shutdown_barrier.set?
     end
 
-    # Wait for running state.
+    # Waits for running state.
     #
-    # @param timeout [Numeric] maximum time to wait in seconds
-    # @return [Boolean] true if running, false if timeout reached
+    # @param timeout [Numeric] Maximum time to wait in seconds.
+    # @return [Boolean] `true` if running, false if timeout reached.
     def wait_for_running(timeout: 5)
       wait_for_condition(timeout: timeout) { running? }
     end
 
-    # Wait for a condition to be met.
+    # Waits for a condition to be met.
     #
-    # @param timeout [Numeric] maximum time to wait in seconds
-    # @yield Block that checks the condition.
-    # @return [Boolean] true if the condition is met, false if timeout reached
+    # @param timeout [Numeric] Maximum time to wait in seconds.
+    # @yield The block that checks the condition.
+    # @return [Boolean] `true` if the condition is met, false if timeout reached.
     def wait_for_condition(timeout: 1)
       deadline = monotonic_time + timeout
       while monotonic_time <= deadline

data/lib/patient_http/outgoing_request.rb

@@ -1,35 +1,37 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # A mutable view of a request as it is about to be sent, after secret references
-  # have been resolved and the send-time headers (x-request-id and the default
-  # user-agent) have been set.
+  # A request immediately before it's sent. Secret references are resolved, and
+  # the `x-request-id` and default `user-agent` headers are set.
   #
-  # Preprocessors attached to a request receive this object and can modify the
-  # headers or append query parameters before the request goes out -- for example,
-  # to sign the request. The HTTP method, URL, and body are read-only; headers can
-  # be changed in place and query parameters appended with {#add_param}.
+  # Preprocessors receive this object. They can change the headers and add
+  # query parameters, for example to sign the request. The HTTP method, URL,
+  # and body are read-only. Change the headers in place, and add query
+  # parameters with {#add_param}.
   #
   # @see Configuration#register_preprocessor
   class OutgoingRequest
-    # @return [Symbol] HTTP method (:get, :head, :post, :put, :patch, :delete, :query)
+    # @return [Symbol] The HTTP method: `:get`, `:head`, `:post`, `:put`,
+    #   `:patch`, `:delete`, or `:query`.
     attr_reader :http_method
 
-    # @return [String] the request URL with any secret query params already resolved
+    # @return [String] The request URL, with the secret query parameters
+    #   resolved.
     attr_reader :url
 
-    # @return [String, nil] the request body
+    # @return [String, nil] The request body.
     attr_reader :body
 
-    # @return [HttpHeaders] mutable, case-insensitive request headers
+    # @return [HttpHeaders] The request headers. You can change them. Names are
+    #   case insensitive.
     attr_reader :headers
 
-    # Initialize a new OutgoingRequest.
+    # Creates an outgoing request.
     #
-    # @param http_method [Symbol] the HTTP method
-    # @param url [String] the resolved request URL
-    # @param headers [HttpHeaders] the resolved request headers
-    # @param body [String, nil] the request body
+    # @param http_method [Symbol] The HTTP method.
+    # @param url [String] The request URL, with secrets resolved.
+    # @param headers [HttpHeaders] The request headers, with secrets resolved.
+    # @param body [String, nil] The request body.
     def initialize(http_method:, url:, headers:, body:)
       @http_method = http_method
       @url = url.to_s
@@ -37,11 +39,11 @@ module PatientHttp
       @body = body
     end
 
-    # Append a query parameter to the request URL.
+    # Adds a query parameter to the request URL.
     #
-    # @param name [String, Symbol] the parameter name
-    # @param value [Object] the parameter value
-    # @return [String] the updated URL
+    # @param name [String, Symbol] The parameter name.
+    # @param value [Object] The parameter value.
+    # @return [String] The new URL.
     def add_param(name, value)
       serialized_param = URI.encode_www_form([[name.to_s, value]])
       uri = URI(@url)
@@ -49,10 +51,10 @@ module PatientHttp
       @url = uri.to_s
     end
 
-    # Inspect the outgoing request. Header values, the query string, and the body
-    # are not shown since they may contain resolved secrets.
+    # Returns a description of the request. It doesn't show the header values,
+    # the query string, or the body, because they can contain secrets.
     #
-    # @return [String]
+    # @return [String] The description.
     def inspect
       "#<#{self.class.name} #{http_method.to_s.upcase} #{redacted_url} headers=#{headers.to_h.keys.inspect}>"
     end