patient_http 1.4.0 → 1.6.0

data/lib/patient_http/redirect_helper.rb

@@ -2,10 +2,64 @@
 
 module PatientHttp
   # Shared redirect-checking logic used by both the async Processor
-  # and the SynchronousExecutor.
+  # and the SynchronousExecutor. Including classes must expose the
+  # active {Configuration} as `@config`.
   #
   # @api private
   module RedirectHelper
+    class << self
+      # Determine the HTTP method to use when following a redirect.
+      #
+      # The rules follow RFC 9110 and the WHATWG Fetch standard:
+      #
+      # - 301 and 302 change POST to GET; every other method is preserved.
+      #   The QUERY specification states this POST exception does not apply
+      #   to QUERY, so a QUERY is re-sent as a QUERY.
+      # - 303 preserves GET and HEAD; every other method becomes GET.
+      # - 300, 307, and 308 preserve the method.
+      #
+      # @param http_method [Symbol] the current request method
+      # @param status [Integer] the redirect status code
+      # @return [Symbol] the method for the redirected request
+      def redirect_method(http_method, status)
+        case status
+        when 301, 302
+          (http_method == :post) ? :get : http_method
+        when 303
+          %i[get head].include?(http_method) ? http_method : :get
+        else
+          http_method
+        end
+      end
+
+      # Check if following a redirect requires changing the request method.
+      #
+      # @param http_method [Symbol] the current request method
+      # @param status [Integer] the redirect status code
+      # @return [Boolean] true if the method must change to follow the redirect
+      def method_change_required?(http_method, status)
+        redirect_method(http_method, status) != http_method
+      end
+
+      # Normalize header names used to strip headers from redirected requests.
+      # Names are downcased so they match header names case insensitively.
+      #
+      # @param names [String, Symbol, Array<String, Symbol>, nil] header names
+      # @return [Array<String>] frozen lowercase header names
+      # @raise [ArgumentError] if a name is not a string or symbol, or is empty
+      def normalize_header_names(names)
+        Array(names).map do |name|
+          unless name.is_a?(String) || name.is_a?(Symbol)
+            raise ArgumentError.new("header names must be strings, got: #{name.inspect}")
+          end
+
+          name = name.to_s.downcase
+          raise ArgumentError.new("header names cannot be empty") if name.empty?
+          name.freeze
+        end.freeze
+      end
+    end
+
     private
 
     # Check if a redirect response should be followed.
@@ -21,9 +75,38 @@ module PatientHttp
       location = response_data[:headers]["location"]
       return false if location.nil? || location.empty?
 
+      if RedirectHelper.method_change_required?(task.request.http_method, status)
+        return false unless follow_method_changing_redirect?(task)
+      end
+
       true
     end
 
+    # Check if the request may change its method to follow a redirect.
+    # The request setting takes precedence over the configuration.
+    #
+    # @param task [RequestTask] the request task
+    # @return [Boolean]
+    def follow_method_changing_redirect?(task)
+      value = task.request.follow_method_changing_redirects
+      value = @config.follow_method_changing_redirects if value.nil?
+      value
+    end
+
+    # Build the task for following a redirect, applying the configured
+    # header stripping rules.
+    #
+    # @param task [RequestTask] the request task
+    # @param response_data [Hash] the response data with status, headers, body
+    # @return [RequestTask] the redirect task
+    def build_redirect_task(task, response_data)
+      task.redirect_task(
+        location: response_data[:headers]["location"],
+        status: response_data[:status],
+        strip_headers: @config.redirect_strip_headers
+      )
+    end
+
     # Check for either too-many-redirects or recursive redirect.
     #
     # @param task [RequestTask] the request task

data/lib/patient_http/request.rb

@@ -17,9 +17,12 @@ module PatientHttp
     private_constant :UNDEFINED
 
     # Valid HTTP methods
-    VALID_METHODS = %i[get post put patch delete].freeze
+    VALID_METHODS = %i[get head post put patch delete query].freeze
 
-    # @return [Symbol] HTTP method (:get, :post, :put, :patch, :delete)
+    # HTTP methods that must not carry a request body
+    BODYLESS_METHODS = %i[get head delete].freeze
+
+    # @return [Symbol] HTTP method (:get, :head, :post, :put, :patch, :delete, :query)
     attr_reader :http_method
 
     # @return [String] The request URL
@@ -34,6 +37,14 @@ module PatientHttp
     # @return [Integer, nil] Maximum number of redirects to follow (nil uses config default, 0 disables)
     attr_reader :max_redirects
 
