patient_http 1.6.1 → 1.8.0

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")
 
@@ -88,23 +89,45 @@ module PatientHttp
           headers_hash.merge("content-encoding" => remaining.join(", "))
         end
       end
+
+      # Runs a block that waits for data from the server, and stops it if no
+      # data arrives in time. Each call starts a new timer, so call it once for
+      # each wait: once for the response headers and once for each body chunk.
+      #
+      # The block must run in an Async task.
+      #
+      # @param read_timeout [Numeric, nil] The maximum number of seconds to wait.
+      #   If `nil`, the block runs without a limit.
+      # @yield Waits for data from the server.
+      # @return [Object] The value of the block.
+      # @raise [ReadTimeoutError] If the block doesn't finish in time.
+      def with_read_timeout(read_timeout, &block)
+        return yield if read_timeout.nil?
+
+        Async::Task.current.with_timeout(
+          read_timeout,
+          ReadTimeoutError,
+          "No data received from the server for #{read_timeout} seconds",
+          &block
+        )
+      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
@@ -114,24 +137,47 @@ module PatientHttp
     # bytes and {#decode_body} applies the same limit to the inflated bytes.
     #
     # The Content-Length header is checked against the size limit before the
-    # read starts. A response to a HEAD request has an empty body but reports
-    # the Content-Length of the resource, so the header check is skipped when
-    # the body reports itself as empty.
+    # read starts. The HTTP/1 parser moves that header into the body, so the
+    # length of the body is used when the header is not present. A response to
+    # a HEAD request has an empty body but reports the Content-Length of the
+    # resource, so the check is skipped when the body reports itself as empty.
+    #
+    # A read timeout limits the wait for each chunk. The timer starts again
+    # each time a chunk arrives, so a body that arrives slowly but steadily is
+    # read to the end.
     #
-    # @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)
+    # @param async_response [Async::HTTP::Protocol::Response] The async HTTP response.
+    # @param headers_hash [Hash] The response headers.
+    # @param max_response_size [Integer, nil] The size limit in bytes. If `nil`,
+    #   the configuration value applies.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   each chunk. If `nil`, there is no limit.
+    # @return [Array<String>, nil] The raw body chunks or nil if no body present.
+    # @raise [ResponseTooLargeError] If the body exceeds max_response_size.
+    # @raise [ReadTimeoutError] If no chunk arrives within the read timeout.
+    # @raise [ReadAbortedError] If the processor stopped past its shutdown deadline mid-read.
+    def read_raw_body(async_response, headers_hash, max_response_size: nil, read_timeout: nil)
       body = async_response.body
       return nil unless body
 
-      validate_content_length(headers_hash) unless body.empty?
-      read_body_chunks(async_response)
+      limit = max_response_size || @config.max_response_size
+      error = nil
+
+      begin
+        validate_content_length(headers_hash, body, limit) unless body.empty?
+        read_body_chunks(body, limit, read_timeout)
+      rescue => e
+        error = e
+        raise
+      ensure
+        # Always close the body. A body that is closed with an error discards
+        # its connection, so a connection that is not fully read is not
+        # returned to the pool.
+        body.close(error)
+      end
     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,17 +190,20 @@ 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
-    def decode_body(chunks, headers_hash)
+    # @param chunks [Array<String>, nil] The raw body chunks.
+    # @param headers_hash [Hash] The response headers.
+    # @param max_response_size [Integer, nil] The size limit in bytes for the
+    #   inflated body. If `nil`, the configuration value applies.
+    # @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, max_response_size: nil)
       return nil if chunks.nil?
 
       remaining, decodable = self.class.split_encodings(headers_hash)
       warn_undecodable(remaining) unless remaining.empty?
 
-      body = inflate_encodings(chunks, decodable).join
+      limit = max_response_size || @config.max_response_size
+      body = inflate_encodings(chunks, decodable, limit).join
       body.force_encoding(Encoding::ASCII_8BIT)
       # A body that is still encoded is not text yet, so the charset does not
       # describe its bytes. Leave it binary for the caller to decode.
@@ -165,46 +214,48 @@ 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
-    def inflate_encodings(chunks, encodings)
+    # @param chunks [Array<String>] The encoded body chunks.
+    # @param encodings [Array<String>] Decodable encoding names in applied order.
+    # @param limit [Integer] The size limit in bytes for the inflated body.
+    # @return [Array<String>] The decoded chunks.
+    # @raise [ResponseTooLargeError] If the inflated body exceeds the limit.
+    def inflate_encodings(chunks, encodings, limit)
       encodings.reverse_each do |name|
-        chunks = [inflate_encoding(chunks, name)] if INFLATE_WINDOW_BITS.key?(name)
+        chunks = [inflate_encoding(chunks, name, limit)] if INFLATE_WINDOW_BITS.key?(name)
       end
 
       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
