patient_http-sidekiq 1.4.0 → 1.5.0

data/README.md

@@ -6,13 +6,13 @@
 
 *Built for APIs that like to think.*
 
-This gem provides a mechanism to offload HTTP requests to a dedicated async I/O processor running in your Sidekiq process using the [patient_http gem](https://github.com/bdurand/patient_http). Worker threads are freed immediately while HTTP requests are in flight so that they can do other work instead of waiting for HTTP responses.
+This gem runs HTTP requests from Sidekiq on a dedicated async I/O processor in your Sidekiq process, using the [patient_http gem](https://github.com/bdurand/patient_http). Worker threads don't wait for HTTP responses, so they're free to run other jobs while requests are in flight.
 
 ## Motivation
 
-Sidekiq is designed with the assumption that jobs are short-lived and complete quickly. Long-running HTTP requests block worker threads from processing other jobs, leading to increased latency and reduced throughput. This is particularly problematic when calling LLM or AI APIs, where requests can take many seconds to complete.
+Sidekiq works best when jobs finish quickly. A long HTTP request blocks a worker thread, so other jobs wait, latency rises, and throughput drops. LLM and other AI APIs make this worse, because a request can take many seconds to finish.
 
-**The Problem:**
+Without this gem, each slow request holds a worker thread for its full duration:
 
 ```
 ┌────────────────────────────────────────────────────────────────────────┐
@@ -26,7 +26,7 @@ Sidekiq is designed with the assumption that jobs are short-lived and complete q
 └────────────────────────────────────────────────────────────────────────┘
 ```
 
-**The Solution:**
+With this gem, a worker thread only hands off the request, and the async processor waits for the response:
 
 ```
 ┌────────────────────────────────────────────────────────────────────────┐
@@ -42,21 +42,33 @@ Sidekiq is designed with the assumption that jobs are short-lived and complete q
 └────────────────────────────────────────────────────────────────────────┘
 ```
 
-The async processor runs in a dedicated thread within your Sidekiq process, using Ruby's Fiber-based concurrency to handle hundreds of concurrent HTTP requests without blocking. When an HTTP request completes, a callback service is invoked for processing.
+The async processor runs in a dedicated thread in your Sidekiq process. It uses Ruby's fiber-based concurrency to run hundreds of HTTP requests at the same time without blocking. When a request finishes, the gem calls your callback service.
 
-## Quick Start
+## Quick start
 
-### 1. Configure The Gem
+### 1. Install the gem
 
-Configure the gem in an initializer (see the Configuration section below for all available options):
+Add the gem to your Gemfile:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
-  config.max_connections = 256
-end
+gem "patient_http-sidekiq"
+```
+
+Then install it:
+
+```bash
+bundle install
 ```
 
-### 2. Create a Callback Service
+No other setup is required. When the gem loads, it registers the request handler and connects the processor to Sidekiq's startup and shutdown. You don't need to write an initializer or call a setup method. Every option has a working default. To change the defaults, see [Configuration](#configuration).
+
+To create a commented initializer to start from, run the generator:
+
+```bash
+bin/rails generate patient_http:sidekiq:install
+```
+
+### 2. Create a callback service
 
 Define a callback service class with `on_complete` and `on_error` methods:
 
@@ -79,9 +91,9 @@ class FetchDataCallback
 end
 ```
 
-### 3. Make HTTP Requests
+### 3. Make HTTP requests
 
-Make HTTP requests from anywhere in your code using `PatientHttp`:
+Make HTTP requests from anywhere in your code with the `PatientHttp` module:
 
 ```ruby
 PatientHttp.get(
@@ -92,24 +104,80 @@ PatientHttp.get(
 )
 ```
 
-### 4. That's It!
-
-The request will be enqueued as a Sidekiq job and passed to a [PatientHttp](https://github.com/bdurand/patient_http) processor to execute asynchronously. When the HTTP request completes, your callback's `on_complete` method is executed in another Sidekiq job.
+The gem enqueues the request as a Sidekiq job, which runs the request on a [PatientHttp](https://github.com/bdurand/patient_http) processor. If a processor runs in the current process, the request goes straight to it instead; see [Direct execution](#direct-execution). When the request finishes, another Sidekiq job calls your callback's `on_complete` method. If the request fails, the job calls `on_error` instead.
 
-If an error occurs during the request, the `on_error` method is called instead.
+The `response.callback_args` and `error.callback_args` methods return the arguments that you passed with the `callback_args` option.
 
-You can also call `PatientHttp.post`, `PatientHttp.put`, `PatientHttp.patch`, and `PatientHttp.delete` for other HTTP methods. See the [patient_http docs](https://github.com/bdurand/patient_http) for the full API reference.
-
-The `response.callback_args` and `error.callback_args` provide access to the arguments you passed via the `callback_args` option.
+For other HTTP methods, use `PatientHttp.post`, `PatientHttp.put`, `PatientHttp.patch`, `PatientHttp.delete`, `PatientHttp.head`, and `PatientHttp.query`. For the full API reference, see the [patient_http documentation](https://github.com/bdurand/patient_http).
 
 > [!IMPORTANT]
-> Do not re-raise errors in the `on_error` callback as a means to retry the request. That will just retry the error callback job. If you want to retry the original request, you can enqueue a new request from within `on_error`. Be careful with this approach, though, as it can lead to infinite retry loops if the error condition is not resolved.
+> Don't raise an error in `on_error` to retry the request. Sidekiq retries the callback job, not the request. To retry the request, make a new request from `on_error`. Make sure that the retries stop if the error persists, or they can loop forever.
 >
-> Also note that the error callback is only called when an exception occurs during the HTTP request (timeout, connection failure, etc). HTTP error status codes (4xx, 5xx) do not trigger the error callback by default. Instead, they are treated as completed requests and passed to the `on_complete` callback. See the "Handling HTTP Error Responses" section below for how to treat HTTP errors as exceptions.
+> The `on_error` callback runs only when the request raises an exception, such as a timeout or a connection failure. By default, HTTP error status codes (4xx and 5xx) don't call `on_error`. The gem treats these responses as completed requests and passes them to `on_complete`. To treat HTTP errors as exceptions, see [Handle HTTP error responses](#handle-http-error-responses).
+
+## Usage
+
+### Make requests
+
+Use the `PatientHttp` module methods to make requests. There's a method for each HTTP method:
+
+```ruby
+# GET request
+PatientHttp.get("https://api.example.com/users/123",
+  callback: MyCallback, callback_args: {user_id: 123})
+
+# POST request with a JSON body
+PatientHttp.post("https://api.example.com/users",
+  json: {name: "John", email: "john@example.com"},
+  callback: MyCallback)
+
+# PUT request
+PatientHttp.put("https://api.example.com/users/123",
+  json: {name: "Updated Name"},
+  callback: MyCallback)
+
+# PATCH request
+PatientHttp.patch("https://api.example.com/users/123",
+  json: {status: "active"},
+  callback: MyCallback)
+
+# DELETE request
+PatientHttp.delete("https://api.example.com/users/123",
+  callback: MyCallback)
+```
+
+The methods take these options:
 
-### Handling HTTP Error Responses
+| Option | Description |
+| --- | --- |
+| `callback:` | Required. The callback service class, or its name. |
+| `callback_args:` | A Hash of arguments that the callback reads from the response or error. See [Callback arguments](#callback-arguments). |
+| `headers:` | The request headers. |
+| `body:` | The request body. GET, HEAD, and DELETE requests can't have a body. |
+| `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. |
+| `raise_error_responses:` | Whether to treat non-2xx responses as errors. See [Handle HTTP error responses](#handle-http-error-responses). |
+| `processor:` | The name of the processor that runs the request. See [Named processors](#named-processors). |
 
-By default, HTTP error status codes (4xx, 5xx) are treated as successful responses and passed to the `on_complete` callback. You can check the status using `response.success?`, `response.client_error?`, or `response.server_error?`:
+For all options, see the [patient_http documentation](https://github.com/bdurand/patient_http#make-requests).
+
+For more control, build a `PatientHttp::Request` object and pass it to `PatientHttp.execute`:
+
+```ruby
+request = PatientHttp::Request.new(:get, "https://api.example.com/users/123",
+  headers: {"Authorization" => "Bearer token"},
+  params: {include: "profile"},
+  timeout: 30
+)
+PatientHttp.execute(request: request, callback: MyCallback, callback_args: {user_id: 123})
+```
+
+For the full `Request` and `Response` API reference, see the [patient_http documentation](https://github.com/bdurand/patient_http).
+
+### Handle HTTP error responses
+
+By default, the gem treats HTTP error status codes (4xx and 5xx) as completed requests and passes them to `on_complete`. To check the status, use `response.success?`, `response.client_error?`, or `response.server_error?`:
 
 ```ruby
 class ApiCallback
@@ -134,22 +202,22 @@ PatientHttp.get(
 )
 ```
 
-If you prefer to treat HTTP errors as exceptions, you can use the `raise_error_responses` option. When enabled, non-2xx responses will call the `on_error` callback with an `HttpError` instead:
+To treat HTTP errors as exceptions, set the `raise_error_responses` option. With this option, a non-2xx response calls `on_error` with a `PatientHttp::HttpError` instead:
 
 ```ruby
 class ApiCallback
   def on_complete(response)
-    # Only called for 2xx responses
+    # Called only for 2xx responses.
     process_data(response.json)
   end
 
   def on_error(error)
-    # Called for exceptions AND HTTP errors when using raise_error_responses
+    # Called for exceptions, and for HTTP errors when raise_error_responses is set.
     if error.is_a?(PatientHttp::HttpError)
-      # Access the response via error.response
+      # The response is available from error.response.
       Rails.logger.error("HTTP #{error.status} from #{error.url}: #{error.response.body}")
     else
-      # Regular request errors (timeout, connection, etc)
+      # Request errors, such as timeouts and connection failures.
       Rails.logger.error("Request failed: #{error.message}")
     end
   end
@@ -162,7 +230,7 @@ PatientHttp.get(
 )
 ```
 
-The `HttpError` provides convenient access to the response:
+An `HttpError` gives you access to the request and the response:
 
 ```ruby
 def on_error(error)
@@ -172,69 +240,14 @@ def on_error(error)
     puts error.http_method         # HTTP method
     puts error.response.body       # Response body
     puts error.response.headers    # Response headers
-    puts error.response.json       # Parse JSON response (if applicable)
+    puts error.response.json       # Response body parsed as JSON
   end
 end
 ```
 
-## Usage Patterns
-
-### Making Requests
+### Set Sidekiq options at runtime
 
-The primary interface for making requests is through the `PatientHttp` module, which provides convenience methods for all HTTP verbs:
-
-```ruby
-# GET request
-PatientHttp.get("https://api.example.com/users/123",
-  callback: MyCallback, callback_args: {user_id: 123})
-
-# POST request with JSON body
-PatientHttp.post("https://api.example.com/users",
-  json: {name: "John", email: "john@example.com"},
-  callback: MyCallback)
-
-# PUT request
-PatientHttp.put("https://api.example.com/users/123",
-  json: {name: "Updated Name"},
-  callback: MyCallback)
-
-# PATCH request
-PatientHttp.patch("https://api.example.com/users/123",
-  json: {status: "active"},
-  callback: MyCallback)
-
-# DELETE request
-PatientHttp.delete("https://api.example.com/users/123",
-  callback: MyCallback)
-```
-
-Available request options:
-
-- `callback:` - (required) Callback service class or class name
-- `callback_args:` - Hash of arguments passed to callback via response/error
-- `headers:` - Request headers
-- `body:` - Request body (for POST/PUT/PATCH)
-- `json:` - Object to serialize as JSON body (cannot use with body)
-- `params:` - Query parameters to append to URL
-- `timeout:` - Request timeout in seconds
-- `raise_error_responses:` - Treat non-2xx responses as errors
-
-You can also build a `PatientHttp::Request` object and pass it to `PatientHttp.execute` for more control:
-
-```ruby
-request = PatientHttp::Request.new(:get, "https://api.example.com/users/123",
-  headers: {"Authorization" => "Bearer token"},
-  params: {include: "profile"},
-  timeout: 30
-)
-PatientHttp.execute(request: request, callback: MyCallback, callback_args: {user_id: 123})
-```
-
-See the [patient_http docs](https://github.com/bdurand/patient_http) for the full `Request` and `Response` API reference.
-
-### Setting Sidekiq Options At Runtime
-
-You can set Sidekiq job options for individual requests with `PatientHttp::Sidekiq.with_sidekiq_options`. The options apply to all requests enqueued within the block. Use this, for example, to route urgent requests to a higher priority queue:
+To set Sidekiq job options for specific requests, use `PatientHttp::Sidekiq.with_sidekiq_options`. The options apply to all requests made in the block. For example, to send urgent requests to a higher priority queue:
 
 ```ruby
 PatientHttp::Sidekiq.with_sidekiq_options(queue: "high_priority") do
@@ -242,60 +255,69 @@ PatientHttp::Sidekiq.with_sidekiq_options(queue: "high_priority") do
 end
 ```
 
-The options are applied with Sidekiq's `set` method, so any Sidekiq job option (`queue`, `retry`, etc.) is allowed. Notes on the behavior:
+Sidekiq applies the options with its `set` method, so any Sidekiq job option, such as `queue` or `retry`, is allowed. The options work as follows:
+
+- If the options include a `queue`, the callback job that calls `on_complete` or `on_error` uses that queue as well. As a result, the request keeps the same priority from start to finish.
+- Nested blocks merge their options, and the innermost values take precedence. When a block exits, the previous options are restored, even if the block raises an error.
+- Requests made in the block always go through the Sidekiq queue, even when the processor runs in the current process, so that Sidekiq applies the options. For more information, see [Direct execution](#direct-execution).
 
-- If the options include a `queue`, the callback job that invokes your `on_complete`/`on_error` methods is enqueued on that queue as well, so the whole request keeps one priority end to end.
-- Nested blocks merge their options, and the innermost values take precedence. The previous options are restored when the block exits, even if the block raises an error.
-- Requests made in the block always go through the Sidekiq queue, even when the processor runs in the current process, so that Sidekiq applies the options (see Direct Execution below).
+### Direct execution
 
-### Direct Execution
+When a request is made in a process where the processor is running, usually a Sidekiq server process, the request skips the Sidekiq queue and goes straight to the processor. This saves a round trip through Redis. Otherwise, the request behaves the same as an enqueued request:
 
-When a request is made in a process where the processor is running (normally a Sidekiq server process), the request skips the Sidekiq queue and goes straight to the processor. This removes a round trip through Redis. The behavior is the same as the enqueued path:
+- The request can always be re-enqueued. The gem adds the request to the crash-recovery registry before the call returns. If the processor shuts down or the process crashes, the request is enqueued as a `RequestWorker` job. If the gem can't write the registry entry, for example because Redis is unavailable, the call raises an error, as a failed enqueue does.
+- If the processor is at capacity or stops accepting requests, the request is enqueued through Sidekiq instead, and the normal Sidekiq retry behavior applies.
 
-- The request can always be re-enqueued. It is registered in the crash-recovery registry before the call returns, so if the processor shuts down or the process crashes, the request is enqueued as a normal `RequestWorker` job. If the registry entry cannot be written (for example, Redis is unavailable), the call raises, the same as a failed enqueue.
-- If the processor is at max capacity or stops accepting requests, the request is enqueued through Sidekiq instead, and the normal Sidekiq retry behavior applies from there.
-- Requests made in a `with_sidekiq_options` block always go through the Sidekiq queue, so that Sidekiq applies the options (queue routing, scheduling, retry). Use this to route specific requests to a dedicated Sidekiq process.
-- Options set with `config.sidekiq_options` (including a `queue`) do not apply to direct-executed requests, because no Sidekiq job is created. If every request must go through the configured queue (for example, to run all requests on a dedicated Sidekiq process), set `config.direct_execution = false`.
-- Direct execution is disabled when `Sidekiq::Testing` is enabled, so tests can observe enqueued jobs as usual.
+Direct execution has these limits:
 
-You can turn this off with `config.direct_execution = false`. Do this if you route all requests to a dedicated queue with `config.sidekiq_options`, if you need Sidekiq client or server middleware to run for every request, or if you want every request to be visible as an enqueued job in Sidekiq metrics and the Web UI.
+- Requests made in a `with_sidekiq_options` block always go through the Sidekiq queue, so that Sidekiq applies the options, such as queue routing, scheduling, and retries. Use a block to send specific requests to a dedicated Sidekiq process.
+- Options set with `config.sidekiq_options`, including `queue`, don't apply to direct requests, because no Sidekiq job is created.
+- Direct execution is off when `Sidekiq::Testing` is enabled, so that tests can check enqueued jobs as usual.
 
-### Named Processors
+To turn off direct execution, set `config.direct_execution = false`. Turn it off in any of these cases:
 
-By default all requests share one processor and one `max_connections` cap. When one process serves workload classes with very different profiles (for example, large slow API calls and small fast webhook deliveries), a burst of one class can consume all of the capacity the other class needs. Named processor profiles isolate them:
+- You send all requests to a dedicated queue with `config.sidekiq_options`, for example to run them on a dedicated Sidekiq process.
+- Sidekiq client or server middleware must run for every request.
+- Every request must appear as an enqueued job in Sidekiq metrics and the Web UI.
+
+### Named processors
+
+By default, all requests share one processor and one `max_connections` limit. If one process runs workloads with very different profiles, such as slow LLM API calls and fast webhook deliveries, a burst of one workload can use all the capacity that the other needs. Named processor profiles keep the workloads separate:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.processor(:llm, max_connections: 200, request_timeout: 120)
   config.processor(:webhooks, max_connections: 64, request_timeout: 10)
 end
 ```
 
-Each profile runs as an independent processor in the process, with its own capacity, timeouts, and threads. Profile options override the top-level configuration; anything not overridden (secrets, preprocessors, payload stores, encryption, logger) is shared. The `:default` processor always exists; declare `config.processor(:default, ...)` to override its options.
+Each profile runs as an independent processor in the process, with its own capacity, timeouts, and threads. Profile options override the top-level configuration. The profiles share every option that they don't override, such as secrets, preprocessors, payload stores, encryption, and the logger. Declare a profile with no options, such as `config.processor(:bulk)`, to run a separate processor that uses the top-level options. The `:default` processor always exists. To override its options, declare `config.processor(:default, ...)`.
 
-Route a request to a processor in any of these ways:
+To send a request to a processor, use any of these methods:
 
 ```ruby
-# Explicit option on execute
-PatientHttp::Sidekiq.execute(request, callback: MyCallback, processor: :llm)
+# An option on the request method.
+PatientHttp.get(url, callback: MyCallback, processor: :llm)
 
-# On the request itself (survives serialization, retries, and crash recovery)
+# A request object. The processor is kept through serialization, retries, and crash recovery.
 request = PatientHttp::Request.new(:get, url, processor: :llm)
 
-# Through a request template
+# A request template.
 template = PatientHttp::RequestTemplate.new(base_url: url, processor: :llm)
 
-# Scoped for a block
+# A block.
 PatientHttp::Sidekiq.with_sidekiq_options("processor" => "webhooks") do
-  PatientHttp::Sidekiq.execute(request, callback: MyCallback)
+  PatientHttp.get(url, callback: MyCallback)
 end
 ```
 
-The processor name is serialized into the job arguments, so Sidekiq retries and crash recovery keep their routing. A job that names a processor that is not configured in the executing process raises `PatientHttp::UnknownProcessorError` and goes through the normal Sidekiq retry mechanism; this makes new profile names safe to roll out gradually. Jobs enqueued by older gem versions run on the `:default` processor.
+A request that names a processor that isn't declared in the process making the request raises `PatientHttp::UnknownProcessorError`, so a misspelled name fails where the request is made. Declare processors in every process that makes requests, not only in the Sidekiq server, for example by declaring them outside a `Sidekiq.configure_server` block.
 
-### Using Request Templates
+The processor name is saved in the job arguments, so Sidekiq retries and crash recovery send the request to the same processor. If a job names a processor that isn't configured in the process that runs it, the job raises `PatientHttp::UnknownProcessorError`, and Sidekiq retries it. As a result, you can roll out a new profile name gradually. Jobs enqueued by earlier versions of the gem run on the `:default` processor.
 
-For repeated requests to the same API, use `PatientHttp::RequestTemplate` to share configuration:
+### Use request templates
+
+To share settings across requests to the same API, use `PatientHttp::RequestTemplate`:
 
 ```ruby
 class ApiService
@@ -327,11 +349,11 @@ class ApiService
 end
 ```
 
-### Using the RequestHelper Module
+If the template doesn't set a `timeout`, the configured `request_timeout` applies.
 
-For classes that make many async HTTP requests, you can include `PatientHttp::RequestHelper` to get convenient instance methods like `async_get`, `async_post`, `async_put`, `async_patch`, and `async_delete`. You can also define a request template at the class level using the `request_template` class method to set shared options like `base_url`, `headers`, and `timeout`.
+### Use the RequestHelper module
 
-When using this gem, the request handler is automatically registered when the processor starts and unregistered when it stops — no manual setup is required.
+For a class that makes many requests, include `PatientHttp::RequestHelper`. The module adds the `async_get`, `async_head`, `async_post`, `async_put`, `async_patch`, `async_delete`, `async_query`, and `async_request` instance methods. To set shared options such as `base_url`, `headers`, and `timeout`, use the `request_template` class method:
 
 ```ruby
 class NotificationService
@@ -358,18 +380,18 @@ class NotificationService
 end
 ```
 
-The `async_*` methods accept the same options as `PatientHttp.get`, `PatientHttp.post`, etc. Paths are resolved relative to the `base_url` defined in the request template.
+The `async_*` methods take the same options as `PatientHttp.get`, `PatientHttp.post`, and the other module methods. Paths are relative to the template's `base_url`.
 
-See the [patient_http gem](https://github.com/bdurand/patient_http) for the full `RequestHelper` documentation.
+For the full `RequestHelper` documentation, see the [patient_http documentation](https://github.com/bdurand/patient_http#use-the-requesthelper-module).
 
-### Callback Arguments
+### Callback arguments
 
-Pass custom data to your callbacks using the `callback_args` option:
+To pass data to your callbacks, use the `callback_args` option:
 
 ```ruby
 class FetchDataCallback
   def on_complete(response)
-    # Access callback_args using symbol or string keys
+    # Read callback_args with symbol or string keys.
     user_id = response.callback_args[:user_id]
     request_timestamp = response.callback_args[:request_timestamp]
 
@@ -389,7 +411,7 @@ class FetchDataCallback
   end
 end
 
-# Pass data via callback_args option
+# Pass data with the callback_args option.
 PatientHttp.get(
   "https://api.example.com/users/#{user_id}",
   callback: FetchDataCallback,
@@ -400,43 +422,43 @@ PatientHttp.get(
 )
 ```
 
-**Important details about callback_args:**
+The `callback_args` value follows these rules:
 
-- Must be a Hash (or respond to `to_h`) containing only JSON-native types: `nil`, `true`, `false`, `String`, `Integer`, `Float`, `Array`, or `Hash`
-- Hash keys will be converted to strings for serialization
-- Nested hashes and hashes in arrays also have their keys converted to strings
-- You can access callback_args using either symbol or string keys: `callback_args[:user_id]` or `callback_args["user_id"]`
+- It must be a Hash, or respond to `to_h`, and contain only JSON-native types: `nil`, `true`, `false`, `String`, `Integer`, `Float`, `Array`, and `Hash`.
+- Hash keys are converted to strings, including the keys of nested hashes and of hashes in arrays.
+- You can read the arguments with symbol or string keys: `callback_args[:user_id]` or `callback_args["user_id"]`.
+- Reading a key that isn't set raises a `KeyError`. To get a default value instead, use `callback_args.fetch(:user_id, nil)`.
 
-### Sensitive Data Handling
+### Protect sensitive data
 
-Requests and responses from asynchronous HTTP requests will be pushed to Redis in order to call the completion job. This can raise security concerns if they contain sensitive data since the data will be stored in plain text.
+The gem stores requests and responses in Redis so that it can run the callback job. If they contain sensitive data, that data is stored in plain text.
 
-You can configure encryption so that all request and response data is automatically encrypted before being stored in Sidekiq and decrypted when retrieved.
+To protect the data, configure encryption. The gem then encrypts all request and response data before it stores the data in Redis, and decrypts the data when it reads it.
 
-#### Using an encryption key
+#### Use an encryption key
 
-The simplest option is `encryption_key=`, which sets up [ActiveSupport::MessageEncryptor](https://api.rubyonrails.org/classes/ActiveSupport/MessageEncryptor.html) using AES-256-GCM:
+The simplest option is `encryption_key=`. It uses [ActiveSupport::MessageEncryptor](https://api.rubyonrails.org/classes/ActiveSupport/MessageEncryptor.html) with AES-256-GCM:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.encryption_key = ENV["PATIENT_HTTP_ENCRYPTION_KEY"]
 end
 ```
 
-Pass an array to support key rotation (first key encrypts, all keys attempt decryption):
+To rotate keys, pass an array. The first key encrypts data, and all keys are tried for decryption:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.encryption_key = [ENV["PATIENT_HTTP_ENCRYPTION_KEY"], ENV["PATIENT_HTTP_OLD_KEY"]]
 end
 ```
 
-#### Using custom callables
+#### Use custom callables
 
-For custom encryption libraries, provide callables that accept and return raw bytes (String):
+To use another encryption library, provide callables that take and return raw bytes as a String:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.encryption { |bytes| MyEncryption.encrypt(bytes) }
   config.decryption { |bytes| MyEncryption.decrypt(bytes) }
 end
@@ -445,152 +467,166 @@ end
 You can also pass any object that responds to `call`:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.encryption(->(bytes) { MyEncryption.encrypt(bytes) })
   config.decryption(->(bytes) { MyEncryption.decrypt(bytes) })
 end
 ```
 
+To keep API tokens out of the queue entirely, use secrets instead. For secrets, request preprocessors, and payload stores for large payloads, see the [patient_http documentation](https://github.com/bdurand/patient_http#sensitive-and-large-payloads).
+
 ## Configuration
 
-The gem can be configured globally in an initializer:
+All configuration is optional. To set options, call `PatientHttp.configure` in an initializer. The method yields this gem's configuration. `PatientHttp::Sidekiq.configure` does the same thing, but `PatientHttp.configure` keeps the initializer free of references to the job system.
+
+Every call yields the same configuration object, so options accumulate. Several initializers can each set options without overwriting one another.
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
-  # Maximum concurrent HTTP requests (default: 256)
+PatientHttp.configure do |config|
+  # Maximum concurrent HTTP requests (default: 256).
   config.max_connections = 256
 
-  # Default timeout for HTTP requests in seconds (default: 60)
+  # Default timeout for HTTP requests in seconds (default: 60).
   config.request_timeout = 60
 
-  # Maximum number of host clients to pool (default: 100)
+  # Maximum number of host clients to pool (default: 100).
   config.connection_pool_size = 100
 
-  # Connection timeout in seconds (default: nil, uses request_timeout)
+  # Timeout in seconds to open a connection, including the TCP connect and the
+  # TLS handshake (default: nil, no limit). It doesn't limit the wait for a
+  # response; request_timeout does that.
   config.connection_timeout = 10
 
-  # Number of retries for failed requests (default: 3)
+  # TCP keepalive for pooled connections (default: nil, the kernel sends no
+  # probes). A number sets the idle seconds before the first probe. A Hash also
+  # sets the interval and the probe count, for example
+  # {idle: 30, interval: 10, count: 3}. The Hash must contain :idle. The
+  # :interval default is 10 seconds, and the :count default is 3 probes.
+  config.tcp_keepalive = 30
+
+  # Seconds that sent data can stay unacknowledged before the kernel closes the
+  # connection (default: nil, the kernel default applies). Sets
+  # TCP_USER_TIMEOUT, which is available only on Linux.
+  config.tcp_user_timeout = 30
+
+  # Number of retries for failed requests (default: 3).
   config.retries = 3
 
-  # HTTP/HTTPS proxy URL (default: nil)
-  # Supports authentication: "http://user:pass@proxy.example.com:8080"
+  # HTTP or HTTPS proxy URL (default: nil). Supports authentication, for
+  # example "http://user:pass@proxy.example.com:8080".
   config.proxy_url = "http://proxy.example.com:8080"
 
-  # Default User-Agent header for all requests (default: "PatientHttp")
+  # Default User-Agent header for all requests (default: "PatientHttp").
   config.user_agent = "MyApp/1.0"
 
-  # Timeout for graceful shutdown in seconds (default: the Sidekiq
-  # shutdown timeout minus 2 seconds). This should be less than Sidekiq's
-  # shutdown timeout.
+  # Timeout for graceful shutdown in seconds (default: the Sidekiq shutdown
+  # timeout minus 2 seconds). Must be less than Sidekiq's shutdown timeout.
   config.shutdown_timeout = 23
 
-  # Maximum response body size in bytes (default: 1MB)
-  # Responses larger than this will trigger ResponseTooLargeError
+  # Maximum response body size in bytes (default: 1MB). Larger responses raise
+  # ResponseTooLargeError.
   config.max_response_size = 1024 * 1024
 
-  # Maximum number of redirects to follow (default: 5, 0 disables)
+  # Maximum number of redirects to follow (default: 5; 0 turns off redirects).
   config.max_redirects = 5
 
-  # Whether to raise HttpError for non-2xx responses by default (default: false)
+  # Whether to raise HttpError for non-2xx responses by default (default: false).
   config.raise_error_responses = false
 
-  # Heartbeat interval for crash recovery in seconds (default: 60)
+  # Heartbeat interval for crash recovery in seconds (default: 60).
   config.heartbeat_interval = 60
 
-  # Orphan detection threshold in seconds (default: 300)
-  # Requests older than this without a heartbeat will be re-enqueued
+  # Seconds without a heartbeat after which a request is re-enqueued
+  # (default: 300).
   config.orphan_threshold = 300
 
-  # Size threshold in bytes for external payload storage (default: 64KB)
-  # Payloads larger than this will be stored externally when a payload
-  # store is configured.
+  # Size in bytes above which payloads are stored externally when a payload
+  # store is configured (default: 64KB).
   config.payload_store_threshold = 64 * 1024
 
-  # Sidekiq options for RequestWorker and CallbackWorker
-  # (use PatientHttp::Sidekiq.with_sidekiq_options to override per request)
+  # Sidekiq options for RequestWorker and CallbackWorker (default: nil). To
+  # override them for specific requests, use
+  # PatientHttp::Sidekiq.with_sidekiq_options.
   config.sidekiq_options = {queue: "patient_http", retry: 5}
 
   # Whether the URL, HTTP method, and processor of each in-flight request are
-  # recorded so the Web UI can list them (default: true).
+  # recorded so that the Web UI can list them (default: true).
   config.inflight_details = true
 
-  # Sanitizer applied to a URL before it is recorded. Without one, the user
-  # name, password, query string, and fragment are removed.
+  # Sanitizer that runs on a URL before it's recorded (default: removes the
+  # user name, password, query string, and fragment).
   config.inflight_url_sanitizer { |url| url.sub(%r{/users/\d+}, "/users/:id") }
 
   # Whether requests made in a process with a running processor skip the
-  # Sidekiq queue and go straight to the processor (default: true).
-  # Sidekiq options, including a queue, do not apply to direct-executed
-  # requests; set this to false to route every request through the queue.
+  # Sidekiq queue and go straight to the processor (default: true). Sidekiq
+  # options, including a queue, don't apply to these requests. Set this to
+  # false to send every request through the queue.
   config.direct_execution = true
 
-  # Size of the gem's dedicated Redis pool used by its own threads
-  # (default: nil, sized automatically from completion_threads with a
-  # floor of 10)
+  # Size of the gem's dedicated Redis pool, which the gem's own threads use
+  # (default: nil, based on completion_threads with a minimum of 10).
   config.redis_pool_size = nil
 
-  # Checkout timeout in seconds for the dedicated Redis pool (default: 5)
+  # Checkout timeout in seconds for the dedicated Redis pool (default: 5).
   config.redis_pool_timeout = 5
 
-  # Seconds between flushes of locally aggregated stats to Redis
-  # (default: 5; 0 writes every event synchronously)
+  # Seconds between flushes of local stats to Redis (default: 5; 0 writes every
+  # event immediately).
   config.stats_flush_interval = 5
 
-  # Number of threads that decode responses and deliver results (default: 2)
+  # Number of threads that decode responses and deliver results (default: 2).
   config.completion_threads = 2
 
-  # Maximum connections per host (default: nil, unlimited)
+  # Maximum connections to each host (default: nil, no limit).
   config.max_connections_per_host = 32
 
-  # Named processor profiles for workload isolation (see Named Processors)
+  # Named processor profiles for workload isolation. See Named processors.
   config.processor(:llm, max_connections: 200, request_timeout: 120)
   config.processor(:webhooks, max_connections: 64, request_timeout: 10)
 
-  # Handler called when a callback job exhausts all Sidekiq retries
+  # Handler that runs when a callback job uses up all of its Sidekiq retries.
   config.on_retries_exhausted { |error| MyAlertService.notify(error) }
 
-  # Custom logger (defaults to Sidekiq.logger)
+  # Logger (default: Sidekiq.logger).
   config.logger = Rails.logger
 
-  # Encryption for sensitive data (see Sensitive Data Handling)
+  # Encryption for sensitive data. See Protect sensitive data.
   config.encryption_key = ENV["PATIENT_HTTP_ENCRYPTION_KEY"]
 end
 ```
 
-See the [Configuration](lib/patient_http/sidekiq/configuration.rb) class for all available options.
+For all options, see the [Configuration](lib/patient_http/sidekiq/configuration.rb) class. For the HTTP options that this gem inherits, see the [patient_http documentation](https://github.com/bdurand/patient_http#configuration).
 
-> [!NOTE]
-> You **must** call `PatientHttp::Sidekiq.configure` or `PatientHttp::Sidekiq.register_handler` in order to register the request handler and start processing requests. If you do not call either method, you will get errors making HTTP requests with `PatientHttp.execute`.
+### Tuning tips
 
-### Tuning Tips
-
-- `max_connections`: Adjust this based on your system's resources. Each connection uses memory and file descriptors. A tuned system with sufficient resources can handle thousands of concurrent connections.
-- `request_timeout`: Set this based on the expected response times of the APIs you are calling. AI APIs might sometimes take minutes to respond as they generate content.
-- `connection_pool_size`: Controls how many connections to different hosts are kept alive. Increase for applications calling many different API endpoints.
-- `connection_timeout`: Set this if you need to fail fast on connection establishment. Useful for detecting network issues quickly.
-- `retries`: Number of times to retry a failed request before calling the error callback.
-- `max_response_size`: Set this to limit the maximum size of HTTP responses. This helps prevent excessive memory usage from unexpectedly large responses. Responses need to be serialized to Redis as Sidekiq jobs and very large responses may cause performance issues in Redis. If a response body is text content, it will be compressed to save space in Redis. However, binary content needs to be Base64 encoded which increases size by ~33%.
-- `max_connections_per_host`: Bounds sockets per host. Verify the process file descriptor limit covers `max_connections` plus pooled idle host connections plus the application's own connections; raise the limit if needed.
-- `shutdown_timeout`: Must be below the process supervisor's termination window so the drain finishes before a hard kill. The default derives it from Sidekiq's own shutdown timeout; check any additional supervisor (container orchestrator, init system) stop timeout as well.
-- `completion_threads`: Increase when result callbacks do heavier work (serialization, encryption) and completions back up behind them.
-- `redis_pool_size`: The automatic size covers the gem's own threads. Increase it when a high request rate makes registration or completion pushes wait on checkouts.
+- `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.
+- `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.
+- `connection_pool_size`: Sets the maximum number of hosts whose connections are kept open. Increase it if your application calls many different hosts.
+- `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.
+- `retries`: Sets the number of times to retry a failed request before the gem calls the error callback.
+- `max_response_size`: Limits the size of HTTP responses to prevent high memory use from unexpectedly large responses. Responses are serialized in Sidekiq job arguments, and very large responses can slow Redis down. Text response bodies are compressed to save space. Binary bodies are Base64 encoded, which increases their size by about 33%.
+- `payload_store_threshold`: Lower this if large payloads slow your queue down. Higher values avoid extra reads and writes to the payload store.
+- `max_connections_per_host`: Limits the sockets open to each host. Make sure that the process file descriptor limit covers `max_connections`, plus idle pooled connections, plus the application's own connections. Raise the limit if needed.
+- `shutdown_timeout`: Must be less than the process supervisor's stop timeout, so that in-flight requests finish before a hard kill. The default is based on Sidekiq's shutdown timeout. If a container orchestrator or init system also stops the process, check its stop timeout as well.
+- `completion_threads`: Increase this when result delivery does heavy work, such as serialization or encryption, and finished requests wait for a thread.
+- `redis_pool_size`: The automatic size covers the gem's own threads. Increase it if a high request rate makes request registration or result delivery wait for a connection.
+- `heartbeat_interval` and `orphan_threshold`: For high-volume workloads, set `heartbeat_interval` as high as your recovery objective allows, while you keep it less than `orphan_threshold`. Fewer heartbeats mean fewer writes to Redis.
 
 > [!WARNING]
-> Do not install `hiredis-client` in processes that run the async processor. The hiredis driver performs blocking I/O that does not yield to the fiber scheduler, so a Redis call made on the reactor thread (for example, from a custom processor observer) stalls every in-flight HTTP request. The gem logs a warning at startup when it detects the hiredis driver.
+> Don't install `hiredis-client` in processes that run the async processor. The hiredis driver does blocking I/O that doesn't yield to the fiber scheduler. A Redis call on the reactor thread, for example from a custom processor observer, stalls every in-flight HTTP request. The gem logs a warning at startup if it detects the hiredis driver.
 
 > [!IMPORTANT]
+> When the processor reaches `max_connections`, a new request raises an error in its Sidekiq job, and Sidekiq retries the job.
 >
-> One difference between using this gem and making synchronous HTTP requests from a Sidekiq job is that if `max_connections` is reached due to slow asynchronous requests, new requests will trigger an error on the Sidekiq Job. The Sidekiq retry mechanism will handle re-enqueuing the job.
->
-> In contrast, slow synchronous HTTP requests will fill up the Sidekiq worker pool and block new jobs from being dequeued until a worker thread becomes free.
+> Synchronous HTTP requests in Sidekiq jobs behave differently. Slow synchronous requests fill the Sidekiq worker pool, and no new jobs start until a worker thread is free.
 >
-> In general, the former behavior is preferable because it allows Sidekiq to continue processing other jobs and prevents getting into a state with 1000's of jobs stuck in the queue.
+> The asynchronous behavior is usually better, because Sidekiq keeps running other jobs, and thousands of jobs don't pile up in the queue.
 
-## Metrics and Monitoring
+## Metrics and monitoring
 
 ### Web UI
 
-If you're using Sidekiq's Web UI, you can add a tab with the async HTTP processor statistics. The Web UI tab requires Sidekiq 7.3 or later.
+If you use the Sidekiq Web UI, you can add a tab that shows the async HTTP processor stats. The tab requires Sidekiq 7.3 or later.
 
 ```ruby
 # config/routes.rb (Rails)
@@ -599,45 +635,36 @@ require "patient_http/sidekiq/web"
 mount Sidekiq::Web => "/sidekiq"
 ```
 
-The Web UI shows:
-- Total requests, errors, average duration, and current capacity utilization
-- Per-processor capacity, utilization, requests, errors, average duration, and the high-water mark of
-  requests in flight, when more than one [named processor](#named-processors) is configured
-- The requests that have been in flight the longest, with their URL, HTTP method, processor, and age
-- Per-process inflight request counts
+The tab shows the following information:
+
+- Total requests, errors, times at capacity, average duration, and current capacity utilization.
+- Capacity, utilization, requests, errors, times at capacity, average duration, and the in-flight high-water mark for each processor, when more than one [named processor](#named-processors) is configured.
+- The requests that have been in flight the longest, with their URL, HTTP method, processor, and age.
+- The number of in-flight requests in each process.
 
-The per-processor numbers come from the capacity each process publishes with its heartbeat, so they
-cover the processes that are currently running and can lag by a few seconds.
+The processor numbers come from the capacity that each process publishes with its heartbeat. They cover the processes that are running, and they can be a few seconds old.
 
-The high-water mark is the most requests one process held on that processor at once, so compare it
-with `max_connections`, which is also per process, rather than with the capacity column, which is the
-sum across the running processes. The count only rises when a processor accepts a request, so the
-mark is exact rather than sampled. It covers everything since the statistics were last cleared.
+The high-water mark is the most requests that one process held on that processor at once. Compare it with `max_connections`, which is also per process, and not with the capacity column, which is the sum across running processes. The count rises only when a processor accepts a request, so the mark is exact, not sampled. It covers everything since the stats were last cleared.
 
-#### In-Flight Requests
+#### In-flight requests
 
-The URL, HTTP method, and processor of each in-flight request are recorded next to its
-crash-recovery record, and the dashboard lists the 50 oldest. A request left behind by a process
-that died stays listed until the orphan collector re-enqueues it, so this is also where you see what
-a process was working on when it stopped.
+The gem records the URL, HTTP method, and processor of each in-flight request next to its crash-recovery record. The dashboard lists the 50 oldest requests. A request left behind by a process that died stays listed until the orphan collector re-enqueues it. As a result, the list also shows what a process was working on when it stopped.
 
-The URL is sanitized before it is recorded: the user name, password, query string, and fragment are
-removed and the scheme, host, and path are kept. Paths can still carry identifiers, so you can
-redact more, or record nothing at all:
+The gem sanitizes each URL before it records it. It removes the user name, password, query string, and fragment, and keeps the scheme, host, and path. Paths can still contain identifiers, so you can remove more, or record nothing:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
-  # Redact more of the URL.
+PatientHttp.configure do |config|
+  # Remove more of the URL.
   config.inflight_url_sanitizer { |url| url.sub(%r{/users/\d+}, "/users/:id") }
 
-  # Or keep URLs out of Redis entirely.
+  # Or keep URLs out of Redis.
   config.inflight_details = false
 end
 ```
 
-### Callbacks for Custom Monitoring
+### Monitoring callbacks
 
-You can register callbacks to integrate with your monitoring system using the `after_completion` and `after_error` hooks:
+To send metrics to your monitoring system, register `after_completion` and `after_error` callbacks:
 
 ```ruby
 PatientHttp::Sidekiq.after_completion do |response|
@@ -651,14 +678,14 @@ PatientHttp::Sidekiq.after_error do |error|
 end
 ```
 
-You can register multiple callbacks; they will be called in the order registered.
+You can register more than one callback. Callbacks run in the order that you register them.
 
-### Handling Exhausted Retries
+### Handle exhausted retries
 
-When a callback worker job exhausts all of its Sidekiq retries, you can configure an `on_retries_exhausted` handler to be notified. This is useful for alerting or recording when a callback has permanently failed. The handler receives the same error object as the `on_error` callback:
+When a callback job uses up all of its Sidekiq retries, the gem can call an `on_retries_exhausted` handler. Use the handler to send an alert or to record that a callback failed permanently. The handler receives the same error object as `on_error`:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.on_retries_exhausted do |error|
     Sentry.capture_message("Callback permanently failed: #{error.message}")
     DeadLetterRecord.create!(
@@ -672,101 +699,78 @@ end
 You can also assign any object that responds to `call`:
 
 ```ruby
-PatientHttp::Sidekiq.configure do |config|
+PatientHttp.configure do |config|
   config.on_retries_exhausted = ->(error) { MyAlertService.notify(error) }
 end
 ```
 
 > [!NOTE]
-> The `on_retries_exhausted` handler is only invoked for jobs with an "error" result type. If the handler itself raises an exception, the error is logged as a warning and does not affect the normal dead job cleanup.
+> The gem calls the `on_retries_exhausted` handler only for callback jobs that deliver an error to `on_error`. If the handler raises an exception, the gem logs a warning, and the dead job cleanup continues as usual.
 
-## Shutdown Behavior
+## Shutdown behavior
 
-The async HTTP processor automatically hooks in with Sidekiq's lifecycle events.
+The async HTTP processor follows Sidekiq's lifecycle events:
 
-1. **Startup:** Processor starts automatically when Sidekiq starts
-2. **Quiet (TSTP signal):** Processor stops accepting new requests but continues processing in-flight requests
-3. **Shutdown:** Processor waits up to `shutdown_timeout` seconds for in-flight requests to complete
+1. **Startup**: The processor starts when Sidekiq starts.
+2. **Quiet** (TSTP signal): The processor stops accepting new requests but continues to run in-flight requests.
+3. **Shutdown**: The processor waits up to `shutdown_timeout` seconds for in-flight requests to finish.
 
-### Incomplete Request Handling
+### Incomplete requests
 
-If requests are still in-flight when shutdown times out:
+If requests are still in flight when the shutdown timeout ends, the gem interrupts them and re-enqueues their Sidekiq jobs. The jobs run again when Sidekiq restarts or on another Sidekiq process, so no work is lost during deployments or restarts.
 
-- In-flight requests are interrupted
-- The **original Sidekiq job** is automatically re-enqueued
-- Re-enqueued jobs will be processed again when Sidekiq restarts
+### Crash recovery
 
-This ensures no work is lost during deployments or restarts.
+The gem recovers requests from processes that crash:
 
-### Crash Recovery
+1. **Heartbeats**: Every `heartbeat_interval` seconds, each process updates the heartbeat times of its in-flight requests in Redis.
+2. **Orphan detection**: One process at a time checks for requests that haven't had a heartbeat in `orphan_threshold` seconds.
+3. **Re-enqueue**: The gem re-enqueues the Sidekiq jobs of the orphaned requests.
 
-The gem includes crash recovery to handle process failures:
+As a result, if a Sidekiq process crashes, another process retries its in-flight requests.
 
-1. **Heartbeat Tracking:** Every `heartbeat_interval` seconds, the processor updates heartbeat timestamps for all in-flight requests in Redis
-2. **Orphan Detection:** One processor periodically checks for requests that haven't received a heartbeat update in `orphan_threshold` seconds
-3. **Automatic Re-enqueue:** Orphaned requests have their original Sidekiq jobs re-enqueued
+Crash recovery gives at-least-once delivery. If a process crashes at the wrong moment, such as between a re-enqueue and the removal of the registry entry, a request can run more than once, and its callback can run more than once. Make your callbacks idempotent. A request is durable once the call that makes it returns. A crash during the call behaves like a failed enqueue, and the caller never gets an acknowledgment.
 
-This ensures that if a Sidekiq process crashes, its in-flight requests will be retried by another process.
-
-Crash recovery gives at-least-once delivery. If a process crashes at the wrong moment (for example, between a re-enqueue and the removal of the registry entry), a request can execute more than once and its callback can fire more than once. Make your callbacks idempotent. A request is durable once the call that submits it returns; a crash during the call behaves like a failed enqueue, and the caller never received an acknowledgment.
-
-A request whose result cannot be handed to a callback job keeps its registry entry as well, so the same recovery re-enqueues it. When the failure is one that trying again cannot fix, because the result cannot be serialized, the request is not kept: it is counted as an `undeliverable_result` error and its job is moved to the Sidekiq dead set, where you can inspect it and retry it by hand.
+If the gem can't hand a result to a callback job, it keeps the request's registry entry, so crash recovery re-enqueues the request. The exception is a failure that a retry can't fix, because the result can't be serialized. In that case, the gem records an `undeliverable_result` error and moves the job to the Sidekiq dead set, where you can inspect it and retry it by hand.
 
 ## Testing
 
-The gem supports `Sidekiq::Testing.inline!` mode for synchronous testing. When in inline mode, async HTTP requests are executed immediately within the worker thread, blocking until completion. This allows you to write tests that verify the full request/response cycle without needing the async processor to be running.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem "patient_http-sidekiq"
-```
-
-Then execute:
-
-```bash
-bundle install
-```
+The gem supports `Sidekiq::Testing.inline!`. In inline mode, requests run immediately in the worker thread and block until they finish. As a result, tests can check the full request and response cycle without a running processor.
 
 ## Contributing
 
 Open a pull request on [GitHub](https://github.com/bdurand/patient_http-sidekiq).
 
-Please use the [standardrb](https://github.com/testdouble/standard) syntax and lint your code with `standardrb --fix` before submitting.
+Follow the [standardrb](https://github.com/testdouble/standard) style, and run `standardrb --fix` before you submit a pull request.
 
-Running the tests requires a Redis compatible server. There is a script to start one in a local container running on port 24455:
+The tests require a Redis-compatible server. To start one in a local container on port 24455, run this script:
 
 ```bash
 bin/run-valkey
 ```
 
-Then run the test suite with:
+Then run the tests:
 
 ```bash
 bundle exec rake
 ```
 
-There is also a bundled test app in the `test_app` directory that can be used for manual testing and experimentation.
-
-To run the test app, first install the dependencies:
+The `test_app` directory has a test app for manual testing. To run it, install its dependencies:
 
 ```bash
 bundle exec rake test_app:bundle
 ```
 
-The server will run on http://localhost:9292 and can be started with:
+Then start the server, which runs at http://localhost:9292:
 
 ```bash
 bundle exec rake test_app
 ```
 
-## Further Reading
+## Further reading
 
 - [Architecture](ARCHITECTURE.md)
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).