+    # @return [Boolean, nil] Whether a redirect that requires changing the HTTP method
+    #   (for example POST to GET on a 302) may be followed (nil uses config default)
+    attr_reader :follow_method_changing_redirects
+
+    # @return [Array<String>] Lowercase header names stripped from redirected requests,
+    #   in addition to those configured on the {Configuration}
+    attr_reader :redirect_strip_headers
+
     # @return [Hash{String, Symbol => SecretReference}] Query parameters whose values are
     #   secret references, kept out of the serialized URL and resolved at send time
     attr_reader :secret_params
@@ -42,6 +53,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 +72,10 @@ module PatientHttp
           params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
           max_redirects: hash["max_redirects"],
-          preprocessors: hash["preprocessors"]
+          follow_method_changing_redirects: hash["follow_method_changing_redirects"],
+          redirect_strip_headers: hash["redirect_strip_headers"],
+          preprocessors: hash["preprocessors"],
+          processor: hash["processor"]
         )
       end
 
@@ -81,7 +100,7 @@ module PatientHttp
 
     # Initializes a new Request.
     #
-    # @param http_method [Symbol, String] HTTP method (:get, :post, :put, :patch, :delete).
+    # @param http_method [Symbol, String] HTTP method (:get, :head, :post, :put, :patch, :delete, :query).
     # @param url [String, URI::Generic] The request URL.
     # @param headers [Hash, HttpHeaders] Request headers.
     # @param body [String, nil] Request body.
@@ -89,8 +108,16 @@ 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 follow_method_changing_redirects [Boolean, nil] Whether to follow a redirect that requires changing
+    #   the HTTP method (nil uses config). When false, such a redirect response is returned as the
+    #   result instead of being followed.
+    # @param redirect_strip_headers [String, Array<String>, nil] Header names (case insensitive)
+    #   to strip from redirected requests, in addition to those configured on the
+    #   {Configuration}.
     # @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 +127,10 @@ module PatientHttp
       params: nil,
       timeout: nil,
       max_redirects: nil,
-      preprocessors: nil
+      follow_method_changing_redirects: nil,
+      redirect_strip_headers: nil,
+      preprocessors: nil,
+      processor: nil
     )
       @http_method = http_method.is_a?(String) ? http_method.downcase.to_sym : http_method
 
@@ -116,7 +146,10 @@ module PatientHttp
       @body = (body == "") ? nil : body
       @timeout = timeout
       @max_redirects = max_redirects
+      @follow_method_changing_redirects = normalized_follow_method_changing_redirects(follow_method_changing_redirects)
+      @redirect_strip_headers = RedirectHelper.normalize_header_names(redirect_strip_headers)
       @preprocessors = normalized_preprocessors(preprocessors)
+      @processor = normalized_processor(processor)
 
       if json
         raise ArgumentError.new("Cannot provide both body and json") if @body
@@ -157,7 +190,14 @@ module PatientHttp
         hash["secret_params"] = @secret_params.transform_values(&:as_json)
       end
 
+      unless @follow_method_changing_redirects.nil?
+        hash["follow_method_changing_redirects"] = @follow_method_changing_redirects
+      end
+
+      hash["redirect_strip_headers"] = @redirect_strip_headers if @redirect_strip_headers.any?
+
       hash["preprocessors"] = @preprocessors if @preprocessors.any?
+      hash["processor"] = @processor if @processor
 
       hash
     end
@@ -171,6 +211,24 @@ module PatientHttp
       end
     end
 
+    # Normalize the method-changing redirect flag to true, false, or nil.
+    def normalized_follow_method_changing_redirects(value)
+      return nil if value.nil?
+      return value if value == true || value == false
+
+      raise ArgumentError.new("follow_method_changing_redirects must be true, false, or nil, got: #{value.inspect}")
+    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)
@@ -217,7 +275,7 @@ module PatientHttp
         raise ArgumentError.new("url must be a String or URI, got: #{@url.class}")
       end
 
-      if %i[get delete].include?(@http_method) && !@body.nil?
+      if BODYLESS_METHODS.include?(@http_method) && !@body.nil?
         raise ArgumentError.new("body is not allowed for #{@http_method.upcase} requests")
       end
 

data/lib/patient_http/request_helper.rb

@@ -16,8 +16,8 @@ module PatientHttp
   # 1. Register a global request handler with {PatientHttp.register_handler}.
   # 2. Include this module in a class.
   # 3. Optionally configure defaults with {.request_template}.
-  # 4. Call `async_get`, `async_post`, `async_put`, `async_patch`, `async_delete`, or
-  #    `async_request`.
+  # 4. Call `async_get`, `async_head`, `async_post`, `async_put`, `async_patch`,
+  #    `async_delete`, `async_query`, or `async_request`.
   #
   # @example Register a handler
   #   PatientHttp.register_handler do |request:, callback:, callback_args: nil, raise_error_responses: nil|
