patient_http 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e193efd74abdf58c93ef6d65796c881bf08042264da0da0db34ee030ec52d08a
-  data.tar.gz: cb61f5268f51d6959b04e096420419f3454852096b5e027d67f79fa2f9789be8
+  metadata.gz: 54ede397ae79574e7dd597ea642b4d039877d5d642ba49c68b76219b8b1c4a32
+  data.tar.gz: 83bb067b78912753791e6002abb3470ca70936f5fe862fc65ee65d7786e1ac53
 SHA512:
-  metadata.gz: 56896f881827163fffaebfc8c745e47d5abdbf3c11da1727d6801164b1ed1e4ac276ac4a9e288d8d8d9cc544aab2e1a67d28c8cd5cff312429d243b49658107f
-  data.tar.gz: 4e2a4c555e44ed3c0ee6997d74ca0dfa444e7ad4567a9b58386e3bbd442ce8a82d94558e7606aa8bab2749a9930221e0c2609ffced97922a47cf7f1c4261023a
+  metadata.gz: 0302b8cdf7042fa545e49ab1ce565d5f7d1fd388a8413bc8a19249477d46d2fc9f732142d75afbb6cc52d0dd7a228e01c6f0c1cbaea2f7b151568472ccfaecb4
+  data.tar.gz: f418c2d7b5b48ba81ac73de35533143d7e99c75fb108a619f9cf9a55ca204f56f42ffec86ee4fc6d2796730703aad488014955603f87fc94ccf3e66d6b7b8593

data/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.6.0
+
+### Added
+
+- `Configuration#follow_method_changing_redirects` and `Request#follow_method_changing_redirects` (default true): when false, a redirect that would change the HTTP method (such as POST to GET on a 301, 302, or 303) is not followed and the redirect response is delivered to the callback instead. Redirects that preserve the method are still followed. The request setting overrides the configuration.
+- `Configuration#redirect_strip_headers` and `Request#redirect_strip_headers`: header names (matched case insensitively) that are always removed from redirected requests, so sensitive headers are never sent to a redirect target. Request-level names are applied in addition to the configured ones and survive serialization.
+- `PatientHttp.request`, `RequestHelper#async_request`, and `RequestTemplate#request` (and their `get`, `post`, and other method helpers) accept `follow_method_changing_redirects:` and `redirect_strip_headers:` and pass them to the `Request`.
+- `HEAD` and `QUERY` HTTP methods are supported by `Request`, `RequestTemplate`, `RequestHelper` (`async_head`, `async_query`), and `PatientHttp.head` / `PatientHttp.query`. `HEAD` requests cannot carry a body. The response size limit is not applied to the `Content-Length` of a `HEAD` response because no body is transferred.
+
+### Changed
+
+- The HTTP method used when following a redirect now follows RFC 9110. On 301 and 302 responses only `POST` is changed to `GET`; `HEAD`, `PUT`, `PATCH`, `DELETE`, and `QUERY` are re-sent unchanged with their body. On 303 responses `GET` and `HEAD` are preserved and every other method becomes `GET`. Previously every method was changed to `GET` on 301, 302, and 303.
+- When a redirect changes the method and drops the body, the `Content-Type`, `Content-Length`, `Content-Encoding`, `Content-Language`, and `Content-Location` headers are removed from the redirected request as well.
+- A 300 Multiple Choices response with a `Location` header is now followed, preserving the method and body. A 300 response without `Location` is delivered as a response, as before.
+- `RequestTask#redirect_task` accepts a `strip_headers:` option with the configured header names to remove.
+
 ## 1.5.0
 
 ### Added

data/README.md

