patient_http 1.1.2 → 1.3.0

data/lib/patient_http/request.rb

@@ -38,6 +38,10 @@ module PatientHttp
     #   secret references, kept out of the serialized URL and resolved at send time
     attr_reader :secret_params
 
+    # @return [Array<String>] Names of preprocessors registered on the configuration
+    #   to apply to the request when it is sent
+    attr_reader :preprocessors
+
     class << self
       # Reconstruct a Request from a hash
       #
@@ -51,7 +55,8 @@ module PatientHttp
           body: Payload.load(hash["body"])&.value,
           params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
-          max_redirects: hash["max_redirects"]
+          max_redirects: hash["max_redirects"],
+          preprocessors: hash["preprocessors"]
         )
       end
 
@@ -84,6 +89,8 @@ module PatientHttp
     # @param params [Hash, nil] Query parameters to append to the URL.
     # @param timeout [Numeric, nil] Overall timeout in seconds.
     # @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.
     def initialize(
       http_method,
       url,
@@ -92,7 +99,8 @@ module PatientHttp
       json: nil,
       params: nil,
       timeout: nil,
-      max_redirects: nil
+      max_redirects: nil,
+      preprocessors: nil
     )
       @http_method = http_method.is_a?(String) ? http_method.downcase.to_sym : http_method
 
@@ -102,10 +110,13 @@ module PatientHttp
 
       @secret_params = {}
       @url = normalized_url(url, params)
-      @headers = headers.is_a?(HttpHeaders) ? headers : HttpHeaders.new(headers)
+      # Copy the headers so the request does not share mutable state with the
+      # caller (or with another request when following redirects).
+      @headers = headers.is_a?(HttpHeaders) ? headers.dup : HttpHeaders.new(headers)
       @body = (body == "") ? nil : body
       @timeout = timeout
       @max_redirects = max_redirects
+      @preprocessors = normalized_preprocessors(preprocessors)
 
       if json
         raise ArgumentError.new("Cannot provide both body and json") if @body
@@ -146,6 +157,8 @@ module PatientHttp
         hash["secret_params"] = @secret_params.transform_values(&:as_json)
       end
 
+      hash["preprocessors"] = @preprocessors if @preprocessors.any?
+
       hash
     end
 
@@ -158,6 +171,16 @@ module PatientHttp
       end
     end
 
+    # Normalize preprocessor names to a frozen array of strings.
+    def normalized_preprocessors(preprocessors)
+      names = Array(preprocessors).map(&:to_s)
+      if names.any?(&:empty?)
+        raise ArgumentError.new("preprocessor names cannot be empty")
+      end
+
+      names.freeze
+    end
+
     def normalized_url(url, params)
       uri = url.is_a?(URI::Generic) ? url.dup : URI(url.to_s)
       return uri.to_s unless params&.any?

data/lib/patient_http/request_error.rb

@@ -80,7 +80,7 @@ module PatientHttp
           :timeout
         in OpenSSL::SSL::SSLError
           :ssl
-        in Errno::ECONNREFUSED | Errno::ECONNRESET | Errno::ECONNABORTED | Errno::EHOSTUNREACH | Errno::EPIPE | SocketError | IOError
+        in Errno::ECONNREFUSED | Errno::ECONNRESET | Errno::ECONNABORTED | Errno::EHOSTUNREACH | Errno::ETIMEDOUT | Errno::EPIPE | SocketError | IOError
           :connection
         else
           if exception.is_a?(PatientHttp::ResponseTooLargeError)

data/lib/patient_http/request_helper.rb

@@ -114,13 +114,16 @@ module PatientHttp
       # @param headers [Hash] default headers for requests
       # @param params [Hash, nil] default query parameters for requests
       # @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
       # @return [void]
-      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30)
+      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30, preprocessors: nil)
         @patient_http_request_template = RequestTemplate.new(
           base_url: base_url,
           headers: headers,
           params: params,
-          timeout: timeout
+          timeout: timeout,
+          preprocessors: preprocessors
         )
       end
 
@@ -140,6 +143,8 @@ module PatientHttp
       # @param raise_error_responses [Boolean, nil] when true, non-success responses are
       #   reported as errors
       # @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
       # @return [Object] return value from the registered request handler
       def async_request(
         method,
@@ -151,10 +156,11 @@ module PatientHttp
         params: nil,
         timeout: nil,
         raise_error_responses: nil,
-        callback_args: nil
+        callback_args: nil,
+        preprocessors: nil
       )
         template = async_request_template
