patient_http 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c173592c54e9ac9730cbfeca9b81d61a5af9df06839b8abdc2bb2dcb54b228f
-  data.tar.gz: 171d9176271d166855129c6c13bb0e234345f3368dbae835a4221e8b28a9deb8
+  metadata.gz: c4e10ada7964f607e81e169e4f88086d3dd32967fd6bf6ed48025615a133d5fd
+  data.tar.gz: 704ca986fb7622f6e977d8d02d76e198c98abdd1c5ea808d85c8af25bdd3f72f
 SHA512:
-  metadata.gz: '0811e744dadbceb89141f2603de7113fec36ab389967fd941fa9202bba3d6c4924e169b594d17b6f03dba0437bb04b5ca5f895515174d2717a316027428a4f85'
-  data.tar.gz: 3719152b73fd5994766a26dba869f4f278c2b8362fb79a30b543d123abfcfd996db0a5a2e57daf136f2812674c0644e1ad1671c50c2553a615724d7239312048
+  metadata.gz: 442991bea3a29c334866d9136bca7f9ada37d68326b537b31571bae9331f93387e3a617ff970e1433f289fbb078346b33a9394a22afc9eea01e7347233476fe9
+  data.tar.gz: baee6575b4bdf5f7798548cc17419d33234f255088bd612d41daec3bceafd56a7a96acb7f86f991d2b6f1a9e31f316100dee6b243e14b8b56831935614b46055

data/ARCHITECTURE.md

@@ -206,6 +206,8 @@ erDiagram
         hash headers
         string body
         float timeout