@@ -62,6 +62,16 @@ module PatientHttp
         async_request(:get, uri, callback: callback, **kwargs)
       end
 
+      # Enqueues an asynchronous HTTP HEAD request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_head(uri, callback:, **kwargs)
+        async_request(:head, uri, callback: callback, **kwargs)
+      end
+
       # Enqueues an asynchronous HTTP POST request.
       #
       # @param uri [String] absolute URL or path (when using a request template)
@@ -101,6 +111,16 @@ module PatientHttp
       def async_delete(uri, callback:, **kwargs)
         async_request(:delete, uri, callback: callback, **kwargs)
       end
+
+      # Enqueues an asynchronous HTTP QUERY request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_query(uri, callback:, **kwargs)
+        async_request(:query, uri, callback: callback, **kwargs)
+      end
     end
 
     module ClassMethods
@@ -116,14 +136,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
 
@@ -132,7 +154,7 @@ module PatientHttp
       # When a request template is configured, the request is built from the template. Otherwise,
       # it is built directly from the provided arguments.
       #
-      # @param method [Symbol] HTTP method (`:get`, `:post`, `:put`, `:patch`, `:delete`)
+      # @param method [Symbol] HTTP method (`:get`, `:head`, `:post`, `:put`, `:patch`, `:delete`, `:query`)
       # @param url [String] absolute URL or path (when using a request template)
       # @param callback [Class, String] callback class to handle the response
       # @param headers [Hash, nil] request headers
@@ -143,8 +165,14 @@ 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 follow_method_changing_redirects [Boolean, nil] whether to follow a redirect that changes the
+      #   HTTP method (nil uses the configuration default)
+      # @param redirect_strip_headers [String, Array<String>, nil] header names (case insensitive)
+      #   to strip from redirected requests, in addition to the configured names
       # @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 +185,23 @@ module PatientHttp
         timeout: nil,
         raise_error_responses: nil,
         callback_args: nil,
-        preprocessors: nil
+        follow_method_changing_redirects: nil,
+        redirect_strip_headers: 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,
+          follow_method_changing_redirects: follow_method_changing_redirects,
+          redirect_strip_headers: redirect_strip_headers,
+          preprocessors: preprocessors,
+          processor: processor
+        }
         request = if template
           template.request(method, url, **kwargs)
         else
@@ -193,7 +234,7 @@ module PatientHttp
     #
     # This delegates to {.ClassMethods#async_request} on the including class.
     #
-    # @param method [Symbol] HTTP method (`:get`, `:post`, `:put`, `:patch`, `:delete`)
+    # @param method [Symbol] HTTP method (`:get`, `:head`, `:post`, `:put`, `:patch`, `:delete`, `:query`)
     # @param url [String] absolute URL or path (when using a request template)
     # @param callback [Class, String] callback class to handle the response
     # @param headers [Hash, nil] request headers
@@ -204,8 +245,14 @@ 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 follow_method_changing_redirects [Boolean, nil] whether to follow a redirect that changes the
+    #   HTTP method (nil uses the configuration default)
+    # @param redirect_strip_headers [String, Array<String>, nil] header names (case insensitive)
+    #   to strip from redirected requests, in addition to the configured names
     # @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 +265,10 @@ module PatientHttp
       timeout: nil,
       raise_error_responses: nil,
       callback_args: nil,
