patient_http 1.6.0 → 1.7.0

data/lib/patient_http/response.rb

@@ -1,43 +1,45 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Represents an HTTP response from an async request.
+  # The HTTP response to an async request.
   #
-  # This class encapsulates the response data including status, headers, body,
-  # and metadata about the request that generated it.
+  # A response holds the status, headers, and body, and details about the
+  # request that returned it. Responses can be serialized to JSON, so they can
+  # go through a job queue.
   class Response
     UNDEFINED = Object.new.freeze
     private_constant :UNDEFINED
 
-    # @return [Integer] HTTP status code
+    # @return [Integer] The HTTP status code.
     attr_reader :status
 
-    # Response headers. Headers that appeared multiple times in the response
-    # (such as set-cookie) are flattened into a single joined string value.
+    # The response headers. A header that occurs more than one time in the
+    # response, such as `set-cookie`, becomes one string with the values joined.
     #
-    # @return [HttpHeaders] response headers
+    # @return [HttpHeaders] The response headers.
     attr_reader :headers
 
-    # @return [Float] request duration in seconds
+    # @return [Float] The request duration in seconds.
     attr_reader :duration
 
-    # @return [String] request ID
+    # @return [String] The request ID.
     attr_reader :request_id
 
-    # @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 [Array<String>] URLs visited during redirect chain (empty if no redirects)
+    # @return [Array<String>] The URLs of the redirects that were followed, in
+    #   order. Empty if no redirects were followed.
     attr_reader :redirects
 
     class << self
-      # Reconstruct a Response from a hash
+      # Creates a response from its serialized form.
       #
