patient_http 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b3bb6335d47143a8f6e8123be222265651c3e3cee1c8a0084f3aae02b6f6444
-  data.tar.gz: 9c0a549ff00b9861073fd9853d82a6736c26bf34fca3ac689acf14008968abd5
+  metadata.gz: 2c173592c54e9ac9730cbfeca9b81d61a5af9df06839b8abdc2bb2dcb54b228f
+  data.tar.gz: 171d9176271d166855129c6c13bb0e234345f3368dbae835a4221e8b28a9deb8
 SHA512:
-  metadata.gz: c13e5e339088c84e7977ba82c6484780a890076af083d2dbf2754bf1ff0eb05d6a28d585be4d56b13bf5a052d00b643b2c8d44b90a5766fab9cd426c03375830
-  data.tar.gz: cdf38eeac4823f3cb922001541c3d9425c993cc4ce075ca80ff427d2a79a6d38928999518cd690181aaa8d4064554ea087666a54bb426a829809135dc0c4bf35
+  metadata.gz: '0811e744dadbceb89141f2603de7113fec36ab389967fd941fa9202bba3d6c4924e169b594d17b6f03dba0437bb04b5ca5f895515174d2717a316027428a4f85'
+  data.tar.gz: 3719152b73fd5994766a26dba869f4f278c2b8362fb79a30b543d123abfcfd996db0a5a2e57daf136f2812674c0644e1ad1671c50c2553a615724d7239312048

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
@@ -296,8 +297,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
 
@@ -327,7 +328,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,35 @@ 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.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