patient_http 1.3.0 → 1.5.0

data/lib/patient_http/processor_observer.rb

@@ -2,9 +2,31 @@
 
 module PatientHttp
   # Interface for observing request processing. A process observer can be registered with
-  # a Processor and receive events as requests are processed. Observers will run on the main
-  # processor thread and so should be lightweight and not do processing other than recording
-  # metrics or similar.
+  # a Processor and receive events as requests are processed. Observers should be
+  # lightweight and not do processing other than recording metrics or similar.
+  #
+  # 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
+  #
+  # 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.
   class ProcessorObserver
     # Called when the processor starts.
     #
@@ -24,6 +46,41 @@ module PatientHttp
     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.
+    #
+    # @param request_task [RequestTask] the request task that was enqueued
+    # @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.
+    #
+    # @param request_task [RequestTask] the request task that was rejected
+    # @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.
+    #
+    # @param request_task [RequestTask] the request task that was re-enqueued
+    # @return [void]
+    def request_requeued(request_task)
+    end
+
     # Called when a request starts processing.
     #
     # @param request_task [RequestTask] the request task that started
@@ -44,5 +101,16 @@ module PatientHttp
     # @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.
+    #
+    # @param request_task [RequestTask] the request task whose result was not delivered
+    # @param error [StandardError] the delivery failure
+    # @return [void]
+    def completion_failed(request_task, error)
+    end
   end
 end

data/lib/patient_http/request.rb

@@ -42,6 +42,11 @@ module PatientHttp
     #   to apply to the request when it is sent
     attr_reader :preprocessors
 
+    # @return [String, nil] Name of the processor that should execute the request.
+    #   Integrations use this to route the request to a named processor; nil
+    #   uses the default processor.
+    attr_reader :processor
+
     class << self
       # Reconstruct a Request from a hash
       #
@@ -56,7 +61,8 @@ module PatientHttp
           params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
           max_redirects: hash["max_redirects"],
-          preprocessors: hash["preprocessors"]
+          preprocessors: hash["preprocessors"],
+          processor: hash["processor"]
         )
       end
 
@@ -91,6 +97,8 @@ module PatientHttp
     # @param max_redirects [Integer, nil] Maximum redirects to follow (nil uses config, 0 disables).
     # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] Names of preprocessors
     #   registered on the configuration to apply to the request when it is sent.
+    # @param processor [String, Symbol, nil] Name of the processor that should execute the
+    #   request. Integrations use this to route the request to a named processor.
     def initialize(
       http_method,
       url,
@@ -100,7 +108,8 @@ module PatientHttp
       params: nil,
       timeout: nil,
       max_redirects: nil,
-      preprocessors: nil
+      preprocessors: nil,
+      processor: nil
     )
       @http_method = http_method.is_a?(String) ? http_method.downcase.to_sym : http_method
 
@@ -117,6 +126,7 @@ module PatientHttp
       @timeout = timeout
       @max_redirects = max_redirects
       @preprocessors = normalized_preprocessors(preprocessors)
+      @processor = normalized_processor(processor)
 
       if json
         raise ArgumentError.new("Cannot provide both body and json") if @body
@@ -158,6 +168,7 @@ module PatientHttp
       end
 
       hash["preprocessors"] = @preprocessors if @preprocessors.any?
+      hash["processor"] = @processor if @processor
 
       hash
     end
@@ -171,6 +182,16 @@ module PatientHttp
       end
     end
 
+    # Normalize the processor name to a frozen string or nil.
+    def normalized_processor(processor)
+      return nil if processor.nil?
+
+      name = processor.to_s
+      raise ArgumentError.new("processor name cannot be empty") if name.empty?
+
+      name.freeze
+    end
+
     # Normalize preprocessor names to a frozen array of strings.
     def normalized_preprocessors(preprocessors)
       names = Array(preprocessors).map(&:to_s)

data/lib/patient_http/request_helper.rb