@@ -163,7 +163,7 @@ get_request = template.get("/users/123")
 post_request = template.post("/users", json: {name: "John"})
 ```
 
-Templates support all HTTP methods (`get`, `post`, `put`, `patch`, `delete`) and handle URL joining, header merging, and query parameter encoding.
+Templates support all HTTP methods (`get`, `head`, `post`, `put`, `patch`, `delete`, `query`) and handle URL joining, header merging, and query parameter encoding.
 
 ## Standard Interface
 
@@ -188,7 +188,7 @@ PatientHttp.register_handler do |request:, callback:, callback_args: nil, raise_
 end
 
 # Now you can make requests directly through the PatientHttp interface with the .request,
-# .get, .post, .patch, .put, and .delete class methods:
+# .get, .head, .post, .patch, .put, .delete, and .query class methods:
 PatientHttp.get(
   "https://api.example.com/users/123",
   callback: FetchUserCallback,
@@ -229,7 +229,7 @@ Use `PatientHttp::RequestHelper` when you want a simple API for creating and dis
 1. Register a request handler with `PatientHttp.register_handler` that defines how requests are dispatched to your job queue or background processing system.
 2. Include `PatientHttp::RequestHelper` in your class.
 3. Optionally define a `request_template` for shared `base_url`, headers, and timeout.
-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`.
 
 ```ruby
 class ApiClient
@@ -618,6 +618,49 @@ If a request references a preprocessor name that is not registered, a `PatientHt
 
 When redirects are followed, preprocessors are re-run against each redirect URL so signatures stay valid. On cross-origin redirects they are dropped entirely, consistent with the stripping of `Authorization` and `Cookie` headers, so signed credentials are never sent to an unexpected origin.
 
+## Redirects
+
+Redirect responses (300, 301, 302, 303, 307, and 308) with a `Location` header are followed automatically, up to `max_redirects` hops. A 300 response is followed only when the server names a preferred choice in `Location`. Redirect loops raise `RecursiveRedirectError` and exceeding the limit raises `TooManyRedirectsError`. Any redirect that is not followed is delivered to the callback as a normal response.
+
+The HTTP method of the redirected request follows RFC 9110:
+
+| Status | Method |
+| --- | --- |
+| 301, 302 | `POST` becomes `GET` and the body is dropped. Other methods (including `HEAD`, `PUT`, `DELETE`, and `QUERY`) are preserved with their body. |
+| 303 | `GET` and `HEAD` are preserved. Every other method becomes `GET` and the body is dropped. |
+| 300, 307, 308 | The method and body are preserved. |
+
+The QUERY specification states that the POST-to-GET exception on 301 and 302 does not apply to `QUERY`, so a redirected `QUERY` is re-sent as a `QUERY` with its body, and a 303 turns it into a `GET`.
+
+### Preventing method changes
+
+Set `follow_method_changing_redirects: false` to stop following redirects that would change the HTTP method. A `POST` that receives a 302 then completes with the 302 response instead of being retried as a `GET`. Redirects that preserve the method (a `PUT` on a 301, or any method on a 307) are still followed. The option can be set on the `Configuration` or on a single `Request`; the request value wins when both are set.
+
+```ruby
+config = PatientHttp::Configuration.new(follow_method_changing_redirects: false)
+
+# Or per request
+request = PatientHttp::Request.new(:post, "https://api.example.com/submit", body: payload, follow_method_changing_redirects: false)
+```
+
+### Stripping headers on redirects
+
+`Authorization` and `Cookie` headers are always removed on cross-origin redirects. To make sure other sensitive headers are never sent to a redirect target, list them in `redirect_strip_headers`. Header names are matched case insensitively. Listed headers are removed from every redirected request, same-origin or not.
+
+```ruby
+config = PatientHttp::Configuration.new(redirect_strip_headers: ["X-Api-Key", "X-Internal-Token"])
+
+# Or per request; these are stripped in addition to the configured headers
+request = PatientHttp::Request.new(:get, "https://api.example.com/data", headers: headers, redirect_strip_headers: "X-Signature")
+
+# The same options are accepted by PatientHttp.request, the async_* helpers, and RequestTemplate
+PatientHttp.get("https://api.example.com/data", callback: FetchCallback, redirect_strip_headers: "X-Signature")
+```
+
+Per-request header names survive serialization into the job queue, so they apply no matter which process follows the redirect.
+
+Stripping applies to the headers set on the request. Preprocessors run again on each same-origin redirect and can add headers after the strip, so a header that a preprocessor sets is sent to the redirect target. When a redirect changes the method and drops the body, the headers that describe the body (`Content-Type`, `Content-Length`, `Content-Encoding`, `Content-Language`, and `Content-Location`) are removed as well.
+
 ## Troubleshooting
 
 ### Warning: `ThreadError: Attempt to unlock a mutex which is not locked`