+        float read_timeout
+        int max_response_size
     }
 
     REQUEST-TASK {
@@ -283,6 +285,12 @@ The processor uses Ruby's Fiber scheduler (`async` gem) for non-blocking I/O:
 4. **Completion worker threads** decode response bodies (join, inflate, charset), build responses, and execute TaskHandler callbacks and `request_end` observers off the reactor. Decoding is CPU-bound and has no fiber yield point, so running it inline on the reactor would stop every other in-flight request until it finished. On a worker thread the Ruby scheduler can preempt it, and Zlib releases the GVL for part of the inflate
 5. **Delivery is concurrent, not serialized.** Callbacks and completion-time observers run on any of the `completion_threads` workers, so they must be thread-safe. Completions are also bounded: a task stays in the capacity count until a worker claims its result, so the completion backlog can never exceed `max_connections`
 
+## Timeouts and Response Size
+
+A request can have two timeouts. The request timeout limits the full exchange. The read timeout limits each wait for data: the wait for the response headers, and then the wait for each body chunk. The first timer starts before the connection opens, so it also covers opening the connection, sending the request, and the immediate retries of a refused connection. Each wait has its own timer, so a slow but steady stream continues until the request timeout stops it. The read timeout raises `ReadTimeoutError`, a subclass of `Async::TimeoutError`. The immediate retries never retry either timeout.
+
+The response size limit comes from the request, or from the configuration if the request doesn't set one. The reactor applies the limit to the declared body length before the read starts and to the raw bytes as they arrive. The raw response data that goes to the completion worker includes the limit, so the worker applies the same limit to the inflated body.
+
 ## State Management
 
 The processor maintains state through its lifecycle:
@@ -307,7 +315,8 @@ When the processor is stopped with in-flight requests:
 All behavior is controlled through a central `Configuration` object:
 
 - Maximum concurrent connections
-- Request timeouts
+- Request timeouts and read timeouts
+- Response size limits
 - Connection pool settings
 - Retry policies
 - Proxy configuration

data/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.8.0
+
+### Added
+
+- `read_timeout` request option and `Configuration#read_timeout` default (default `nil`, no limit): the maximum number of seconds to wait for data from the server. The first timer starts before the connection opens and covers opening the connection, sending the request, and waiting for the response headers. The timer starts again for each body chunk, so a streamed response that keeps sending data can run longer than the read timeout while a stalled stream fails fast. The request timeout still limits the full exchange. When the read timeout fires, the error is a `PatientHttp::ReadTimeoutError`, a subclass of `Async::TimeoutError`, so `RequestError#error_type` is `:timeout`. It is never retried. Don't use it for requests where the server does all of its work before it sends the headers.
+- `max_response_size` request option: a per-request override of `Configuration#max_response_size`. It applies to the declared body length, to the bytes read, and to the inflated body.
+- `RequestTemplate` and `RequestHelper.request_template` accept `read_timeout` and `max_response_size` defaults. The `RequestHelper` `async_*` methods and the `PatientHttp` request methods accept both options.
+- Both options are serialized with the request only when they are set. Requests serialized by earlier versions load with both options unset.
+
+### Fixed
+
+- The response size check before the body is read now works on HTTP/1 connections. The HTTP/1 parser removes `Content-Length` from the response headers, so the check only ran when the header was present, as it is in test stubs. The declared length of the body is now used when the header is missing.
+- The response body is closed when the size check before the read fails. Before, `SynchronousExecutor` left the connection checked out and waited forever when it closed its client pool.
+
 ## 1.7.0
 
 ### Added

data/README.md

@@ -109,6 +109,8 @@ The methods take these options:
 | `json:` | An object to send as a JSON body. Can't be combined with `body:`. |
 | `params:` | Query parameters to add to the URL. |
 | `timeout:` | The request timeout in seconds. |
+| `read_timeout:` | The maximum number of seconds to wait for data from the server. See [Streamed and long-running responses](#streamed-and-long-running-responses). |
+| `max_response_size:` | The maximum response body size in bytes for this request. Overrides the configured `max_response_size`. |
 | `raise_error_responses:` | Whether to treat non-2xx responses as errors. See [Handle HTTP error responses](#handle-http-error-responses). |
 | `max_redirects:` | The maximum number of redirects to follow for this request. `0` turns off redirects. |
 | `follow_method_changing_redirects:` | Whether to follow redirects that change the HTTP method. See [Redirects](#redirects). |
@@ -217,7 +219,7 @@ request = template.get("/users/123")
 PatientHttp.execute(request: request, callback: FetchUserCallback)
 ```
 
-A template has a method for each HTTP method. The template joins each path with the base URL, and merges the headers and query parameters of each request with its own. If the template doesn't set a `timeout`, the configured `request_timeout` applies.
+A template has a method for each HTTP method. The template joins each path with the base URL, and merges the headers and query parameters of each request with its own. If the template doesn't set a `timeout`, the configured `request_timeout` applies. A template can also set defaults for `read_timeout` and `max_response_size`. A value given to a request overrides the template value.
 
 ### Use the RequestHelper module
 
@@ -245,6 +247,29 @@ end
 
 The `async_*` methods take the same options as the `PatientHttp` module methods. Paths are relative to the template's `base_url`. A subclass uses the template of its superclass unless it declares its own.
 
+### Streamed and long-running responses
+
+The `timeout` option limits the full request, from the time it is sent until the last byte of the body arrives. A streamed response, such as server-sent events from an LLM API, can continue for many minutes. A large `timeout` lets the stream finish, but it cannot find a stream that stops.
+
+To find a stream that stops, set `read_timeout`. This is the maximum number of seconds to wait for data from the server. The first timer starts before the connection opens. It covers the time to get a connection, send the request, and wait for the response headers. The timer starts again each time a body chunk arrives. A stream that sends data at regular intervals can continue for longer than `read_timeout`, until `timeout` stops it.
+
+```ruby
+PatientHttp.post(
+  "https://api.example.com/v1/generate",
+  json: {prompt: "...", stream: true},
+  callback: GenerateCallback,
+  timeout: 30 * 60,              # Limit for the full stream.
+  read_timeout: 60,              # Limit for each wait for data.
+  max_response_size: 8 * 1024 * 1024
+)
+```
+
+When the read timeout stops a request, the `on_error` callback receives a `RequestError` with an `error_type` of `:timeout` and an `error_class` of `PatientHttp::ReadTimeoutError`. When `timeout` stops a request, the `error_class` is `Async::TimeoutError`. A request stopped by either timeout isn't retried, because the server may have processed it.
+
+Do not set `read_timeout` for a request where the server does all of its work before it sends the response headers. For that request, the wait for the headers can be longer than the read timeout, and the request fails.
+
+The callback receives the full body when the stream ends. A streamed body is usually larger than the equivalent JSON body, so set `max_response_size` on the request to increase the limit for these requests only.
+
 ## Configuration
 
 All configuration is optional. To set options, call `PatientHttp.configure` in an initializer. If an integration gem is loaded, the method yields that gem's configuration, which adds the options for the job system to the options below.
@@ -262,11 +287,17 @@ PatientHttp.configure do |config|
   # Default timeout for HTTP requests in seconds (default: 60).
   config.request_timeout = 60
 
+  # Default maximum number of seconds to wait for data from the server
+  # (default: nil, no limit). The timer covers the wait for the response
+  # headers and starts again each time a body chunk arrives. See "Streamed and
+  # long-running responses".
+  config.read_timeout = nil
+
   # Timeout for graceful shutdown in seconds (default: 30).
   config.shutdown_timeout = 30
 
   # Maximum response body size in bytes (default: 1MB). Larger responses raise
-  # ResponseTooLargeError.
+  # ResponseTooLargeError. A request can set its own max_response_size.
   config.max_response_size = 1024 * 1024
 
   # Default User-Agent header for all requests (default: "PatientHttp").
@@ -369,11 +400,12 @@ For how the processor name is kept through retries and crash recovery, see the d
 - `max_connections`: Set this based on your system's resources. Each connection uses memory and a file descriptor. A tuned system with enough resources can handle thousands of concurrent connections.
 - `max_connections_per_host`: Limits the sockets open to each host. The default is no limit. For high concurrency, set a value such as 32, so that one host can't use every file descriptor. Make sure that the process file descriptor limit covers `max_connections`, plus idle pooled connections, plus the application's own connections.
 - `request_timeout`: Set this based on the response times of the APIs that you call. AI APIs can take minutes to respond while they generate content.
+- `read_timeout`: Limits each wait for data from the server, including the wait for the response headers. Set it on requests that stream their response, so that a stream that stops fails before `request_timeout`. Do not set it as a default if the APIs that you call do their work before they send the response headers.
 - `connection_timeout`: Limits only the TCP connect and the TLS handshake. Set it to fail fast when a host doesn't answer. It doesn't limit the wait for a response, because `request_timeout` controls the full exchange.
 - `tcp_keepalive`: The kernel sends probes on an idle pooled connection. The probes keep NAT and firewall mappings open, and let the kernel find a dead peer before the pool sends a request on the connection. Set this option when connections stay idle in the pool between requests.
 - `tcp_user_timeout`: The kernel closes a connection when the peer doesn't acknowledge sent data. This option is available only on Linux. A request to a peer that stopped without notice fails after this timeout, without waiting for `request_timeout`. Acknowledged data isn't affected, so a slow response continues.
 - `connection_pool_size`: Sets the maximum number of hosts whose connections are kept open. Increase it if your application calls many different hosts.
-- `max_response_size`: Limits the size of HTTP responses to prevent high memory use from unexpectedly large responses. For a compressed response, the limit applies to the decompressed body. For large responses, consider a [payload store](#payload-stores).
+- `max_response_size`: Limits the size of HTTP responses to prevent high memory use from unexpectedly large responses. For a compressed response, the limit applies to the decompressed body. To increase the limit for some requests only, set `max_response_size` on those requests. For large responses, consider a [payload store](#payload-stores).
 - `completion_threads`: Increase this when result delivery does heavy work, such as serialization or encryption, and finished requests wait for a thread. If the value is greater than 1, results are delivered concurrently, so `TaskHandler` callbacks and completion-time observers must be thread-safe. Set it to 1 to deliver results one at a time.
 - `completion_retries`: The number of times to retry result delivery before the failure is reported to observers through `completion_failed`. A retry calls `on_complete` or `on_error` again. As a result, a handler that raises an error *after* it enqueues its message delivers that message twice. Make handlers idempotent, or set `completion_retries` to 0 to report the first failure without a retry.
 - `shutdown_timeout`: Must be less than the process supervisor's stop timeout, so that in-flight requests and their results finish before a hard kill.

data/VERSION

@@ -1 +1 @@
-1.7.0
+1.8.0

data/lib/patient_http/client.rb

@@ -23,9 +23,15 @@ module PatientHttp
     # use {#decode_response} to produce the final body string. Splitting the
     # decode out keeps CPU-bound work off the reactor thread.
     #
+    # The request timeout limits the full exchange. The read timeout, if set,
+    # limits the wait for the response headers and the wait for each body
+    # chunk.
+    #
     # @param request [Request] The request to make.
     # @param request_id [String] Unique request identifier.
-    # @return [Hash] The response data with keys for :status, :headers, and :body.
+    # @return [Hash] The response data with keys for :status, :headers, :body,
+    #   and :max_response_size. The size limit goes with the data so that
+    #   {#decode_response} applies the same limit to the inflated body.
     def make_request(request, request_id)
       async_response = nil
       client = nil
@@ -36,21 +42,31 @@ module PatientHttp
         headers = outgoing.headers.to_h
         body = Protocol::HTTP::Body::Buffered.wrap([request.body.to_s]) if request.body
         timeout = request.timeout || config.request_timeout
+        read_timeout = request.read_timeout || config.read_timeout
+        max_response_size = request.max_response_size || config.max_response_size
 
         Async::Task.current.with_timeout(timeout) do
           endpoint = Async::HTTP::Endpoint.parse(url)
-          async_response = request_with_immediate_retries(
-            @client_pool, request, endpoint, headers, body
-          ) { |pooled_client| client = pooled_client }
+          async_response = ResponseReader.with_read_timeout(read_timeout) do
+            request_with_immediate_retries(
+              @client_pool, request, endpoint, headers, body
+            ) { |pooled_client| client = pooled_client }
+          end
           # 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 = @response_reader.read_raw_body(async_response, headers_hash)
+          body = @response_reader.read_raw_body(
+            async_response,
+            headers_hash,
+            max_response_size: max_response_size,
+            read_timeout: read_timeout
+          )
 
           {
             status: async_response.status,
             headers: headers_hash,
-            body: body
+            body: body,
+            max_response_size: max_response_size
           }
         end
       rescue => e
@@ -75,14 +91,19 @@ module PatientHttp
     # intended to run on a completion worker thread.
     #
     # @param response_data [Hash] Raw response data from {#make_request}.
-    # @return [Hash] Response data with the decoded body string.
+    # @return [Hash] Response data with the :status, :headers, and decoded
+    #   :body keys.
     # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
     def decode_response(response_data)
       headers = response_data[:headers]
-      body = @response_reader.decode_body(response_data[:body], headers)
+      body = @response_reader.decode_body(
+        response_data[:body],
+        headers,
+        max_response_size: response_data[:max_response_size]
+      )
       headers = ResponseReader.rewrite_content_encoding(headers)
 
-      response_data.merge(headers: headers, body: body)
+      response_data.except(:max_response_size).merge(headers: headers, body: body)
     end
 
     # Closes all clients and releases their resources.

data/lib/patient_http/configuration.rb

@@ -42,6 +42,10 @@ module PatientHttp
     # @return [Numeric] The default request timeout in seconds.
     attr_reader :request_timeout
 
+    # @return [Numeric, nil] The default maximum number of seconds to wait for
+    #   data from the server, or `nil` for no limit. See {#read_timeout=}.
+    attr_reader :read_timeout
+
     # @return [Numeric] The graceful shutdown timeout in seconds.
     attr_reader :shutdown_timeout
 
@@ -113,6 +117,9 @@ module PatientHttp
     #
     # @param max_connections [Integer] The maximum number of concurrent requests.
     # @param request_timeout [Numeric] The default request timeout in seconds.
+    # @param read_timeout [Numeric, nil] The default maximum number of seconds to
+    #   wait for data from the server. If `nil`, there is no limit. See
+    #   {#read_timeout=}.
     # @param shutdown_timeout [Numeric] The graceful shutdown timeout in seconds.
     # @param logger [Logger, nil] The logger. If `nil`, errors are logged to
     #   standard error.
@@ -157,6 +164,7 @@ module PatientHttp
     def initialize(
       max_connections: 256,
       request_timeout: 60,
+      read_timeout: nil,
       shutdown_timeout: 30,
       logger: nil,
       max_response_size: 1024 * 1024,
@@ -195,6 +203,7 @@ module PatientHttp
 
       self.max_connections = max_connections
       self.request_timeout = request_timeout
+      self.read_timeout = read_timeout
       self.shutdown_timeout = shutdown_timeout
       self.logger = logger || Logger.new($stderr, level: Logger::ERROR)
       self.max_response_size = max_response_size
@@ -293,6 +302,33 @@ module PatientHttp
       @request_timeout = value
     end
 
+    # Sets the default read timeout. This is the maximum number of seconds to
+    # wait for data from the server. The timer starts again each time a body
+    # chunk arrives. A response that sends data at regular intervals can thus
+    # continue for longer than the read timeout. The request timeout continues
+    # to limit the full request.
+    #
+    # The first timer starts before the connection opens. It covers the time to
+    # get a connection, send the request, and wait for the response headers.
+    # Immediate retries of a refused connection use the same timer. This is
+    # different from clients such as Net::HTTP, which use a separate open
+    # timeout and write timeout. The connection timeout continues to limit the
+    # time to open a connection.
+    #
+    # Use it for streamed responses, such as server-sent events. Do not use it
+    # for requests where the server does all of its work before it sends the
+    # response headers, because the wait for the headers must then be shorter
+    # than the read timeout.
+    #
+    # @param value [Numeric, nil] A positive number of seconds, or `nil` for no
+    #   limit.
+    # @return [void]
+    # @raise [ArgumentError] If the value isn't positive or `nil`.
+    def read_timeout=(value)
+      validate_positive(:read_timeout, value) unless value.nil?
+      @read_timeout = value
+    end
+
     # Sets the graceful shutdown timeout. Keep it less than the stop timeout of
     # the process supervisor, so that in-flight requests finish before a hard
     # kill.
@@ -307,7 +343,8 @@ module PatientHttp
 
     # Sets the maximum response body size. For a compressed response, the limit
     # applies to the decompressed body. A larger response raises
-    # {ResponseTooLargeError}.
+    # {ResponseTooLargeError}. A request can set its own limit with
+    # {Request#max_response_size}.
     #
     # @param value [Integer] A positive number of bytes.
     # @return [void]
@@ -695,6 +732,7 @@ module PatientHttp
       {
         "max_connections" => max_connections,
         "request_timeout" => request_timeout,
+        "read_timeout" => read_timeout,
         "shutdown_timeout" => shutdown_timeout,
         "logger" => logger,
         "max_response_size" => max_response_size,

data/lib/patient_http/request.rb

@@ -39,6 +39,16 @@ module PatientHttp
     # @return [Numeric, nil] The timeout in seconds for the full request.
     attr_reader :timeout
 
+    # @return [Numeric, nil] The maximum number of seconds to wait for data from
+    #   the server. The timer covers the wait for the response headers and
+    #   starts again each time a body chunk arrives. If `nil`, the configuration
+    #   value applies.
+    attr_reader :read_timeout
+
+    # @return [Integer, nil] The maximum response body size in bytes for this
+    #   request. If `nil`, the configuration value applies.
+    attr_reader :max_response_size
+
     # @return [Integer, nil] The maximum number of redirects to follow. If `0`,
     #   redirects aren't followed. If `nil`, the configuration value applies.
     attr_reader :max_redirects
@@ -79,6 +89,8 @@ module PatientHttp
           body: Payload.load(hash["body"])&.value,
           params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
+          read_timeout: hash["read_timeout"],
+          max_response_size: hash["max_response_size"],
           max_redirects: hash["max_redirects"],
           follow_method_changing_redirects: hash["follow_method_changing_redirects"],
           redirect_strip_headers: hash["redirect_strip_headers"],
@@ -118,6 +130,14 @@ module PatientHttp
     #   with `body`.
     # @param params [Hash, nil] The query parameters to add to the URL.
     # @param timeout [Numeric, nil] The timeout in seconds for the full request.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait
+    #   for data from the server. The timer covers the wait for the response
+    #   headers and starts again each time a body chunk arrives. Use it for
+    #   streamed responses. Do not use it when the server does all of its work
+    #   before it sends the headers. If `nil`, the configuration value applies.
+    # @param max_response_size [Integer, nil] The maximum response body size in
+    #   bytes. For a compressed response, the limit also applies to the
+    #   decompressed body. If `nil`, the configuration value applies.
     # @param max_redirects [Integer, nil] The maximum number of redirects to
     #   follow. If `0`, redirects aren't followed. If `nil`, the configuration
     #   value applies.
@@ -132,8 +152,8 @@ module PatientHttp
     # @param processor [String, Symbol, nil] The name of the processor that runs
     #   the request. Integrations use this value to send the request to a named
     #   processor.
-    # @raise [ArgumentError] If the HTTP method, URL, or body isn't valid, or if
-    #   both `body` and `json` are given.
+    # @raise [ArgumentError] If the HTTP method, URL, body, `read_timeout`, or
+    #   `max_response_size` isn't valid, or if both `body` and `json` are given.
     def initialize(
       http_method,
       url,
@@ -142,6 +162,8 @@ module PatientHttp
       json: nil,
       params: nil,
       timeout: nil,
+      read_timeout: nil,
+      max_response_size: nil,
       max_redirects: nil,
       follow_method_changing_redirects: nil,
       redirect_strip_headers: nil,
@@ -161,6 +183,8 @@ module PatientHttp
       @headers = headers.is_a?(HttpHeaders) ? headers.dup : HttpHeaders.new(headers)
       @body = (body == "") ? nil : body
       @timeout = timeout
+      @read_timeout = normalized_read_timeout(read_timeout)
+      @max_response_size = normalized_max_response_size(max_response_size)
       @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)
@@ -210,6 +234,9 @@ module PatientHttp
         "max_redirects" => @max_redirects
       }
 
+      hash["read_timeout"] = @read_timeout if @read_timeout
+      hash["max_response_size"] = @max_response_size if @max_response_size
+
       if @secret_params.any?
         hash["secret_params"] = @secret_params.transform_values(&:as_json)
       end
@@ -243,6 +270,26 @@ module PatientHttp
       raise ArgumentError.new("follow_method_changing_redirects must be true, false, or nil, got: #{value.inspect}")
     end
 
+    # Validate the read timeout is a positive number or nil.
+    def normalized_read_timeout(value)
+      return nil if value.nil?
+      return value if value.is_a?(Numeric) && value > 0
+
+      raise ArgumentError.new(
+        "read_timeout must be a positive number or nil, got: #{value.inspect}"
+      )
+    end
+
+    # Validate the maximum response size is a positive integer or nil.
+    def normalized_max_response_size(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer) && value > 0
+
+      raise ArgumentError.new(
+        "max_response_size must be a positive integer 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?

data/lib/patient_http/request_helper.rb

@@ -137,16 +137,32 @@ module PatientHttp
       # @param params [Hash, nil] The default query parameters.
       # @param timeout [Numeric, nil] The default request timeout in seconds. If
       #   `nil`, the configured `request_timeout` applies.
+      # @param read_timeout [Numeric, nil] The default maximum number of seconds to
+      #   wait for data from the server. If `nil`, the configured `read_timeout`
+      #   applies.
+      # @param max_response_size [Integer, nil] The default maximum response body
+      #   size in bytes. If `nil`, the configured `max_response_size` applies.
       # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] The names
       #   of the default preprocessors.
       # @param processor [String, Symbol, nil] The name of the default processor.
       # @return [void]
-      def request_template(base_url: nil, headers: {}, params: nil, timeout: nil, preprocessors: nil, processor: nil)
+      def request_template(
+        base_url: nil,
+        headers: {},
+        params: nil,
+        timeout: nil,
+        read_timeout: nil,
+        max_response_size: nil,
+        preprocessors: nil,
+        processor: nil
+      )
         @patient_http_request_template = RequestTemplate.new(
           base_url: base_url,
           headers: headers,
           params: params,
           timeout: timeout,
+          read_timeout: read_timeout,
+          max_response_size: max_response_size,
           preprocessors: preprocessors,
           processor: processor
         )
@@ -167,6 +183,12 @@ module PatientHttp
       #   combined with `body`.
       # @param params [Hash, nil] The query parameters to add to the URL.
       # @param timeout [Numeric, nil] The request timeout in seconds.
+      # @param read_timeout [Numeric, nil] The maximum number of seconds to wait
+      #   for data from the server. The timer covers the wait for the response
+      #   headers and starts again each time a body chunk arrives. If `nil`, the
+      #   configuration value applies.
+      # @param max_response_size [Integer, nil] The maximum response body size in
+      #   bytes. If `nil`, the configuration value applies.
       # @param raise_error_responses [Boolean, nil] If `true`, non-2xx responses go
       #   to the `on_error` callback as an {HttpError}.
       # @param callback_args [Hash, nil] The JSON-compatible arguments to pass to the
@@ -194,6 +216,8 @@ module PatientHttp
         json: nil,
         params: nil,
         timeout: nil,
+        read_timeout: nil,
+        max_response_size: nil,
         raise_error_responses: nil,
         callback_args: nil,
         max_redirects: nil,
@@ -209,6 +233,8 @@ module PatientHttp
           headers: headers,
           params: params,
           timeout: timeout,
+          read_timeout: read_timeout,
+          max_response_size: max_response_size,
           max_redirects: max_redirects,
           follow_method_changing_redirects: follow_method_changing_redirects,
           redirect_strip_headers: redirect_strip_headers,
@@ -257,6 +283,12 @@ module PatientHttp
     #   combined with `body`.
     # @param params [Hash, nil] The query parameters to add to the URL.
     # @param timeout [Numeric, nil] The request timeout in seconds.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   data from the server. The timer covers the wait for the response headers
+    #   and starts again each time a body chunk arrives. If `nil`, the
+    #   configuration value applies.
+    # @param max_response_size [Integer, nil] The maximum response body size in
+    #   bytes. If `nil`, the configuration value applies.
     # @param raise_error_responses [Boolean, nil] If `true`, non-2xx responses go
     #   to the `on_error` callback as an {HttpError}.
     # @param callback_args [Hash, nil] The JSON-compatible arguments to pass to the
@@ -284,6 +316,8 @@ module PatientHttp
       json: nil,
       params: nil,
       timeout: nil,
+      read_timeout: nil,
+      max_response_size: nil,
       raise_error_responses: nil,
       callback_args: nil,
       max_redirects: nil,
@@ -301,6 +335,8 @@ module PatientHttp
         json: json,
         params: params,
         timeout: timeout,
+        read_timeout: read_timeout,
+        max_response_size: max_response_size,
         raise_error_responses: raise_error_responses,
         callback_args: callback_args,
         max_redirects: max_redirects,

data/lib/patient_http/request_task.rb

@@ -274,6 +274,8 @@ module PatientHttp
         headers: redirect_headers,
         body: redirect_body,
         timeout: request.timeout,
+        read_timeout: request.read_timeout,
+        max_response_size: request.max_response_size,
         max_redirects: request.max_redirects,
         follow_method_changing_redirects: request.follow_method_changing_redirects,
         redirect_strip_headers: request.redirect_strip_headers,

data/lib/patient_http/request_template.rb

@@ -27,6 +27,14 @@ module PatientHttp
     #   the configured `request_timeout` applies.
     attr_accessor :timeout
 
+    # @return [Numeric, nil] The default read timeout in seconds. If `nil`, the
+    #   configured `read_timeout` applies.
+    attr_accessor :read_timeout
+
+    # @return [Integer, nil] The default maximum response body size in bytes. If
+    #   `nil`, the configured `max_response_size` applies.
+    attr_accessor :max_response_size
+
     # Creates a template.
     #
     # @param base_url [String, URI::HTTP, nil] The base URL that relative paths
@@ -35,15 +43,31 @@ module PatientHttp
     # @param params [Hash, nil] The default query parameters for all requests.
     # @param timeout [Numeric, nil] The default request timeout in seconds. If
     #   `nil`, the configured `request_timeout` applies.
+    # @param read_timeout [Numeric, nil] The default maximum number of seconds to
+    #   wait for data from the server. If `nil`, the configured `read_timeout`
+    #   applies.
+    # @param max_response_size [Integer, nil] The default maximum response body
+    #   size in bytes. If `nil`, the configured `max_response_size` applies.
     # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] The names
     #   of the default preprocessors for all requests.
     # @param processor [String, Symbol, nil] The name of the default processor for
     #   all requests.
-    def initialize(base_url: nil, headers: {}, params: nil, timeout: nil, preprocessors: nil, processor: nil)
+    def initialize(
+      base_url: nil,
+      headers: {},
+      params: nil,
+      timeout: nil,
+      read_timeout: nil,
+      max_response_size: nil,
+      preprocessors: nil,
+      processor: nil
+    )
       @base_url = base_url
       @headers = HttpHeaders.new(headers)
       @params = params
       @timeout = timeout
+      @read_timeout = read_timeout
+      @max_response_size = max_response_size
       @preprocessors = preprocessors
       @processor = processor
     end
@@ -62,6 +86,10 @@ module PatientHttp
     #   parameters.
     # @param timeout [Numeric, nil] The request timeout in seconds. Overrides the
     #   template timeout.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   data from the server. Overrides the template read timeout.
+    # @param max_response_size [Integer, nil] The maximum response body size in
+    #   bytes. Overrides the template value.
     # @param max_redirects [Integer, nil] The maximum number of redirects to
     #   follow. If `0`, redirects aren't followed. If `nil`, the configuration
     #   value applies.
@@ -84,6 +112,8 @@ module PatientHttp
       headers: nil,
       params: nil,
       timeout: nil,
+      read_timeout: nil,
+      max_response_size: nil,
       max_redirects: nil,
       follow_method_changing_redirects: nil,
       redirect_strip_headers: nil,
@@ -104,6 +134,8 @@ module PatientHttp
         json: json,
         params: merged_params,
         timeout: timeout || @timeout,
+        read_timeout: read_timeout || @read_timeout,
+        max_response_size: max_response_size || @max_response_size,
         max_redirects: max_redirects,
         follow_method_changing_redirects: follow_method_changing_redirects,
         redirect_strip_headers: redirect_strip_headers,

data/lib/patient_http/response_reader.rb

@@ -89,6 +89,28 @@ module PatientHttp
           headers_hash.merge("content-encoding" => remaining.join(", "))
         end
       end
+
+      # Runs a block that waits for data from the server, and stops it if no
+      # data arrives in time. Each call starts a new timer, so call it once for
+      # each wait: once for the response headers and once for each body chunk.
+      #
+      # The block must run in an Async task.
+      #
+      # @param read_timeout [Numeric, nil] The maximum number of seconds to wait.
+      #   If `nil`, the block runs without a limit.
+      # @yield Waits for data from the server.
+      # @return [Object] The value of the block.
+      # @raise [ReadTimeoutError] If the block doesn't finish in time.
+      def with_read_timeout(read_timeout, &block)
+        return yield if read_timeout.nil?
+
+        Async::Task.current.with_timeout(
+          read_timeout,
+          ReadTimeoutError,
+          "No data received from the server for #{read_timeout} seconds",
+          &block
+        )
+      end
     end
 
     # Creates the reader.
@@ -115,21 +137,44 @@ module PatientHttp
     # 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.
+    # read starts. The HTTP/1 parser moves that header into the body, so the
+    # length of the body is used when the header is not present. A response to
+    # a HEAD request has an empty body but reports the Content-Length of the
+    # resource, so the check is skipped when the body reports itself as empty.
+    #
+    # A read timeout limits the wait for each chunk. The timer starts again
+    # each time a chunk arrives, so a body that arrives slowly but steadily is
+    # read to the end.
     #
     # @param async_response [Async::HTTP::Protocol::Response] The async HTTP response.
     # @param headers_hash [Hash] The response headers.
+    # @param max_response_size [Integer, nil] The size limit in bytes. If `nil`,
+    #   the configuration value applies.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   each chunk. If `nil`, there is no limit.
     # @return [Array<String>, nil] The raw body chunks or nil if no body present.
     # @raise [ResponseTooLargeError] If the body exceeds max_response_size.
+    # @raise [ReadTimeoutError] If no chunk arrives within the read timeout.
     # @raise [ReadAbortedError] If the processor stopped past its shutdown deadline mid-read.
-    def read_raw_body(async_response, headers_hash)
+    def read_raw_body(async_response, headers_hash, max_response_size: nil, read_timeout: nil)
       body = async_response.body
       return nil unless body
 
-      validate_content_length(headers_hash) unless body.empty?
-      read_body_chunks(async_response)
+      limit = max_response_size || @config.max_response_size
+      error = nil
+
+      begin
+        validate_content_length(headers_hash, body, limit) unless body.empty?
+        read_body_chunks(body, limit, read_timeout)
+      rescue => e
+        error = e
+        raise
+      ensure
+        # Always close the body. A body that is closed with an error discards
+        # its connection, so a connection that is not fully read is not
+        # returned to the pool.
+        body.close(error)
+      end
     end
 
     # Decodes raw body chunks into the final body string.
@@ -147,15 +192,18 @@ module PatientHttp
     #
     # @param chunks [Array<String>, nil] The raw body chunks.
     # @param headers_hash [Hash] The response headers.
+    # @param max_response_size [Integer, nil] The size limit in bytes for the
+    #   inflated body. If `nil`, the configuration value applies.
     # @return [String, nil] The decoded body or nil if there was no body.
     # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
-    def decode_body(chunks, headers_hash)
+    def decode_body(chunks, headers_hash, max_response_size: nil)
       return nil if chunks.nil?
 
       remaining, decodable = self.class.split_encodings(headers_hash)
       warn_undecodable(remaining) unless remaining.empty?
 
-      body = inflate_encodings(chunks, decodable).join
+      limit = max_response_size || @config.max_response_size
+      body = inflate_encodings(chunks, decodable, limit).join
       body.force_encoding(Encoding::ASCII_8BIT)
       # A body that is still encoded is not text yet, so the charset does not
       # describe its bytes. Leave it binary for the caller to decode.
@@ -171,11 +219,12 @@ module PatientHttp
     #
     # @param chunks [Array<String>] The encoded body chunks.
     # @param encodings [Array<String>] Decodable encoding names in applied order.
+    # @param limit [Integer] The size limit in bytes for the inflated body.
     # @return [Array<String>] The decoded chunks.
-    # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
-    def inflate_encodings(chunks, encodings)
+    # @raise [ResponseTooLargeError] If the inflated body exceeds the limit.
+    def inflate_encodings(chunks, encodings, limit)
       encodings.reverse_each do |name|
-        chunks = [inflate_encoding(chunks, name)] if INFLATE_WINDOW_BITS.key?(name)
+        chunks = [inflate_encoding(chunks, name, limit)] if INFLATE_WINDOW_BITS.key?(name)
       end
 
       chunks
@@ -187,15 +236,16 @@ module PatientHttp
     #
     # @param chunks [Array<String>] The encoded body chunks.
     # @param name [String] A lowercased content encoding name.
+    # @param limit [Integer] The size limit in bytes for the inflated body.
     # @return [String] The inflated body.
     # @raise [Zlib::Error] If no format could inflate the body.
-    # @raise [ResponseTooLargeError] If the inflated body exceeds max_response_size.
-    def inflate_encoding(chunks, name)
+    # @raise [ResponseTooLargeError] If the inflated body exceeds the limit.
+    def inflate_encoding(chunks, name, limit)
       formats = INFLATE_WINDOW_BITS.fetch(name)
       last_index = formats.size - 1
 
       formats.each_with_index do |window_bits, index|
-        return inflate_chunks(chunks, window_bits)
+        return inflate_chunks(chunks, window_bits, limit)
       rescue Zlib::DataError, Zlib::BufError
         raise if index == last_index
       end
@@ -215,77 +265,74 @@ module PatientHttp
       nil
     end
 
-    def max_response_size
-      @config.max_response_size
-    end
-
     def logger
       @config.logger
     end
 
-    # Validates content-length header doesn't exceed max size.
+    # Validates the declared body length doesn't exceed max size.
     #
     # @param headers_hash [Hash] The response headers.
-    # @raise [ResponseTooLargeError] If content-length exceeds max_response_size.
-    def validate_content_length(headers_hash)
-      content_length = headers_hash["content-length"]&.to_i
-      if content_length && content_length > max_response_size
+    # @param body [Protocol::HTTP::Body::Readable] The response body.
+    # @param limit [Integer] The size limit in bytes.
+    # @raise [ResponseTooLargeError] If the declared length exceeds the limit.
+    def validate_content_length(headers_hash, body, limit)
+      content_length = headers_hash["content-length"]&.to_i || body.length
+      if content_length && content_length > limit
         raise ResponseTooLargeError.new(
-          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{max_response_size} bytes)"
+          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{limit} bytes)"
         )
       end
     end
 
     # Reads body chunks while checking size.
     #
-    # @param async_response [Async::HTTP::Protocol::Response] The async HTTP response.
+    # Each chunk is read with its own read timeout, so the timer starts again
+    # after every chunk.
+    #
+    # @param body [Protocol::HTTP::Body::Readable] The response body.
+    # @param limit [Integer] The size limit in bytes.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   each chunk.
     # @return [Array<String>] The raw body chunks.
-    # @raise [ResponseTooLargeError] If body size exceeds max_response_size during read.
+    # @raise [ResponseTooLargeError] If body size exceeds the limit during read.
+    # @raise [ReadTimeoutError] If no chunk arrives within the read timeout.
     # @raise [ReadAbortedError] If the processor stopped past its shutdown deadline mid-read.
-    def read_body_chunks(async_response)
+    def read_body_chunks(body, limit, read_timeout)
       chunks = []
       total_size = 0
-      finished = false
 
-      begin
-        async_response.body.each do |chunk|
-          # 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
-
-          if total_size > max_response_size
-            raise ResponseTooLargeError.new(
-              "Response body size exceeded maximum allowed size (#{max_response_size} bytes)"
-            )
-          end
-
-          chunks << chunk
+      while (chunk = self.class.with_read_timeout(read_timeout) { body.read })
+        # 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
 
-        finished = true
+        total_size += chunk.bytesize
 
-        chunks
-      ensure
-        # Always close the body if we were interrupted or if an error occurred
-        # This ensures the connection is properly released back to the pool
-        async_response.body.close unless finished
+        if total_size > limit
+          raise ResponseTooLargeError.new(
+            "Response body size exceeded maximum allowed size (#{limit} bytes)"
+          )
+        end
+
+        chunks << chunk
       end
+
+      chunks
     end
 
     # Inflates compressed body chunks with streaming size enforcement, so a
-    # small compressed body cannot expand past max_response_size.
+    # small compressed body cannot expand past the size limit.
     #
     # @param chunks [Array<String>] The raw compressed chunks.
     # @param window_bits [Integer] Zlib window bits for the content encoding.
+    # @param limit [Integer] The size limit in bytes for the inflated body.
     # @return [String] The inflated body.
-    # @raise [ResponseTooLargeError] If the inflated size exceeds max_response_size.
-    def inflate_chunks(chunks, window_bits)
+    # @raise [ResponseTooLargeError] If the inflated size exceeds the limit.
+    def inflate_chunks(chunks, window_bits, limit)
       # A response can declare a content encoding and still carry no body.
       # There is nothing to inflate, and finishing an empty stream would
       # raise a buffer error.
@@ -301,7 +348,7 @@ module PatientHttp
         # before any check runs.
         appender = ->(output) do
           body << output
-          validate_inflated_size(body)
+          validate_inflated_size(body, limit)
         end
 
         chunks.each { |chunk| inflater.inflate(chunk, &appender) }
@@ -313,10 +360,10 @@ module PatientHttp
       body
     end
 
-    def validate_inflated_size(body)
-      if body.bytesize > max_response_size
+    def validate_inflated_size(body, limit)
+      if body.bytesize > limit
         raise ResponseTooLargeError.new(
-          "Response body size exceeded maximum allowed size (#{max_response_size} bytes)"
+          "Response body size exceeded maximum allowed size (#{limit} bytes)"
         )
       end
     end

data/lib/patient_http/synchronous_executor.rb

@@ -121,26 +121,43 @@ module PatientHttp
     # wrapper isn't used, because it replaces an `accept-encoding` header that
     # the caller set to turn off compression.
     #
+    # The request timeout limits the full exchange. The read timeout, if set,
+    # limits the wait for the response headers and the wait for each body
+    # chunk.
+    #
     # @return [Hash] The response data, with the `:status`, `:headers`, and
     #   `:body` keys.
     def perform_request
       outgoing = @request_preparer.prepare(@task.request, @task.id)
       timeout = @task.request.timeout || @config.request_timeout
+      read_timeout = @task.request.read_timeout || @config.read_timeout
+      max_response_size = @task.request.max_response_size || @config.max_response_size
 
       Async::Task.current.with_timeout(timeout) do
         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(outgoing.url)
-        async_response = request_with_immediate_retries(
-          @client_pool, @task.request, endpoint, headers, body
-        )
+        async_response = ResponseReader.with_read_timeout(read_timeout) do
+          request_with_immediate_retries(
+            @client_pool, @task.request, endpoint, headers, body
+          )
+        end
         # 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)
 
-        chunks = @response_reader.read_raw_body(async_response, headers_hash)
-        body_content = @response_reader.decode_body(chunks, headers_hash)
+        chunks = @response_reader.read_raw_body(
+          async_response,
+          headers_hash,
+          max_response_size: max_response_size,
+          read_timeout: read_timeout
+        )
+        body_content = @response_reader.decode_body(
+          chunks,
+          headers_hash,
+          max_response_size: max_response_size
+        )
 
         {
           status: async_response.status,

data/lib/patient_http.rb

@@ -37,6 +37,12 @@ module PatientHttp
   # Raised when a response body is larger than `max_response_size`.
   class ResponseTooLargeError < StandardError; end
 
+  # Raised when no data arrives from the server for `read_timeout` seconds. It
+  # is a subclass of `Async::TimeoutError`, so the error type of the
+  # {RequestError} is `:timeout`. Use the class name to tell it apart from the
+  # timeout for the full request.
+  class ReadTimeoutError < Async::TimeoutError; end
+
   # Raised when a request names a processor that isn't configured. The job
   # system then retries the job instead of dropping it.
   class UnknownProcessorError < StandardError; end
@@ -369,6 +375,12 @@ module PatientHttp
     #   combined with `body`.
     # @param params [Hash, nil] The query parameters to add to the URL.
     # @param timeout [Numeric, nil] The request timeout in seconds.
+    # @param read_timeout [Numeric, nil] The maximum number of seconds to wait for
+    #   data from the server. The timer covers the wait for the response headers
+    #   and starts again each time a body chunk arrives. If `nil`, the
+    #   configuration value applies.
+    # @param max_response_size [Integer, nil] The maximum response body size in
+    #   bytes. If `nil`, the configuration value applies.
     # @param raise_error_responses [Boolean, nil] If `true`, non-2xx responses go
     #   to the `on_error` callback as an {HttpError}. If `nil`, the configuration
     #   value applies.
@@ -397,6 +409,8 @@ module PatientHttp
       json: nil,
       params: nil,
       timeout: nil,
+      read_timeout: nil,
+      max_response_size: nil,
       raise_error_responses: nil,
       callback_args: nil,
       max_redirects: nil,
@@ -413,6 +427,8 @@ module PatientHttp
         headers: headers,
         params: params,
         timeout: timeout,
+        read_timeout: read_timeout,
+        max_response_size: max_response_size,
         max_redirects: max_redirects,
         follow_method_changing_redirects: follow_method_changing_redirects,
         redirect_strip_headers: redirect_strip_headers,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_http
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Brian Durand