patient_http 1.6.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b3bb6335d47143a8f6e8123be222265651c3e3cee1c8a0084f3aae02b6f6444
-  data.tar.gz: 9c0a549ff00b9861073fd9853d82a6736c26bf34fca3ac689acf14008968abd5
+  metadata.gz: c4e10ada7964f607e81e169e4f88086d3dd32967fd6bf6ed48025615a133d5fd
+  data.tar.gz: 704ca986fb7622f6e977d8d02d76e198c98abdd1c5ea808d85c8af25bdd3f72f
 SHA512:
-  metadata.gz: c13e5e339088c84e7977ba82c6484780a890076af083d2dbf2754bf1ff0eb05d6a28d585be4d56b13bf5a052d00b643b2c8d44b90a5766fab9cd426c03375830
-  data.tar.gz: cdf38eeac4823f3cb922001541c3d9425c993cc4ce075ca80ff427d2a79a6d38928999518cd690181aaa8d4064554ea087666a54bb426a829809135dc0c4bf35
+  metadata.gz: 442991bea3a29c334866d9136bca7f9ada37d68326b537b31571bae9331f93387e3a617ff970e1433f289fbb078346b33a9394a22afc9eea01e7347233476fe9
+  data.tar.gz: baee6575b4bdf5f7798548cc17419d33234f255088bd612d41daec3bceafd56a7a96acb7f86f991d2b6f1a9e31f316100dee6b243e14b8b56831935614b46055

data/ARCHITECTURE.md

@@ -20,13 +20,13 @@ The heart of the system - runs in a dedicated thread with its own Fiber reactor.
 Abstract base class that defines the integration point between the pool and your application. Implementations handle completion callbacks, error callbacks, and job retry operations. Concrete implementations (such as those in the `patient_http-sidekiq` or `patient_http-solid_queue` gems) are responsible for using `Configuration#encryptor` to encrypt serialized `Response`/`Error` data before passing it to the job queue. The base class itself does not call encrypt or decrypt; that responsibility belongs to the implementation. This abstraction allows the pool to work with any job system (Sidekiq, SolidQueue, custom queues, etc.).
 
 ### Request/RequestTemplate
-`Request` is an immutable value object representing an HTTP request. `RequestTemplate` provides a builder for creating requests with shared configuration (base URL, headers, timeout).
+`Request` is a value object representing an HTTP request. `RequestTemplate` provides a builder for creating requests with shared configuration (base URL, headers, timeout).
 
 ### RequestTask
 Wraps a `Request` with execution context: the `TaskHandler`, callback class name, and callback arguments. This is what gets enqueued to the processor.
 
 ### Response
-Immutable value object representing an HTTP response. Includes status, headers, body, and callback arguments. Designed to be serializable for passing through job queues.
+Value object representing an HTTP response. Includes status, headers, body, and callback arguments. Designed to be serializable for passing through job queues.
 
 ### Error Classes
 Typed error classes (`HttpError`, `RequestError`, `RedirectError`) that are also serializable. Include context about the failed request and callback arguments.