@@ -660,6 +703,15 @@ config = PatientHttp::Configuration.new(
   # Maximum redirects to follow (default: 5, 0 disables)
   max_redirects: 5,
 
+  # Follow redirects that must change the HTTP method, such as POST to GET on
+  # a 302 (default: true). When false, those requests receive the redirect response.
+  follow_method_changing_redirects: true,
+
+  # Header names (case insensitive) always stripped from redirected requests
+  # (default: []). Authorization and Cookie are always stripped on cross-origin
+  # redirects.
+  redirect_strip_headers: ["X-Api-Key", "X-Internal-Token"],
+
   # Maximum number of hosts to maintain persistent connections for (default: 100)
   connection_pool_size: 100,
 

data/VERSION

@@ -1 +1 @@
-1.5.0
+1.6.0

data/lib/patient_http/configuration.rb

@@ -43,6 +43,15 @@ module PatientHttp
     # @return [Integer] Maximum number of redirects to follow (0 disables redirects)
     attr_reader :max_redirects
 
+    # @return [Boolean] Whether a redirect that requires changing the HTTP method
+    #   (for example POST to GET on a 302) may be followed. When false, such a
+    #   redirect response is returned as the result instead of being followed.
+    attr_reader :follow_method_changing_redirects
+
+    # @return [Array<String>] Lowercase header names that are always stripped from
+    #   redirected requests
+    attr_reader :redirect_strip_headers
+
     # @return [Integer] This is the maximum number of hosts for which connections
     #   will be kept alive for at one time.
     attr_reader :connection_pool_size
@@ -73,6 +82,12 @@ module PatientHttp
     # @param user_agent [String, nil] Default User-Agent header value
     # @param raise_error_responses [Boolean] Whether to raise HttpError for non-2xx responses by default
     # @param max_redirects [Integer] Maximum number of redirects to follow (0 disables redirects)
+    # @param follow_method_changing_redirects [Boolean] Whether to follow a redirect that requires changing the
+    #   HTTP method, such as POST to GET on a 301, 302, or 303 response. When false, requests
+    #   whose method would change do not follow the redirect and receive the redirect response.
+    # @param redirect_strip_headers [String, Array<String>] Header names (case insensitive)
+    #   that are always stripped from redirected requests, so sensitive headers are never
+    #   sent to a redirect target
     # @param connection_pool_size [Integer] Maximum number of host clients to pool
     # @param connection_timeout [Numeric, nil] Connection timeout in seconds
     # @param proxy_url [String, nil] HTTP/HTTPS proxy URL (supports authentication)
@@ -93,6 +108,8 @@ module PatientHttp
       user_agent: "PatientHttp",
       raise_error_responses: false,
       max_redirects: 5,
+      follow_method_changing_redirects: true,
+      redirect_strip_headers: [],
       connection_pool_size: 100,
       connection_timeout: nil,
       proxy_url: nil,
@@ -126,6 +143,8 @@ module PatientHttp
       self.user_agent = user_agent
       self.raise_error_responses = raise_error_responses
       self.max_redirects = max_redirects
+      self.follow_method_changing_redirects = follow_method_changing_redirects
+      self.redirect_strip_headers = redirect_strip_headers
       self.connection_pool_size = connection_pool_size
       self.connection_timeout = connection_timeout
       self.proxy_url = proxy_url
@@ -186,6 +205,18 @@ module PatientHttp
       @max_redirects = value
     end
 
+    def follow_method_changing_redirects=(value)
+      unless value == true || value == false
+        raise ArgumentError.new("follow_method_changing_redirects must be true or false, got: #{value.inspect}")
+      end
+
+      @follow_method_changing_redirects = value
+    end
+
+    def redirect_strip_headers=(value)
+      @redirect_strip_headers = RedirectHelper.normalize_header_names(value)
+    end
+
     def connection_pool_size=(value)
       validate_positive_integer(:connection_pool_size, value)
       @connection_pool_size = value
@@ -425,6 +456,8 @@ module PatientHttp
         "user_agent" => user_agent,
         "raise_error_responses" => raise_error_responses,
         "max_redirects" => max_redirects,
+        "follow_method_changing_redirects" => follow_method_changing_redirects,
+        "redirect_strip_headers" => redirect_strip_headers,
         "connection_pool_size" => connection_pool_size,
         "connection_timeout" => connection_timeout,
         "proxy_url" => proxy_url,

data/lib/patient_http/outgoing_request.rb

@@ -12,7 +12,7 @@ module PatientHttp
   #
   # @see Configuration#register_preprocessor
   class OutgoingRequest
-    # @return [Symbol] HTTP method (:get, :post, :put, :patch, :delete)
+    # @return [Symbol] HTTP method (:get, :head, :post, :put, :patch, :delete, :query)
     attr_reader :http_method
 
     # @return [String] the request URL with any secret query params already resolved

data/lib/patient_http/processor.rb

@@ -809,7 +809,7 @@ module PatientHttp
       # Create the redirect task, then atomically claim the original (remove it
       # from in-flight) and enqueue the redirect. If the claim fails the
       # shutdown sequence already re-enqueued the original, so drop the redirect.
-      redirect_task = task.redirect_task(location: location, status: status)
+      redirect_task = build_redirect_task(task, response_data)
 
       begin
         claimed = announce_and_enqueue(redirect_task) do

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
@@ -61,6 +72,8 @@ module PatientHttp
           params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
           max_redirects: hash["max_redirects"],
+          follow_method_changing_redirects: hash["follow_method_changing_redirects"],
+          redirect_strip_headers: hash["redirect_strip_headers"],
           preprocessors: hash["preprocessors"],
           processor: hash["processor"]
         )