-        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout}
+        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout, preprocessors: preprocessors}
         request = if template
           template.request(method, url, **kwargs)
         else
@@ -198,6 +204,8 @@ module PatientHttp
     # @param raise_error_responses [Boolean, nil] when true, non-success responses are
     #   reported as errors
     # @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
     # @return [Object] return value from the registered request handler
     def async_request(
       method,
@@ -209,7 +217,8 @@ module PatientHttp
       params: nil,
       timeout: nil,
       raise_error_responses: nil,
-      callback_args: nil
+      callback_args: nil,
+      preprocessors: nil
     )
       self.class.async_request(
         method,
@@ -221,7 +230,8 @@ module PatientHttp
         params: params,
         timeout: timeout,
         raise_error_responses: raise_error_responses,
-        callback_args: callback_args
+        callback_args: callback_args,
+        preprocessors: preprocessors
       )
     end
 

data/lib/patient_http/request_preparer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Prepares a {Request} to be sent: resolves any secret references, sets the
+  # send-time headers (x-request-id and the default user-agent), and invokes any
+  # preprocessors attached to the request.
+  class RequestPreparer
+    # Raised when a request references a preprocessor name that is not registered.
+    class PreprocessorNotFoundError < StandardError; end
+
+    # @param config [Configuration] the configuration holding secrets and preprocessors
+    def initialize(config)
+      @config = config
+    end
+
+    # Prepare a request for sending.
+    #
+    # Secret references in the headers and query params are resolved first, then the
+    # x-request-id and default user-agent headers are set, and finally each
+    # preprocessor attached to the request is invoked in order with the outgoing
+    # request. Each preprocessor sees any changes made by the ones before it.
+    #
+    # @param request [Request] the request to prepare
+    # @param request_id [String] unique request identifier set as the x-request-id header
+    # @return [OutgoingRequest] the outgoing request with the final URL and headers
+    # @raise [PreprocessorNotFoundError] if the request references an unregistered preprocessor
+    def prepare(request, request_id)
+      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
+      url = @config.secret_manager.resolve_url(request.url, request.secret_params)
+
+      outgoing = OutgoingRequest.new(
+        http_method: request.http_method,
+        url: url,
+        headers: HttpHeaders.new(headers),
+        body: request.body
+      )
+
+      request.preprocessors.each do |name|
+        preprocessor = @config.preprocessor(name)
+        unless preprocessor
+          raise PreprocessorNotFoundError.new("No preprocessor registered for #{name.inspect}")
+        end
+
+        preprocessor.call(outgoing)
+      end
+
+      outgoing
+    end
+  end
+end

data/lib/patient_http/request_task.rb

@@ -92,6 +92,15 @@ module PatientHttp
       @started_at = monotonic_time
     end
 
+    # Return true if the task has started processing (i.e. {#started!} was
+    # called). Used to keep observer request_start/request_end notifications
+    # balanced when a task is re-enqueued during shutdown.
+    #
+    # @return [Boolean]
+    def started?
+      !@started_at.nil?
+    end
+
     # Returns the wall clock time when the task was enqueued.
     #
     # @return [Time, nil] The enqueued time or nil if not enqueued.
@@ -213,12 +222,11 @@ module PatientHttp
       # Resolve the redirect URL (handle relative URLs)
       redirect_url = resolve_redirect_url(location)
 
-      # Strip sensitive headers on cross-origin redirects to prevent credential leakage
-      redirect_headers = if cross_origin?(request.url, redirect_url)
-        request.headers.except(*SENSITIVE_HEADERS)
-      else
-        request.headers
-      end
+      # Strip sensitive headers and preprocessors on cross-origin redirects to
+      # prevent credential leakage
+      cross_origin = cross_origin?(request.url, redirect_url)
+      redirect_headers = cross_origin ? request.headers.except(*SENSITIVE_HEADERS) : request.headers
+      redirect_preprocessors = cross_origin ? [] : request.preprocessors
 
       # Create a new request for the redirect
       redirect_request = Request.new(
@@ -227,7 +235,8 @@ module PatientHttp
         headers: redirect_headers,
         body: redirect_body,
         timeout: request.timeout,
-        max_redirects: request.max_redirects
+        max_redirects: request.max_redirects,
+        preprocessors: redirect_preprocessors
       )
 
       redirect_task_id = "#{id.split("/").first}/#{@redirects.size + 2}"