@@ -116,14 +116,16 @@ module PatientHttp
       # @param timeout [Float] default timeout in seconds
       # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] default names of
       #   preprocessors registered on the configuration to apply to requests
+      # @param processor [String, Symbol, nil] default processor name for requests
       # @return [void]
-      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30, preprocessors: nil)
+      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30, preprocessors: nil, processor: nil)
         @patient_http_request_template = RequestTemplate.new(
           base_url: base_url,
           headers: headers,
           params: params,
           timeout: timeout,
-          preprocessors: preprocessors
+          preprocessors: preprocessors,
+          processor: processor
         )
       end
 
@@ -145,6 +147,8 @@ module PatientHttp
       # @param callback_args [Hash, nil] JSON-compatible callback arguments
       # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] names of preprocessors
       #   registered on the configuration to apply to the request when it is sent
+      # @param processor [String, Symbol, nil] name of the processor that should execute
+      #   the request
       # @return [Object] return value from the registered request handler
       def async_request(
         method,
@@ -157,10 +161,11 @@ module PatientHttp
         timeout: nil,
         raise_error_responses: nil,
         callback_args: nil,
-        preprocessors: nil
+        preprocessors: nil,
+        processor: nil
       )
         template = async_request_template
-        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout, preprocessors: preprocessors}
+        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout, preprocessors: preprocessors, processor: processor}
         request = if template
           template.request(method, url, **kwargs)
         else
@@ -206,6 +211,8 @@ module PatientHttp
     # @param callback_args [Hash, nil] JSON-compatible callback arguments
     # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] names of preprocessors
     #   registered on the configuration to apply to the request when it is sent
+    # @param processor [String, Symbol, nil] name of the processor that should execute
+    #   the request
     # @return [Object] return value from the registered request handler
     def async_request(
       method,
@@ -218,7 +225,8 @@ module PatientHttp
       timeout: nil,
       raise_error_responses: nil,
       callback_args: nil,
-      preprocessors: nil
+      preprocessors: nil,
+      processor: nil
     )
       self.class.async_request(
         method,
@@ -231,7 +239,8 @@ module PatientHttp
         timeout: timeout,
         raise_error_responses: raise_error_responses,
         callback_args: callback_args,
-        preprocessors: preprocessors
+        preprocessors: preprocessors,
+        processor: processor
       )
     end
 

data/lib/patient_http/request_preparer.rb

@@ -28,6 +28,13 @@ module PatientHttp
       headers = @config.secret_manager.resolve_headers(request.headers.to_h)
       headers["x-request-id"] = request_id
       headers["user-agent"] ||= @config.user_agent if @config.user_agent
+      # Compressed responses are inflated by ResponseReader during response
+      # decoding rather than by a client middleware wrapper. Requesting gzip is
+      # the default because it is what the reader can decode, but a caller that
+      # sets the header keeps its own value: "identity" opts out of compression,
+      # and any other encoding is delivered still encoded with its
+      # content-encoding header intact.
+      headers["accept-encoding"] ||= "gzip"
       url = @config.secret_manager.resolve_url(request.url, request.secret_params)
 
       outgoing = OutgoingRequest.new(

data/lib/patient_http/request_task.rb

@@ -236,7 +236,8 @@ module PatientHttp
         body: redirect_body,
         timeout: request.timeout,
         max_redirects: request.max_redirects,
-        preprocessors: redirect_preprocessors
+        preprocessors: redirect_preprocessors,
+        processor: request.processor
       )
 
       redirect_task_id = "#{id.split("/").first}/#{@redirects.size + 2}"

data/lib/patient_http/request_template.rb

@@ -34,12 +34,14 @@ module PatientHttp
     # @param timeout [Float] Default request timeout in seconds
     # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] Default preprocessors
     #   to apply to all requests