@@ -44,7 +44,7 @@ Manages processor state transitions (stopped → starting → running → draini
 Handles encryption and decryption of serialized payloads at the job queue boundary. Wraps user-provided encryption/decryption callables (which operate on raw bytes) with JSON serialization and Base64 encoding. Instantiated from `Configuration#encryptor`. The `Encryptor` is a helper: concrete `TaskHandler` implementations are responsible for calling `encryptor.encrypt`/`encryptor.decrypt` at every serialization boundary. Encrypted data is enveloped as `{"__encrypted__" => true, "value" => "<base64>"}` to allow transparent no-op pass-through when no encryption is configured.
 
 ### ExternalStorage/PayloadStore
-Optional external storage for large request/response payloads. Supports file, Redis, S3, and custom adapters.
+Optional external storage for large request/response payloads. Supports file, Redis, S3, ActiveRecord, and custom adapters.
 
 ## TaskHandler Pattern
 
@@ -110,12 +110,13 @@ Example:
 PatientHttp.register_handler do |request:, callback:, callback_args: nil, raise_error_responses: nil|
   task = PatientHttp::RequestTask.new(
     request: request,
-    task_handler: MyTaskHandler.new,
+    task_handler: MyTaskHandler.new(MyJobSystem.current_job_id),
     callback: callback,
     callback_args: callback_args,
     raise_error_responses: raise_error_responses
   )
   processor.enqueue(task)
+  task.id
 end
 
 # Use in your application code
@@ -205,6 +206,8 @@ erDiagram
         hash headers
         string body
         float timeout
+        float read_timeout
+        int max_response_size
     }
 
     REQUEST-TASK {
@@ -282,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:
@@ -296,8 +305,8 @@ The processor maintains state through its lifecycle:
 
 When the processor is stopped with in-flight requests:
 
-1. The processor stops accepting new requests (drain state)
-2. In-flight requests are given time to complete (configurable timeout)
+1. The processor stops accepting new requests (stopping state). Call `drain` first to stop accepting requests before the stop begins.
+2. In-flight requests are given time to complete (`shutdown_timeout`, or the `timeout` passed to `stop`)
 3. Any requests still pending when the timeout expires trigger `TaskHandler#retry`
 4. The application's job system can re-enqueue these requests for later processing
 
@@ -306,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
@@ -327,7 +337,7 @@ For large request/response payloads, the `ExternalStorage` class provides option
 - **Thread-safe queues**: `Thread::Queue` for request enqueueing
 - **Atomic operations**: `Concurrent::AtomicReference` for state
 - **Synchronized access**: Mutexes protect shared data structures
-- **Immutable values**: Request/Response are immutable once created
+- **Value objects**: Request and Response have no setters for their attributes
 
 ## Further Reading
 

data/CHANGELOG.md

@@ -4,6 +4,49 @@ 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
+
+- `PatientHttp.configure` is a single entry point for configuration regardless of which job system is in use. When an integration gem (patient_http-sidekiq, patient_http-solid_queue) is loaded it yields that integration's configuration; otherwise it yields a plain `Configuration` used for inline execution. The same object is yielded on every call, so options accumulate and several initializers can each contribute without overwriting one another. Application code no longer has to name the integration to configure it.
+- `PatientHttp.configuration` returns that configuration, creating it on first use and applying any secrets registered with `PatientHttp.register_secret`. There is no longer a boot order to get right.
+- `PatientHttp.register_configuration_provider` lets an integration gem supply the configuration class that `configure` and `configuration` build. The configuration object itself is stored here, so there is exactly one in a process no matter which module it is reached through. `PatientHttp.configuration_provider` returns the registered provider. Loading two integrations in one process warns instead of silently taking the last one.
+- `Configuration#payload_store_threshold` (default 64KB): the size above which a serialized payload is written to the registered payload store. This moves the option next to `register_payload_store`, where the store it applies to is registered. The integration gems inherit it, and their own `payload_store_threshold` accessors continue to work.
+- A request that fails before any response byte arrives is retried at once when the failure is known to be safe to retry: the server refused the request before processing it (`Protocol::HTTP::RefusedError`, raised for an HTTP/2 GOAWAY, a pooled connection that closed after it was acquired, or a refused stream), or the request method is idempotent (`Request#idempotent?`: GET, HEAD, PUT, DELETE, QUERY) and the connection failed. A connection failure evicts the host's pooled client first, so the retry uses a new connection. A request is retried up to `ImmediateRetries::IMMEDIATE_RETRY_LIMIT` times, or `retries - 1` times when the `retries` setting is higher. A POST or PATCH that fails with `EOFError`, `ECONNRESET`, `ECONNABORTED`, `EPIPE`, or `ETIMEDOUT` before a response is not retried, because the server may have processed it.
+- `Configuration#tcp_keepalive` enables TCP keepalive on pooled connections, as an idle time in seconds or a Hash with `:idle`, `:interval`, and `:count`. Keepalive probes keep NAT and firewall mappings alive while a connection is idle and let the kernel detect a dead peer, so the connection is retired before a request is sent on it.
+- `Configuration#tcp_user_timeout` sets `TCP_USER_TIMEOUT` (Linux only) on pooled connections: the seconds transmitted data may stay unacknowledged before the kernel aborts the connection with `ETIMEDOUT`. A request sent on a connection whose peer has silently gone away fails after this long instead of waiting for `request_timeout`. Acknowledged data is not affected, so a slow response is never cut short. `ETIMEDOUT` from the socket is retried at once for idempotent requests like the other connection failures; the request timeout itself is still never retried.
+
+### Changed
+
+- `PatientHttp.default_configuration` is now the configuration created by `PatientHttp.configuration` rather than a separate slot an integration had to remember to assign. It still returns nil until a configuration exists, and assigning nil discards the configuration so the next read builds a fresh one. Assigning a configuration still applies module level secrets to it.
+- The separate configuration that was lazily created for inline execution is gone. Inline requests run against `PatientHttp.configuration`, so they see the same secrets, payload stores, and preprocessors as queued requests instead of a parallel set.
+- Retries are applied by patient_http alone. The async-http clients make a single attempt per request, so the async-http retries and the immediate retries no longer stack.
+- Requires async-http 0.99 or later and declares protocol-http 0.66 or later as a direct dependency, since its error classes are referenced directly.
+- **`RequestTemplate` no longer defaults to a 30 second timeout.** A template without a `timeout` leaves the request timeout unset, so the configured `request_timeout` applies. The same is true for `request_template` in `RequestHelper`. Templates that need 30 seconds must now set `timeout: 30`.
+- `PatientHttp.execute_inline` and `SynchronousExecutor` make their connections through a `ClientPool` that lives for the one execution, so inline requests honor `connection_timeout`, `protocol`, `tcp_keepalive`, `tcp_user_timeout`, and the immediate retry rules exactly as processor-backed requests do. Previously the connection timeout capped inline response reads and no immediate retries applied inline.
+- Minimum Ruby version is 3.3.
+
+### Fixed
+
+- `RequestTemplate#request` and the `RequestHelper` `async_*` methods accept `max_redirects`, like the `PatientHttp` module methods.
+- `connection_timeout` now bounds only the TCP connect and TLS handshake. It was applied as the socket's IO timeout and so also capped every read and write for the life of the connection, including reads on reused keep-alive connections. A server that paused longer than the connection timeout before or between response bytes failed with `IO::TimeoutError` ("read timeout") even when `request_timeout` allowed more time. Once a connection is established the request timeout alone governs the exchange.
+- `IO::TimeoutError` is classified as a `:timeout` error. It was reported as `:connection` because it inherits from `IOError`.
+- Evicting a host's pooled client no longer stalls the processor. The eviction closed the client while holding the client pool lock, and closing waits for the host's in-flight requests to finish, so one request timing out blocked dispatch of every queued request, to any host, until the slowest in-flight request to that host completed. The client is now removed from the pool immediately and closed in a separate task once its requests finish.
+
 ## 1.6.1
 
 ### Fixed