patient_http 1.1.2 → 1.2.0

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)

data/lib/patient_http.rb

@@ -52,6 +52,7 @@ module PatientHttp
   autoload :HttpError, File.join(__dir__, "patient_http/http_error")
   autoload :HttpHeaders, File.join(__dir__, "patient_http/http_headers")
   autoload :LifecycleManager, File.join(__dir__, "patient_http/lifecycle_manager")
+  autoload :OutgoingRequest, File.join(__dir__, "patient_http/outgoing_request")
   autoload :Payload, File.join(__dir__, "patient_http/payload")
   autoload :PayloadStore, File.join(__dir__, "patient_http/payload_store")
   autoload :Processor, File.join(__dir__, "patient_http/processor")
@@ -62,6 +63,7 @@ module PatientHttp
   autoload :Request, File.join(__dir__, "patient_http/request")
   autoload :RequestError, File.join(__dir__, "patient_http/request_error")
   autoload :RequestHelper, File.join(__dir__, "patient_http/request_helper")
+  autoload :RequestPreparer, File.join(__dir__, "patient_http/request_preparer")
   autoload :RequestTask, File.join(__dir__, "patient_http/request_task")
   autoload :RequestTemplate, File.join(__dir__, "patient_http/request_template")
   autoload :Response, File.join(__dir__, "patient_http/response")
@@ -238,6 +240,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 request(
       method,
@@ -249,9 +253,19 @@ module PatientHttp
       params: nil,
       timeout: nil,
       raise_error_responses: nil,
-      callback_args: nil
+      callback_args: nil,
+      preprocessors: nil
     )
-      request = Request.new(method, url, body: body, json: json, headers: headers, params: params, timeout: timeout)
+      request = Request.new(
+        method,
+        url,
+        body: body,
+        json: json,
+        headers: headers,
+        params: params,
+        timeout: timeout,
+        preprocessors: preprocessors
+      )
       execute(
         request: request,
         callback: callback,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_http
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Brian Durand
@@ -110,6 +110,7 @@ files:
 - lib/patient_http/http_error.rb
 - lib/patient_http/http_headers.rb
 - lib/patient_http/lifecycle_manager.rb
+- lib/patient_http/outgoing_request.rb
 - lib/patient_http/payload.rb
 - lib/patient_http/payload_store.rb
 - lib/patient_http/payload_store/active_record_store.rb
@@ -125,6 +126,7 @@ files:
 - lib/patient_http/request.rb
 - lib/patient_http/request_error.rb
 - lib/patient_http/request_helper.rb
+- lib/patient_http/request_preparer.rb
 - lib/patient_http/request_task.rb
 - lib/patient_http/request_template.rb
 - lib/patient_http/response.rb
@@ -156,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Generic async HTTP connection pool for Ruby applications using Fiber-based
   concurrency