-      # @param hash [Hash] hash representation
-      # @return [Response] reconstructed response
+      # @param hash [Hash] The hash from {#as_json}.
+      # @return [Response] The response.
       def load(hash)
         new(
           status: hash["status"],
@@ -53,17 +55,18 @@ module PatientHttp
       end
     end
 
-    # Initialize a Response from an Async::HTTP::Response
+    # Creates a response.
     #
-    # @param status [Integer] HTTP status code
-    # @param headers [Hash, HttpHeaders] response headers
-    # @param body [String, nil] response body
-    # @param duration [Float] request duration in seconds
-    # @param request_id [String] the request ID
-    # @param url [String] the request URL
-    # @param http_method [Symbol] the HTTP method
-    # @param callback_args [Hash, nil] callback arguments (string keys)
-    # @param redirects [Array<String>, nil] URLs visited during redirect chain
+    # @param status [Integer] The HTTP status code.
+    # @param headers [Hash, HttpHeaders] The response headers.
+    # @param body [String, nil] The response body.
+    # @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] The HTTP method.
+    # @param callback_args [Hash, nil] The callback arguments, with string keys.
+    # @param redirects [Array<String>, nil] The URLs of the redirects that were
+    #   followed.
     def initialize(status:, headers:, body:, duration:, request_id:, url:, http_method:, callback_args: nil, redirects: nil)
       @status = status
       @headers = HttpHeaders.new(headers)
@@ -80,76 +83,78 @@ module PatientHttp
       @redirects = redirects || []
     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
 
-    # Returns the response body, decoding it from the payload if necessary.
+    # Returns the response body. The body is decoded on first access.
     #
-    # @return [String, nil] The decoded response body or nil if there was no body.
+    # @return [String, nil] The response body, or `nil` if the response has no
+    #   body.
     def body
       @body = @payload&.value if @body.equal?(UNDEFINED)
       @body
     end
 
-    # Check if response is successful (2xx status)
+    # Returns whether the status is 2xx.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` if the request succeeded.
     def success?
       status >= 200 && status < 300
     end
 
-    # Check if response is a redirect (3xx status)
+    # Returns whether the status is 3xx.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` if the response is a redirect.
     def redirect?
       status >= 300 && status < 400
     end
 
-    # Check if response is a client error (4xx status)
+    # Returns whether the status is 4xx.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` if the response is a client error.
     def client_error?
       status >= 400 && status < 500
     end
 
-    # Check if response is a server error (5xx status)
+    # Returns whether the status is 5xx.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` if the response is a server error.
     def server_error?
       status >= 500 && status < 600
     end
 
-    # Check if response is any error (4xx or 5xx status)
+    # Returns whether the status is 4xx or 5xx.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` if the response is an error.
     def error?
       status >= 400 && status < 600
     end
 
-    # Get the Content-Type header
+    # Returns the value of the `content-type` header.
     #
-    # @return [String, nil]
+    # @return [String, nil] The content type, or `nil` if the header isn't set.
     def content_type
       headers["content-type"]
     end
 
-    # Return true if Content-Type indicates JSON.
+    # Returns whether the `content-type` header identifies a JSON body.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` if the body is JSON.
     def json?
       type = content_type.to_s.downcase
       type.match?(%r{\Aapplication/[^ ]*json\b}) || type == "text/json"
     end
 
-    # Parse response body as JSON
+    # Parses the response body as JSON.
     #
-    # @return [Hash, Array] parsed JSON
-    # @raise [RuntimeError] if Content-Type is not application/json
-    # @raise [JSON::ParserError] if body is not valid JSON
+    # @return [Hash, Array] The parsed body.
+    # @raise [RuntimeError] If the `content-type` header doesn't identify a JSON
+    #   body.
+    # @raise [JSON::ParserError] If the body isn't valid JSON.
     def json
       unless json?
         raise "Response Content-Type is not application/json (got: #{content_type.inspect})"
@@ -158,9 +163,9 @@ module PatientHttp
       JSON.parse(body)
     end
 
-    # Serialize to JSON hash.
+    # Returns the response as a JSON-compatible hash.
     #
-    # @return [Hash]
+    # @return [Hash] The serialized response.
     def as_json
       {
         "status" => status,
@@ -175,10 +180,11 @@ module PatientHttp
       }
     end
 
-    # Serialize to JSON string.
+    # Returns the response as a JSON string.
     #
-    # @param options [Hash] options to pass to JSON.generate (for ActiveSupport compatibility)
-    # @return [String] JSON representation
+    # @param options [Hash, nil] The options for `JSON.generate`. This parameter
+    #   makes the method compatible with Active Support.
+    # @return [String] The JSON string.
     def to_json(options = nil)
       JSON.generate(as_json, options)
     end

data/lib/patient_http/response_reader.rb

@@ -3,11 +3,12 @@
 module PatientHttp
   # Reads and decodes HTTP response bodies.
   #
-  # Reading happens on the reactor thread and collects the raw (possibly
-  # compressed) body chunks with size validation. Decoding — joining the
-  # chunks, inflating compressed content, and applying the charset — is a
-  # separate step so it can run on a completion worker thread instead of
-  # blocking the event loop.
+  # The reactor thread reads the raw body chunks, which can be compressed, and
+  # checks their size. Decoding is a separate step that runs on a completion
+  # worker thread, so it doesn't block the reactor. Decoding joins the chunks,
+  # decompresses them, and applies the charset.
+  #
+  # @api private
   class ResponseReader
     # Raised when a body read is aborted because the processor was stopped
     # past its shutdown deadline. The shutdown sequence re-enqueues the task,
@@ -34,7 +35,7 @@ module PatientHttp
     IDENTITY_ENCODING = "identity"
 
     class << self
-      # Split the encodings named in the content-encoding header into the ones
+      # Splits the encodings named in the content-encoding header into the ones
       # that stay applied to the body and the ones that can be decoded.
       #
       # A body can carry more than one encoding. They are listed in the order
@@ -42,9 +43,9 @@ module PatientHttp
       # stops at the first name it does not recognize. Everything before that
       # point stays applied to the body.
       #
-      # @param headers_hash [Hash] the response headers
-      # @return [Array(Array<String>, Array<String>)] the encodings that remain
-      #   applied and the encodings that can be decoded, both in applied order
+      # @param headers_hash [Hash] The response headers.
+      # @return [Array(Array<String>, Array<String>)] The encodings that remain
+      #   applied and the encodings that can be decoded, both in applied order.
       def split_encodings(headers_hash)
         encodings = content_encodings(headers_hash)
         boundary = encodings.rindex { |name| !decodable?(name) }
@@ -53,10 +54,10 @@ module PatientHttp
         [encodings[0..boundary], encodings[(boundary + 1)..]]
       end
 
-      # Parse the content-encoding header into encoding names.
+      # Parses the content-encoding header into encoding names.
       #
-      # @param headers_hash [Hash] the response headers
-      # @return [Array<String>] the lowercased encoding names in applied order
+      # @param headers_hash [Hash] The response headers.
+      # @return [Array<String>] The lowercased encoding names in applied order.
       def content_encodings(headers_hash)
         headers_hash["content-encoding"].to_s.split(",").filter_map do |name|
           name = name.strip.downcase
@@ -64,19 +65,19 @@ module PatientHttp
         end
       end
 
-      # @param name [String] a lowercased content encoding name
-      # @return [Boolean] true if the reader can remove this encoding
+      # @param name [String] A lowercased content encoding name.
+      # @return [Boolean] `true` if the reader can remove this encoding.
       def decodable?(name)
         name == IDENTITY_ENCODING || INFLATE_WINDOW_BITS.key?(name)
       end
 
-      # Restate the content-encoding header for a decoded body. The header is
+      # Restates the content-encoding header for a decoded body. The header is
       # removed when nothing is left applied, and narrowed to the encodings the
       # reader could not remove otherwise, so the header always describes the
       # body delivered with it.
       #
-      # @param headers_hash [Hash] the response headers
-      # @return [Hash] the headers with content-encoding updated or removed
+      # @param headers_hash [Hash] The response headers.
+      # @return [Hash] The headers with content-encoding updated or removed.
       def rewrite_content_encoding(headers_hash)
         return headers_hash unless headers_hash.key?("content-encoding")
 
@@ -90,21 +91,21 @@ module PatientHttp
       end
     end
 
-    # Initialize the reader.
+    # Creates the reader.
     #
     # Reading needs a processor so it can abort once the processor is past its
     # shutdown deadline. Decoding needs only the configuration, so a caller
     # that does its own reading can supply the configuration on its own.
     #
-    # @param processor [Processor, nil] the processor object
-    # @param config [Configuration, nil] the configuration; defaults to the
-    #   processor's configuration
+    # @param processor [Processor, nil] The processor object.
+    # @param config [Configuration, nil] The configuration; defaults to the
+    #   processor's configuration.
     def initialize(processor, config: nil)
       @processor = processor
       @config = config || processor.config
     end
 
-    # Read the raw response body chunks with size validation.
+    # Reads the raw response body chunks with size validation.
     #
     # Reads the async HTTP response body asynchronously to completion, which allows
     # the connection to be reused. The async-http client handles connection pooling
@@ -118,11 +119,11 @@ module PatientHttp
     # the Content-Length of the resource, so the header check is skipped when
     # the body reports itself as empty.
     #
-    # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
-    # @param headers_hash [Hash] the response headers
-    # @return [Array<String>, nil] the raw body chunks or nil if no body present
-    # @raise [ResponseTooLargeError] if the body exceeds max_response_size
-    # @raise [ReadAbortedError] if the processor stopped past its shutdown deadline mid-read
+    # @param async_response [Async::HTTP::Protocol::Response] The async HTTP response.
+    # @param headers_hash [Hash] The response headers.
+    # @return [Array<String>, nil] The raw body chunks or nil if no body present.
+    # @raise [ResponseTooLargeError] If the body exceeds max_response_size.
+    # @raise [ReadAbortedError] If the processor stopped past its shutdown deadline mid-read.
     def read_raw_body(async_response, headers_hash)
       body = async_response.body
       return nil unless body
@@ -131,7 +132,7 @@ module PatientHttp
       read_body_chunks(async_response)
     end
 
-    # Decode raw body chunks into the final body string.
+    # Decodes raw body chunks into the final body string.
     #
     # Joins the chunks, inflates gzip/deflate content (enforcing
     # max_response_size on the inflated bytes), and applies the charset from
@@ -144,10 +145,10 @@ module PatientHttp
     # so the content-encoding header delivered with the response describes the
     # body it carries.
     #
-    # @param chunks [Array<String>, nil] the raw body chunks
-    # @param headers_hash [Hash] the response headers
-    # @return [String, nil] the decoded body or nil if there was no body
-    # @raise [ResponseTooLargeError] if the inflated body exceeds max_response_size
+    # @param chunks [Array<String>, nil] The raw body chunks.
+    # @param headers_hash [Hash] The response headers.
+    # @return [String, nil] The decoded body or nil if there was no body.
+    # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
     def decode_body(chunks, headers_hash)
       return nil if chunks.nil?
 
@@ -165,13 +166,13 @@ module PatientHttp
 
     private
 
-    # Remove the given encodings from the body, starting with the one applied
+    # Removes the given encodings from the body, starting with the one applied
     # last. Identity needs no work; every other name here inflates.
     #
-    # @param chunks [Array<String>] the encoded body chunks
-    # @param encodings [Array<String>] decodable encoding names in applied order
-    # @return [Array<String>] the decoded chunks
-    # @raise [ResponseTooLargeError] if the inflated body exceeds max_response_size
+    # @param chunks [Array<String>] The encoded body chunks.
+    # @param encodings [Array<String>] Decodable encoding names in applied order.
+    # @return [Array<String>] The decoded chunks.
+    # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
     def inflate_encodings(chunks, encodings)
       encodings.reverse_each do |name|
         chunks = [inflate_encoding(chunks, name)] if INFLATE_WINDOW_BITS.key?(name)
@@ -180,15 +181,15 @@ module PatientHttp
       chunks
     end
 
-    # Inflate one encoding, trying each wire format the encoding can use. The
+    # Inflates one encoding, trying each wire format the encoding can use. The
     # chunks are all in memory, so a format that turns out to be wrong can be
     # abandoned and the next one started from the beginning of the body.
     #
-    # @param chunks [Array<String>] the encoded body chunks
-    # @param name [String] a lowercased content encoding name
-    # @return [String] the inflated body
-    # @raise [Zlib::Error] if no format could inflate the body
-    # @raise [ResponseTooLargeError] if the inflated body exceeds max_response_size
+    # @param chunks [Array<String>] The encoded body chunks.
+    # @param name [String] A lowercased content encoding name.
+    # @return [String] The inflated body.
+    # @raise [Zlib::Error] If no format could inflate the body.
+    # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
     def inflate_encoding(chunks, name)
       formats = INFLATE_WINDOW_BITS.fetch(name)
       last_index = formats.size - 1
@@ -200,11 +201,11 @@ module PatientHttp
       end
     end
 
-    # Report an encoding that could not be removed. The body is still delivered
+    # Reports an encoding that could not be removed. The body is still delivered
     # with its content-encoding header, so the caller can decode it, but the
     # server ignored the accept-encoding header and that is worth recording.
     #
-    # @param remaining [Array<String>] the encodings left on the body
+    # @param remaining [Array<String>] The encodings left on the body.
     # @return [void]
     def warn_undecodable(remaining)
       logger&.warn(
@@ -222,10 +223,10 @@ module PatientHttp
       @config.logger
     end
 
-    # Validate content-length header doesn't exceed max size.
+    # Validates content-length header doesn't exceed max size.
     #
-    # @param headers_hash [Hash] the response headers
-    # @raise [ResponseTooLargeError] if content-length exceeds max_response_size
+    # @param headers_hash [Hash] The response headers.
+    # @raise [ResponseTooLargeError] If content-length exceeds max_response_size.
     def validate_content_length(headers_hash)
       content_length = headers_hash["content-length"]&.to_i
       if content_length && content_length > max_response_size
@@ -235,12 +236,12 @@ module PatientHttp
       end
     end
 
-    # Read body chunks while checking size.
+    # Reads body chunks while checking size.
     #
-    # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
-    # @return [Array<String>] the raw body chunks
-    # @raise [ResponseTooLargeError] if body size exceeds max_response_size during read
-    # @raise [ReadAbortedError] if the processor stopped past its shutdown deadline mid-read
+    # @param async_response [Async::HTTP::Protocol::Response] The async HTTP response.
+    # @return [Array<String>] The raw body chunks.
+    # @raise [ResponseTooLargeError] If body size exceeds max_response_size during read.
+    # @raise [ReadAbortedError] If the processor stopped past its shutdown deadline mid-read.
     def read_body_chunks(async_response)
       chunks = []
       total_size = 0
@@ -277,13 +278,13 @@ module PatientHttp
       end
     end
 
-    # Inflate compressed body chunks with streaming size enforcement, so a
+    # Inflates compressed body chunks with streaming size enforcement, so a
     # small compressed body cannot expand past max_response_size.
     #
-    # @param chunks [Array<String>] the raw compressed chunks
-    # @param window_bits [Integer] Zlib window bits for the content encoding
-    # @return [String] the inflated body
-    # @raise [ResponseTooLargeError] if the inflated size exceeds max_response_size
+    # @param chunks [Array<String>] The raw compressed chunks.
+    # @param window_bits [Integer] Zlib window bits for the content encoding.
+    # @return [String] The inflated body.
+    # @raise [ResponseTooLargeError] If the inflated size exceeds max_response_size.
     def inflate_chunks(chunks, window_bits)
       # A response can declare a content encoding and still carry no body.
       # There is nothing to inflate, and finishing an empty stream would
@@ -320,10 +321,10 @@ module PatientHttp
       end
     end
 
-    # Extract charset from Content-Type header.
+    # Extracts charset from Content-Type header.
     #
-    # @param headers_hash [Hash] the response headers
-    # @return [String, nil] the charset name or nil if not specified
+    # @param headers_hash [Hash] The response headers.
+    # @return [String, nil] The charset name or nil if not specified.
     def extract_charset(headers_hash)
       content_type = headers_hash["content-type"]
       return nil unless content_type
@@ -335,14 +336,14 @@ module PatientHttp
       charset.gsub(/\A["']|["']\z/, "")
     end
 
-    # Apply charset encoding to response body.
+    # Applies charset encoding to response body.
     #
     # Sets the string encoding based on the charset specified in the Content-Type header.
     # Falls back to ASCII-8BIT if charset is invalid or not recognized.
     #
-    # @param body [String] the response body
-    # @param headers_hash [Hash] the response headers
-    # @return [String] the body with proper encoding set
+    # @param body [String] The response body.
+    # @param headers_hash [Hash] The response headers.
+    # @return [String] The body with proper encoding set.
     def apply_charset_encoding(body, headers_hash)
       return body unless body
 

data/lib/patient_http/secret_manager.rb

@@ -1,41 +1,38 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Resolves {SecretReference} values into their actual secret values when a request
-  # is sent by the processor.
+  # Replaces {SecretReference} values with the secret values when the processor
+  # sends a request.
   #
-  # A SecretManager is built from the secrets registered on the {Configuration}.
+  # The manager holds the secrets registered in the {Configuration}.
   #
   # @see Configuration#secret_manager
   class SecretManager
-    # Raised when a referenced secret cannot be resolved.
+    # Raised when a referenced secret isn't registered.
     class SecretNotFoundError < StandardError; end
 
-    # Initialize a new SecretManager.
+    # Creates a secret manager.
     #
-    # @param secrets [Hash{String => Object}] static registry mapping names to values
-    #   (a value may be a callable, which is invoked with the name to produce the value)
-    #   secret not found in the static registry
+    # @param secrets [Hash{String => Object}] The secret values, keyed by name. A
+    #   value can be a callable, which is called with the name to get the value.
     def initialize(secrets: {})
       @secrets = secrets || {}
     end
 
-    # Check if a secret name is registered in the static registry.
+    # Returns whether a secret is registered.
     #
-    # @param name [String, Symbol] the secret name
-    # @return [Boolean] true if the name is registered, false otherwise
+    # @param name [String, Symbol] The secret name.
+    # @return [Boolean] `true` if the secret is registered.
     def include?(name)
       @secrets.include?(name.to_s)
     end
 
-    # Resolve a secret by name.
+    # Returns the value of a secret. If the registered value responds to `call`,
+    # it's called with the name.
     #
-    # The static registry is checked first; if the registered value responds to #call
-    # it is invoked with the name. If the name is not in the registry, an error is raised.
-    #
-    # @param name [String, Symbol] the secret name
-    # @return [String] the resolved secret value
-    # @raise [SecretNotFoundError] if the secret cannot be resolved
+    # @param name [String, Symbol] The secret name.
+    # @return [String, nil] The secret value.
+    # @raise [SecretNotFoundError] If the secret isn't registered.
     def resolve(name)
       name = name.to_s
 
@@ -48,27 +45,34 @@ module PatientHttp
       value&.to_s
     end
 
-    # Resolve any secret references in a headers hash, returning a new hash.
+    # Returns a copy of the headers with the secret references replaced by the
+    # secret values.
     #
-    # @param headers [Hash, nil] header name/value pairs
-    # @return [Hash, nil] a new hash with secret references replaced by resolved values
+    # @param headers [Hash, nil] The headers.
+    # @return [Hash, nil] The resolved headers.
+    # @raise [SecretNotFoundError] If a referenced secret isn't registered.
     def resolve_headers(headers)
       resolve_values(headers)
     end
 
-    # Resolve any secret references in a params hash, returning a new hash.
+    # Returns a copy of the query parameters with the secret references
+    # replaced by the secret values.
     #
-    # @param params [Hash, nil] param name/value pairs
-    # @return [Hash, nil] a new hash with secret references replaced by resolved values
+    # @param params [Hash, nil] The query parameters.
+    # @return [Hash, nil] The resolved query parameters.
+    # @raise [SecretNotFoundError] If a referenced secret isn't registered.
     def resolve_params(params)
       resolve_values(params)
     end
 
-    # Append resolved secret params to a URL's query string.
+    # Adds the resolved secret query parameters to a URL.
     #
-    # @param url [String] the request URL
-    # @param secret_params [Hash, nil] secret param name/value (SecretReference) pairs
-    # @return [String] the URL with resolved secret params appended (unchanged if none)
+    # @param url [String] The request URL.
+    # @param secret_params [Hash, nil] The query parameters whose values are
+    #   secret references.
+    # @return [String] The URL with the parameters added. If there are no
+    #   parameters, the URL is unchanged.
+    # @raise [SecretNotFoundError] If a referenced secret isn't registered.
     def resolve_url(url, secret_params)
       return url if secret_params.nil? || secret_params.empty?
 
@@ -80,8 +84,8 @@ module PatientHttp
 
     private
 
-    # Return a new hash with any secret-reference values replaced by their resolved
-    # values. Non-secret values are passed through unchanged.
+    # Returns a copy of a hash with the secret references replaced by the
+    # secret values. Other values are unchanged.
     def resolve_values(hash)
       return hash if hash.nil?