-    def initialize(base_url: nil, headers: {}, params: nil, timeout: 30, preprocessors: nil)
+    # @param processor [String, Symbol, nil] Default processor name for all requests
+    def initialize(base_url: nil, headers: {}, params: nil, timeout: 30, preprocessors: nil, processor: nil)
       @base_url = base_url
       @headers = HttpHeaders.new(headers)
       @params = params
       @timeout = timeout
       @preprocessors = preprocessors
+      @processor = processor
     end
 
     # Build an async HTTP request. Returns a Request object.
@@ -52,8 +54,10 @@ module PatientHttp
     # @param params [Hash, nil] query parameters to add to URL
     # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] preprocessors to apply
     #   to the request (overrides the template default)
+    # @param processor [String, Symbol, nil] processor name for the request (overrides the
+    #   template default)
     # @return [Request] request object
-    def request(method, uri, body: nil, json: nil, headers: nil, params: nil, timeout: nil, preprocessors: nil)
+    def request(method, uri, body: nil, json: nil, headers: nil, params: nil, timeout: nil, preprocessors: nil, processor: nil)
       full_uri = @base_url ? URI.join(@base_url, uri.to_s) : URI(uri)
 
       merged_headers = headers&.any? ? @headers.merge(headers) : @headers
@@ -68,7 +72,8 @@ module PatientHttp
         json: json,
         params: merged_params,
         timeout: timeout || @timeout,
-        preprocessors: preprocessors || @preprocessors
+        preprocessors: preprocessors || @preprocessors,
+        processor: processor || @processor
       )
     end
 

data/lib/patient_http/response_reader.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Reads and validates HTTP response bodies.
+  # Reads and decodes HTTP response bodies.
   #
-  # Encapsulates the logic for reading async HTTP responses with size validation
-  # and building Response objects from the raw response data.
+  # 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.
   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,
@@ -13,41 +16,204 @@ module PatientHttp
     # @api private
     class ReadAbortedError < StandardError; end
 
+    # Content encodings that are inflated during decoding, mapped to the window
+    # bits of each wire format the encoding may arrive in. Formats are tried in
+    # order until one inflates the body.
+    #
+    # A "deflate" body should carry a zlib header (RFC 9110 specifies the zlib
+    # format), but some servers send a bare deflate stream instead, so the raw
+    # format is kept as a fallback.
+    INFLATE_WINDOW_BITS = {
+      "gzip" => [Zlib::MAX_WBITS | 16].freeze,
+      "deflate" => [Zlib::MAX_WBITS, -Zlib::MAX_WBITS].freeze
+    }.freeze
+
+    # Content encoding that means the body was not encoded at all. It needs no
+    # work to decode, but it still has to be recognized so it does not stop the
+    # decode of the encodings applied before it.
+    IDENTITY_ENCODING = "identity"
+
+    class << self
+      # Split 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
+      # they were applied, so decoding runs from the last name backwards and
+      # 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
+      def split_encodings(headers_hash)
+        encodings = content_encodings(headers_hash)
+        boundary = encodings.rindex { |name| !decodable?(name) }
+        return [[], encodings] if boundary.nil?
+
+        [encodings[0..boundary], encodings[(boundary + 1)..]]
+      end
+
+      # Parse the content-encoding header into encoding names.
+      #
+      # @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
+          name unless name.empty?
+        end
+      end
+
+      # @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
+      # 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
+      def rewrite_content_encoding(headers_hash)
+        return headers_hash unless headers_hash.key?("content-encoding")
+
+        remaining, _decodable = split_encodings(headers_hash)
+
+        if remaining.empty?
+          headers_hash.except("content-encoding")
+        else
+          headers_hash.merge("content-encoding" => remaining.join(", "))
+        end
+      end
+    end
+
     # Initialize the reader.
     #
-    # @param processor [Processor] the processor object
-    def initialize(processor)
+    # 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
+    def initialize(processor, config: nil)
       @processor = processor
+      @config = config || processor.config
     end
 