@@ -87,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.
@@ -95,6 +108,12 @@ 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
@@ -108,6 +127,8 @@ module PatientHttp
       params: nil,
       timeout: nil,
       max_redirects: nil,
+      follow_method_changing_redirects: nil,
+      redirect_strip_headers: nil,
       preprocessors: nil,
       processor: nil
     )
@@ -125,6 +146,8 @@ 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)
 
@@ -167,6 +190,12 @@ 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
 
@@ -182,6 +211,14 @@ 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?
@@ -238,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
@@ -134,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
@@ -145,6 +165,10 @@ 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
@@ -161,11 +185,23 @@ module PatientHttp
         timeout: nil,
         raise_error_responses: nil,
         callback_args: 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, processor: processor}
+        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
@@ -198,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
@@ -209,6 +245,10 @@ 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
@@ -225,6 +265,8 @@ module PatientHttp
       timeout: nil,
       raise_error_responses: nil,
       callback_args: nil,
+      follow_method_changing_redirects: nil,
+      redirect_strip_headers: nil,
       preprocessors: nil,
       processor: nil
     )
@@ -239,6 +281,8 @@ module PatientHttp
         timeout: timeout,
         raise_error_responses: raise_error_responses,
         callback_args: callback_args,
+        follow_method_changing_redirects: follow_method_changing_redirects,
+        redirect_strip_headers: redirect_strip_headers,
         preprocessors: preprocessors,
         processor: processor
       )

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,6 +247,8 @@ module PatientHttp
         body: redirect_body,
         timeout: request.timeout,
         max_redirects: request.max_redirects,
+        follow_method_changing_redirects: request.follow_method_changing_redirects,
+        redirect_strip_headers: request.redirect_strip_headers,
         preprocessors: redirect_preprocessors,
         processor: request.processor
       )

data/lib/patient_http/request_template.rb

@@ -46,18 +46,35 @@ module PatientHttp
 
     # 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, processor: 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
@@ -72,6 +89,8 @@ module PatientHttp
         json: json,
         params: merged_params,
         timeout: timeout || @timeout,
+        follow_method_changing_redirects: follow_method_changing_redirects,
+        redirect_strip_headers: redirect_strip_headers,
         preprocessors: preprocessors || @preprocessors,
         processor: processor || @processor
       )
@@ -86,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
@@ -121,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

data/lib/patient_http/response_reader.rb

@@ -113,15 +113,21 @@ module PatientHttp
     # response is compressed, the size check here applies to the compressed
     # bytes and {#decode_body} applies the same limit to the inflated bytes.
     #
+    # The Content-Length header is checked against the size limit before the
+    # read starts. A response to a HEAD request has an empty body but reports
+    # the Content-Length of the resource, so the header check is skipped when
+    # the body reports itself as empty.
+    #
     # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
     # @param headers_hash [Hash] the response headers
     # @return [Array<String>, nil] the raw body chunks or nil if no body present
     # @raise [ResponseTooLargeError] if the body exceeds max_response_size
     # @raise [ReadAbortedError] if the processor stopped past its shutdown deadline mid-read
     def read_raw_body(async_response, headers_hash)
-      return nil unless async_response.body
+      body = async_response.body
+      return nil unless body
 
-      validate_content_length(headers_hash)
+      validate_content_length(headers_hash) unless body.empty?
       read_body_chunks(async_response)
     end
 

data/lib/patient_http/synchronous_executor.rb

@@ -63,7 +63,7 @@ module PatientHttp
               # flattened to a single joined string value.
               headers_hash = async_response.headers.to_h.transform_values(&:to_s)
 