data/lib/patient_http/request_template.rb

@@ -32,11 +32,14 @@ module PatientHttp
     # @param headers [Hash] Default headers for all requests
     # @param params [Hash, nil] Default query parameters to add to all requests
     # @param timeout [Float] Default request timeout in seconds
-    def initialize(base_url: nil, headers: {}, params: nil, timeout: 30)
+    # @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)
       @base_url = base_url
       @headers = HttpHeaders.new(headers)
       @params = params
       @timeout = timeout
+      @preprocessors = preprocessors
     end
 
     # Build an async HTTP request. Returns a Request object.
@@ -47,8 +50,10 @@ module PatientHttp
     # @param json [Object, nil] JSON object to serialize (cannot use with body)
     # @param headers [Hash] additional headers to merge with client headers
     # @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)
     # @return [Request] request object
-    def request(method, uri, body: nil, json: nil, headers: nil, params: nil, timeout: nil)
+    def request(method, uri, body: nil, json: nil, headers: nil, params: nil, timeout: nil, preprocessors: nil)
       full_uri = @base_url ? URI.join(@base_url, uri.to_s) : URI(uri)
 
       merged_headers = headers&.any? ? @headers.merge(headers) : @headers
@@ -62,7 +67,8 @@ module PatientHttp
         body: body,
         json: json,
         params: merged_params,
-        timeout: timeout || @timeout
+        timeout: timeout || @timeout,
+        preprocessors: preprocessors || @preprocessors
       )
     end
 

data/lib/patient_http/response.rb

@@ -12,6 +12,9 @@ module PatientHttp
     # @return [Integer] 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.
+    #
     # @return [HttpHeaders] response headers
     attr_reader :headers
 

data/lib/patient_http/response_reader.rb

@@ -6,6 +6,13 @@ module PatientHttp
   # Encapsulates the logic for reading async HTTP responses with size validation
   # and building Response objects from the raw response data.
   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,
+    # so this error is handled internally and never reaches callbacks.
+    #
+    # @api private
+    class ReadAbortedError < StandardError; end
+
     # Initialize the reader.
     #
     # @param processor [Processor] the processor object
@@ -24,6 +31,7 @@ module PatientHttp
     # @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
+    # @raise [ReadAbortedError] if the processor stopped past its shutdown deadline mid-read
     def read_body(async_response, headers_hash)
       return nil unless async_response.body
 
@@ -58,8 +66,9 @@ module PatientHttp
     # Read body chunks while checking size.
     #
     # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
-    # @return [String, nil] the response body in ASCII-8BIT encoding, or nil if interrupted
+    # @return [String] the response body in ASCII-8BIT encoding
     # @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
@@ -67,9 +76,12 @@ module PatientHttp
 
       begin
         async_response.body.each do |chunk|
-          # Check if processor is stopping/stopped (early exit during shutdown)
-          if @processor.stopping? || @processor.stopped?
-            return nil
+          # 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

data/lib/patient_http/synchronous_executor.rb

@@ -19,6 +19,7 @@ module PatientHttp
       @on_complete = on_complete
       @on_error = on_error
       @proxy_client = nil
+      @request_preparer = RequestPreparer.new(config)
     end
 
     # Execute the request synchronously.
@@ -30,21 +31,21 @@ module PatientHttp
         begin
           http_client = nil
           response_data = nil
+          redirect_error = nil
 
           loop do
             http_client&.close
             @proxy_client&.close
             @proxy_client = nil
-            http_client = create_http_client
+            outgoing = @request_preparer.prepare(@task.request, @task.id)
+            http_client = create_http_client(outgoing.url)
             timeout = @task.request.timeout || @config.request_timeout
 
             response_data = Async::Task.current.with_timeout(timeout) do
-              headers = @config.secret_manager.resolve_headers(@task.request.headers.to_h)
-              headers["x-request-id"] = @task.id
-              headers["user-agent"] ||= @config.user_agent if @config.user_agent
+              headers = outgoing.headers.to_h
               body = Protocol::HTTP::Body::Buffered.wrap([@task.request.body.to_s]) if @task.request.body
 