-    # Read the response body with size validation.
+    # Read 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
     # and keep-alive internally. Using iteration instead of read() ensures non-blocking
-    # I/O that yields to the reactor.
+    # I/O that yields to the reactor. The chunks are the wire bytes: when the
+    # response is compressed, the size check here applies to the compressed
+    # bytes and {#decode_body} applies the same limit to the inflated bytes.
     #
     # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
     # @param headers_hash [Hash] the response headers
-    # @return [String, nil] the response body or nil if no body present
-    # @raise [ResponseTooLargeError] if body exceeds max_response_size
+    # @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_body(async_response, headers_hash)
+    def read_raw_body(async_response, headers_hash)
       return nil unless async_response.body
 
       validate_content_length(headers_hash)
-      body = read_body_chunks(async_response)
+      read_body_chunks(async_response)
+    end
+
+    # Decode 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
+    # the Content-Type header. This is CPU-bound work intended to run on a
+    # completion worker thread.
+    #
+    # An encoding the reader does not support leaves the body encoded, and a
+    # body that is still encoded keeps its binary encoding because the charset
+    # does not describe it. Use {.split_encodings} to find what stays applied
+    # 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)
+      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
+      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.
+      return body unless remaining.empty?
+
       apply_charset_encoding(body, headers_hash)
     end
 
     private
 
+    # Remove 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)
+      encodings.reverse_each do |name|
+        chunks = [inflate_encoding(chunks, name)] if INFLATE_WINDOW_BITS.key?(name)
+      end
+
+      chunks
+    end
+
+    # Inflate 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)
+      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)
+      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
+    # 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
+    # @return [void]
+    def warn_undecodable(remaining)
+      logger&.warn(
+        "[PatientHttp] Cannot decode response body with content-encoding " \
+        "'#{remaining.join(", ")}'; returning the encoded body"
+      )
+      nil
+    end
+
     def max_response_size
-      @processor.config.max_response_size
+      @config.max_response_size
     end
 
     def logger
-      @processor.config.logger
+      @config.logger
     end
 
     # Validate content-length header doesn't exceed max size.
@@ -66,7 +232,7 @@ module PatientHttp
     # Read body chunks while checking size.
     #
     # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
-    # @return [String] the response body in ASCII-8BIT encoding
+    # @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)
@@ -80,7 +246,7 @@ module PatientHttp
           # 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?
+          if @processor&.stopped?
             raise ReadAbortedError.new("Processor stopped while reading response body")
           end
 
@@ -97,8 +263,7 @@ module PatientHttp
 
         finished = true
 
-        # Join chunks and force to binary encoding to preserve raw bytes
-        chunks.join.force_encoding(Encoding::ASCII_8BIT)
+        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
@@ -106,6 +271,49 @@ module PatientHttp
       end
     end
 
+    # Inflate 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
+    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
+      # raise a buffer error.
+      return +"" if chunks.all?(&:empty?)
+
+      inflater = Zlib::Inflate.new(window_bits)
+      body = +""
+
+      begin
+        # The block form yields the inflated output in buffer-sized pieces, so
+        # the size is checked before the whole expansion is materialized. A
+        # single small compressed chunk can otherwise inflate to gigabytes
+        # before any check runs.
+        appender = ->(output) do
+          body << output
+          validate_inflated_size(body)
+        end
+
+        chunks.each { |chunk| inflater.inflate(chunk, &appender) }
+        inflater.finish(&appender) unless inflater.finished?
+      ensure
+        inflater.close
+      end
+
+      body
+    end
+
+    def validate_inflated_size(body)
+      if body.bytesize > max_response_size
+        raise ResponseTooLargeError.new(
+          "Response body size exceeded maximum allowed size (#{max_response_size} bytes)"
+        )
+      end
+    end
+
     # Extract charset from Content-Type header.
     #
     # @param headers_hash [Hash] the response headers