-              chunks = read_response_body(async_response, headers_hash)
+              chunks = @response_reader.read_raw_body(async_response, headers_hash)
               body_content = @response_reader.decode_body(chunks, headers_hash)
 
               {
@@ -81,8 +81,7 @@ module PatientHttp
             redirect_error = check_redirect_error(@task, response_data)
             break if redirect_error
 
-            location = response_data[:headers]["location"]
-            @task = @task.redirect_task(location: location, status: response_data[:status])
+            @task = build_redirect_task(@task, response_data)
           end
 
           if redirect_error
@@ -179,47 +178,6 @@ module PatientHttp
       )
     end
 
-    # Read the raw response body chunks with size validation. The chunks are
-    # the wire bytes; ResponseReader#decode_body inflates and applies the
-    # charset, enforcing the same limit on the inflated bytes.
-    #
-    # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
-    # @param headers_hash [Hash] the response headers
-    # @return [Array<String>, nil] the raw body chunks or nil if no body present
-    def read_response_body(async_response, headers_hash)
-      return nil unless async_response.body
-
-      content_length = headers_hash["content-length"]&.to_i
-      if content_length && content_length > @config.max_response_size
-        raise ResponseTooLargeError.new(
-          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{@config.max_response_size} bytes)"
-        )
-      end
-
-      chunks = []
-      total_size = 0
-      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
-
-        finished = true
-      ensure
-        # Close the body if the read was interrupted so the connection is released
-        async_response.body.close unless finished
-      end
-
-      chunks
-    end
-
     # Invoke callback synchronously.
     #
     # @param result [Response, Error] the result to pass to callback

data/lib/patient_http.rb

@@ -36,8 +36,9 @@ module PatientHttp
   # lands in the job system's retry mechanism instead of being dropped.
   class UnknownProcessorError < StandardError; end
 
-  # HTTP redirect status codes that should be followed
-  FOLLOWABLE_REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
+  # HTTP redirect status codes that are followed when a Location header is present.
+  # A 300 response is followed only when the server names a preferred choice in Location.
+  FOLLOWABLE_REDIRECT_STATUSES = [300, 301, 302, 303, 307, 308].freeze
 
   VERSION = File.read(File.join(__dir__, "../VERSION")).strip
 
@@ -275,6 +276,16 @@ module PatientHttp
       request(:get, uri, callback: callback, **kwargs)
     end
 
+    # Enqueues an HTTP HEAD request.
+    #
+    # @param uri [String] absolute URL
+    # @param callback [Class, String] callback class to handle the response
+    # @param kwargs [Hash] forwarded to `request`
+    # @return [Object] return value from the registered request handler
+    def head(uri, callback:, **kwargs)
+      request(:head, uri, callback: callback, **kwargs)
+    end
+
     # Enqueues an HTTP POST request.
     #
     # @param uri [String] absolute URL
@@ -315,9 +326,19 @@ module PatientHttp
       request(:delete, uri, callback: callback, **kwargs)
     end
 
+    # Enqueues an HTTP QUERY request.
+    #
+    # @param uri [String] absolute URL
+    # @param callback [Class, String] callback class to handle the response
+    # @param kwargs [Hash] forwarded to `request`
+    # @return [Object] return value from the registered request handler
+    def query(uri, callback:, **kwargs)
+      request(:query, uri, callback: callback, **kwargs)
+    end
+
     # Builds and dispatches an HTTP request.
     #
-    # @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
     # @param callback [Class, String] callback class to handle the response
     # @param headers [Hash, nil] request headers
@@ -328,6 +349,12 @@ 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 max_redirects [Integer, nil] maximum redirects to follow (nil uses the configuration
+    #   default, 0 disables redirects)
+    # @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
@@ -344,6 +371,9 @@ module PatientHttp
       timeout: nil,
       raise_error_responses: nil,
       callback_args: nil,
+      max_redirects: nil,
+      follow_method_changing_redirects: nil,
+      redirect_strip_headers: nil,
       preprocessors: nil,
       processor: nil
     )
@@ -355,6 +385,9 @@ module PatientHttp
         headers: headers,
         params: params,
         timeout: timeout,
+        max_redirects: max_redirects,
+        follow_method_changing_redirects: follow_method_changing_redirects,
+        redirect_strip_headers: redirect_strip_headers,
         preprocessors: preprocessors,
         processor: processor
       )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_http
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Brian Durand
@@ -146,7 +146,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