-      preprocessors: nil
+      follow_method_changing_redirects: nil,
+      redirect_strip_headers: nil,
+      preprocessors: nil,
+      processor: nil
     )
       self.class.async_request(
         method,
@@ -231,7 +281,10 @@ module PatientHttp
         timeout: timeout,
         raise_error_responses: raise_error_responses,
         callback_args: callback_args,
-        preprocessors: preprocessors
+        follow_method_changing_redirects: follow_method_changing_redirects,
+        redirect_strip_headers: redirect_strip_headers,
+        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

@@ -10,6 +10,9 @@ module PatientHttp
     # Headers that are sensitive to origin and should be stripped on cross-origin redirects
     SENSITIVE_HEADERS = %w[authorization cookie].freeze
 
+    # Headers that describe a request body. They are removed when a redirect drops the body.
+    BODY_HEADERS = %w[content-type content-length content-encoding content-language content-location].freeze
+
     # @return [String] Unique UUID for tracking the task
     attr_reader :id
 
@@ -204,20 +207,24 @@ module PatientHttp
 
     # Create a new RequestTask for following a redirect.
     #
+    # The HTTP method follows RFC 9110: 301 and 302 change POST to GET, 303
+    # changes everything except GET and HEAD to GET, and 300, 307, and 308
+    # preserve the method. The body and the headers that describe it are
+    # dropped whenever the method changes.
+    #
+    # Headers named in the request's own redirect_strip_headers or in the given
+    # list are removed from the redirected request. Authorization and Cookie
+    # headers and preprocessors are removed on cross-origin redirects.
+    #
     # @param location [String] The redirect URL from the Location header
     # @param status [Integer] The HTTP status code of the redirect response
+    # @param strip_headers [Array<String>] Additional header names to strip,
+    #   typically from the {Configuration}
     # @return [RequestTask] A new task configured for the redirect
-    def redirect_task(location:, status:)
-      # Determine the HTTP method and body for the redirect
-      # 301, 302, 303: Convert to GET (no body) - standard browser behavior
-      # 307, 308: Preserve original method and body
-      if [301, 302, 303].include?(status)
-        redirect_method = :get
-        redirect_body = nil
-      else
-        redirect_method = request.http_method
-        redirect_body = request.body
-      end
+    def redirect_task(location:, status:, strip_headers: [])
+      redirect_method = RedirectHelper.redirect_method(request.http_method, status)
+      method_changed = (redirect_method != request.http_method)
+      redirect_body = method_changed ? nil : request.body
 
       # Resolve the redirect URL (handle relative URLs)
       redirect_url = resolve_redirect_url(location)
@@ -226,8 +233,12 @@ module PatientHttp
       # prevent credential leakage
       cross_origin = cross_origin?(request.url, redirect_url)
       redirect_headers = cross_origin ? request.headers.except(*SENSITIVE_HEADERS) : request.headers
+      redirect_headers = redirect_headers.except(*BODY_HEADERS) if method_changed
       redirect_preprocessors = cross_origin ? [] : request.preprocessors
 
+      strip_names = request.redirect_strip_headers + Array(strip_headers)
+      redirect_headers = redirect_headers.except(*strip_names) if strip_names.any?
+
       # Create a new request for the redirect
       redirect_request = Request.new(
         redirect_method,
@@ -236,7 +247,10 @@ module PatientHttp
         body: redirect_body,
         timeout: request.timeout,
         max_redirects: request.max_redirects,
-        preprocessors: redirect_preprocessors
+        follow_method_changing_redirects: request.follow_method_changing_redirects,
+        redirect_strip_headers: request.redirect_strip_headers,
+        preprocessors: redirect_preprocessors,
+        processor: request.processor
       )
 
       redirect_task_id = "#{id.split("/").first}/#{@redirects.size + 2}"

data/lib/patient_http/request_template.rb

@@ -34,26 +34,47 @@ 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.
     #
-    # @param method [Symbol] HTTP method (:get, :post, :put, :patch, :delete)
+    # @param method [Symbol] HTTP method (:get, :head, :post, :put, :patch, :delete, :query)
     # @param uri [String, URI::HTTP] URI path to request (joined with base_url if relative)
     # @param body [String, nil] request body
     # @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 timeout [Numeric, nil] request timeout in seconds (overrides the template default)
+    # @param follow_method_changing_redirects [Boolean, nil] whether to follow a redirect that changes the
+    #   HTTP method (nil uses the configuration default)
+    # @param redirect_strip_headers [String, Array<String>, nil] header names (case insensitive)
+    #   to strip from redirected requests, in addition to the configured names
     # @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,
+      follow_method_changing_redirects: nil,
+      redirect_strip_headers: 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 +89,10 @@ module PatientHttp
         json: json,
         params: merged_params,
         timeout: timeout || @timeout,
-        preprocessors: preprocessors || @preprocessors
+        follow_method_changing_redirects: follow_method_changing_redirects,
+        redirect_strip_headers: redirect_strip_headers,
+        preprocessors: preprocessors || @preprocessors,
+        processor: processor || @processor
       )
     end
 
@@ -81,6 +105,15 @@ module PatientHttp
       request(:get, uri, **kwargs)
     end
 
+    # Convenience method for HEAD requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def head(uri, **kwargs)
+      request(:head, uri, **kwargs)
+    end
+
     # Convenience method for POST requests.
     #
     # @param uri [String, URI::HTTP] URI path to request
@@ -116,5 +149,14 @@ module PatientHttp
     def delete(uri, **kwargs)
       request(:delete, uri, **kwargs)
     end
+
+    # Convenience method for QUERY requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def query(uri, **kwargs)
+      request(:query, uri, **kwargs)
+    end
   end
 end