-              endpoint = Async::HTTP::Endpoint.parse(request_url)
+              endpoint = Async::HTTP::Endpoint.parse(outgoing.url)
               endpoint = configure_endpoint(endpoint) if @config.connection_timeout
 
               verb = @task.request.http_method.to_s.upcase
@@ -57,6 +58,8 @@ module PatientHttp
 
               request = Protocol::HTTP::Request[verb, endpoint.path, **options]
               async_response = http_client.call(request)
+              # Note: headers that appear multiple times (e.g. set-cookie) are
+              # flattened to a single joined string value.
               headers_hash = async_response.headers.to_h.transform_values(&:to_s)
 
               body_content = read_response_body(async_response, headers_hash)
@@ -71,36 +74,39 @@ module PatientHttp
             # Check for redirect
             break unless should_follow_redirect?(@task, response_data)
 
+            # Note: a `return` here would raise LocalJumpError since this block
+            # runs on a reactor fiber, so break out and handle the error below.
             redirect_error = check_redirect_error(@task, response_data)
-            if redirect_error
-              invoke_callback(redirect_error, :error)
-              return
-            end
+            break if redirect_error
 
             location = response_data[:headers]["location"]
             @task = @task.redirect_task(location: location, status: response_data[:status])
           end
 
-          end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          duration = end_time - start_time
-
-          response = Response.new(
-            status: response_data[:status],
-            headers: response_data[:headers],
-            body: response_data[:body],
-            duration: duration,
-            request_id: @task.id,
-            url: @task.request.url,
-            http_method: @task.request.http_method,
-            callback_args: @task.callback_args,
-            redirects: @task.redirects
-          )
-
-          if @task.raise_error_responses && !response.success?
-            http_error = HttpError.new(response)
-            invoke_callback(http_error, :error)
+          if redirect_error
+            invoke_callback(redirect_error, :error)
           else
-            invoke_callback(response, :response)
+            end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            duration = end_time - start_time
+
+            response = Response.new(
+              status: response_data[:status],
+              headers: response_data[:headers],
+              body: response_data[:body],
+              duration: duration,
+              request_id: @task.original_id,
+              url: @task.request.url,
+              http_method: @task.request.http_method,
+              callback_args: @task.callback_args,
+              redirects: @task.redirects
+            )
+
+            if @task.raise_error_responses && !response.success?
+              http_error = HttpError.new(response)
+              invoke_callback(http_error, :error)
+            else
+              invoke_callback(response, :response)
+            end
           end
         rescue => e
           end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -125,18 +131,12 @@ module PatientHttp
 
     private
 
-    # Resolve the current task's request URL, appending any secret query params.
-    #
-    # @return [String] the resolved request URL
-    def request_url
-      @config.secret_manager.resolve_url(@task.request.url, @task.request.secret_params)
-    end
-
     # Create HTTP client with config settings (retries, proxy, connection timeout).
     #
+    # @param url [String] the resolved request URL
     # @return [Protocol::HTTP::AcceptEncoding] wrapped HTTP client
-    def create_http_client
-      endpoint = Async::HTTP::Endpoint.parse(request_url)
+    def create_http_client(url)
+      endpoint = Async::HTTP::Endpoint.parse(url)
       endpoint = configure_endpoint(endpoint) if @config.connection_timeout
 
       client = if @config.proxy_url
@@ -191,15 +191,23 @@ module PatientHttp
 
       chunks = []
       total_size = 0
-
-      async_response.body.each do |chunk|
-        total_size += chunk.bytesize
-        if total_size > @config.max_response_size
-          raise ResponseTooLargeError.new(
-            "Response body size exceeded maximum allowed size (#{@config.max_response_size} bytes)"
-          )
+      finished = false
+
+      begin
+        async_response.body.each do |chunk|
+          total_size += chunk.bytesize
+          if total_size > @config.max_response_size
+            raise ResponseTooLargeError.new(
+              "Response body size exceeded maximum allowed size (#{@config.max_response_size} bytes)"
+            )
+          end
+          chunks << chunk
         end
-        chunks << chunk
+
+        finished = true
+      ensure
+        # Close the body if the read was interrupted so the connection is released
+        async_response.body.close unless finished
       end
 
       body = chunks.join.force_encoding(Encoding::ASCII_8BIT)