-    def inflate_encoding(chunks, name)
+    # @param chunks [Array<String>] The encoded body chunks.
+    # @param name [String] A lowercased content encoding name.
+    # @param limit [Integer] The size limit in bytes for the inflated body.
+    # @return [String] The inflated body.
+    # @raise [Zlib::Error] If no format could inflate the body.
+    # @raise [ResponseTooLargeError] If the inflated body exceeds the limit.
+    def inflate_encoding(chunks, name, limit)
       formats = INFLATE_WINDOW_BITS.fetch(name)
       last_index = formats.size - 1
 
       formats.each_with_index do |window_bits, index|
-        return inflate_chunks(chunks, window_bits)
+        return inflate_chunks(chunks, window_bits, limit)
       rescue Zlib::DataError, Zlib::BufError
         raise if index == last_index
       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(
@@ -214,77 +265,74 @@ module PatientHttp
       nil
     end
 
-    def max_response_size
-      @config.max_response_size
-    end
-
     def logger
       @config.logger
     end
 
-    # Validate content-length header doesn't exceed max size.
+    # Validates the declared body length doesn't exceed max 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
+    # @param headers_hash [Hash] The response headers.
+    # @param body [Protocol::HTTP::Body::Readable] The response body.
+    # @param limit [Integer] The size limit in bytes.
+    # @raise [ResponseTooLargeError] If the declared length exceeds the limit.
+    def validate_content_length(headers_hash, body, limit)
+      content_length = headers_hash["content-length"]&.to_i || body.length
+      if content_length && content_length > limit
         raise ResponseTooLargeError.new(
-          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{max_response_size} bytes)"
+          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{limit} bytes)"
         )
       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
-    def read_body_chunks(async_response)
+    # Each chunk is read with its own read timeout, so the timer starts again
+    # after every chunk.
+    #
+    # @param body [Protocol::HTTP::Body::Readable] The response body.
+    # @param limit [Integer] The size limit in bytes.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   each chunk.
+    # @return [Array<String>] The raw body chunks.
+    # @raise [ResponseTooLargeError] If body size exceeds the limit during read.
+    # @raise [ReadTimeoutError] If no chunk arrives within the read timeout.
+    # @raise [ReadAbortedError] If the processor stopped past its shutdown deadline mid-read.
+    def read_body_chunks(body, limit, read_timeout)
       chunks = []
       total_size = 0
-      finished = false
 
-      begin
-        async_response.body.each do |chunk|
-          # Abort the read once the processor has passed its shutdown deadline.
-          # Reads are allowed to finish while the processor is merely stopping
-          # (the graceful shutdown window) so in-flight responses can still be
-          # delivered.
-          if @processor&.stopped?
-            raise ReadAbortedError.new("Processor stopped while reading response body")
-          end
-
-          total_size += chunk.bytesize
-
-          if total_size > max_response_size
-            raise ResponseTooLargeError.new(
-              "Response body size exceeded maximum allowed size (#{max_response_size} bytes)"
-            )
-          end
-
-          chunks << chunk
+      while (chunk = self.class.with_read_timeout(read_timeout) { body.read })
+        # Abort the read once the processor has passed its shutdown deadline.
+        # Reads are allowed to finish while the processor is merely stopping
+        # (the graceful shutdown window) so in-flight responses can still be
+        # delivered.
+        if @processor&.stopped?
+          raise ReadAbortedError.new("Processor stopped while reading response body")
         end
 
-        finished = true
+        total_size += chunk.bytesize
 
-        chunks
-      ensure
-        # Always close the body if we were interrupted or if an error occurred
-        # This ensures the connection is properly released back to the pool
-        async_response.body.close unless finished
+        if total_size > limit
+          raise ResponseTooLargeError.new(
+            "Response body size exceeded maximum allowed size (#{limit} bytes)"
+          )
+        end
+
+        chunks << chunk
       end
+
+      chunks
     end
 
-    # Inflate compressed body chunks with streaming size enforcement, so a
-    # small compressed body cannot expand past max_response_size.
+    # Inflates compressed body chunks with streaming size enforcement, so a
+    # small compressed body cannot expand past the size limit.
     #
-    # @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)
+    # @param chunks [Array<String>] The raw compressed chunks.
+    # @param window_bits [Integer] Zlib window bits for the content encoding.
+    # @param limit [Integer] The size limit in bytes for the inflated body.
+    # @return [String] The inflated body.
+    # @raise [ResponseTooLargeError] If the inflated size exceeds the limit.
+    def inflate_chunks(chunks, window_bits, limit)
       # A response can declare a content encoding and still carry no body.
       # There is nothing to inflate, and finishing an empty stream would
       # raise a buffer error.
@@ -300,7 +348,7 @@ module PatientHttp
         # before any check runs.
         appender = ->(output) do
           body << output
-          validate_inflated_size(body)
+          validate_inflated_size(body, limit)
         end
 
         chunks.each { |chunk| inflater.inflate(chunk, &appender) }
@@ -312,18 +360,18 @@ module PatientHttp
       body
     end
 
-    def validate_inflated_size(body)
-      if body.bytesize > max_response_size
+    def validate_inflated_size(body, limit)
+      if body.bytesize > limit
         raise ResponseTooLargeError.new(
-          "Response body size exceeded maximum allowed size (#{max_response_size} bytes)"
+          "Response body size exceeded maximum allowed size (#{limit} bytes)"
         )
       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 +383,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?