dedupe_requests 1.0.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cabb55d1b9a54a93f4b72f552fed6d9a1c38a8343a3750444196150ce21a3ff0
+  data.tar.gz: 6308e4ef27a02cb46bf495f1dd1fd00535e83118a0cbbe99a65b2cf91d19cf82
+SHA512:
+  metadata.gz: 561cc06ce39366c6a2e816c6b2f9f4404a0cafd59673e08e69809a8283e8a3ce8adec51cf2225d974a223099525c21c72ac810b437ac809e3c2bd932faf6e209
+  data.tar.gz: f20afbdb2841ec7cf9c3ece8eb686fc0f6e3574d5dc805bf641c30692cbdbb2f1e333f6b514c7d97721a8b756ead454b366ee9a012bf7e99370f6b8cb7dcb569

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0.pre1 (2026-06-16)
+
+Initial release. See the [README](README.md) for full usage and configuration.
+
+### Summary
+- Server-side de-duplication of inbound mutating requests — **POST/PUT/PATCH only** (GET/DELETE are never deduped). No client-supplied idempotency key required: the server computes a fingerprint of each request (caller + verb + path + query + body).
+- Controller macro `dedupe_requests` with `on:` (add) and `skip:` (remove), plus `skip_dedupe_requests`, over an inherited per-action map — declare a baseline in `ApplicationController` and refine it per subclass. Guarded actions are matched by action name.
+- Per-action TTL by repeating the macro line; actions without one fall back to the global `ttl`.
+- Per-caller scoping via `caller_id` — by default derived from the `Authorization` header (or a Rails session cookie), and fully overridable with your own callable.
+- Pluggable `fingerprint` override to replace the default fingerprint computation entirely.
+- Three operating modes for safe rollout: `:off`, `:observe` (detect-only / shadow), and `:enforce` (reject duplicates).
+- Configurable 409 conflict response (`conflict_status`, `conflict_body`), with an `X-Dedupe-Request` header set on rejections.
+- Reliability: atomic `SET NX EX` claim with a random token and a token-safe Lua check-and-del release; **fails open** (allows the request through) when Redis is unreachable.
+- Retry-friendly claim lifecycle: keeps the fingerprint on a 2xx or 3xx response (including Post/Redirect/Get), and releases it on a 4xx/5xx response or a raised exception, so a genuinely failed request can be retried.
+- Observability hooks: `on_duplicate_detected` and `on_duplicate_rejected`.
+- Configurable digest (`:sha256` default, plus `:sha1` / `:sha512` / `:md5`, or a callable), key `namespace`, and `logger`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tilo Sloboda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# dedupe_requests
+
+Automatic server-side de-duplication of inbound mutating Rails requests (POST / PUT / PATCH), with **no client-side idempotency key required**.
+
+When a client re-sends the same mutating request — because of a retry, a network timeout, a double-click, or a buggy client — a non-idempotent endpoint often turns the duplicate into a 5xx (the resource is already created or modified).
+
+One go-to solution for this used to be to require the client to provide a idempotency key together with the request, and then reject duplicate requests (requests that use a previous idemptotency key).
+
+`dedupe_requests` simplifies this, removing the requirement for providing an idempotency key, and instead auto-computes a fingerprint of each mutating request (effectively auto-generating the idempotency key on-the-fly), claims it atomically in Redis, and short-circuits a duplicate seen within a configurable window with a clean **409 Conflict** instead of letting it blow up your app.
+
+This is different from the usual idempotency-key gems: the **server** computes the fingerprint from the request itself, so
+* existing clients need no changes
+* clients no longer need to send an idempotency_key
+
+## How it works
+
+1. A mutating request (POST/PUT/PATCH) arrives for a guarded action.
+2. The server computes a fingerprint: `digest(caller_id + verb + path + query + body)`.
+3. It runs an atomic `SET key <token> NX EX <ttl>` in Redis.
+   - **Key already existed** → it's a duplicate. In `enforce` mode, respond `409`; in `observe` mode, just record it and let it through.
+   - **Key created** → first occurrence. Run the action normally.
+4. After the action: a **2xx, or a 3xx redirect** (the Post/Redirect/Get pattern is a successful create), keeps the fingerprint until the TTL expires — so a later duplicate is blocked; a **4xx/5xx or a raised exception releases** the fingerprint, so a genuine retry of a failed request is allowed.
+
+GET and DELETE are never deduped. Time is not part of the fingerprint — the window is the Redis TTL.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "dedupe_requests"
+```
+
+## Usage
+
+### 1. Global defaults — an initializer
+
+```ruby
+# config/initializers/dedupe_requests.rb
+DedupeRequests.configure do |c|
+  c.redis     = Redis.new(url: ENV["REDIS_URL"])
+  c.mode      = :enforce            # :off | :observe | :enforce
+  c.ttl       = 90                  # the dedup window, in seconds
+  c.digest    = :sha256             # :sha256 | :sha512 | :sha1 | :md5 | ->(bytes) { ... }
+  c.namespace = "myapp"             # Redis key prefix
+  c.caller_id = ->(controller) { controller.current_user&.id }   # per-caller scoping
+  c.logger    = Rails.logger        # where Redis/fail-open errors are logged
+end
+```
+
+The guarded verbs are fixed — **POST, PUT, PATCH**. They're not a config knob, and GET/DELETE are never deduped.
+
+### 2. Per-controller — the `dedupe_requests` macro
+
+Include the concern once (usually in `ApplicationController`), then declare which actions are guarded:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include DedupeRequests::Controller
+  dedupe_requests on: %i[create update]     # project-wide baseline
+end
+```
+
+Each `dedupe_requests` line **adds** the actions it names to the list of deduplicated actions — it does not replace anything (same as Rails' own `before_action only:`). A controller inherits its parent's guarded actions and can add more or drop some:
+
+The list of deduplicated actions is matched by **action name**: once the baseline names `create`, every controller that inherits it deduplicates its own `create` action — not just `ApplicationController`'s. Opt a controller out with `skip:`.
+
+| Option  | Effect on this controller                      |
+| ------- | ---------------------------------------------- |
+| `on:`   | guard these actions (uses this line's `ttl:`)  |
+| `skip:` | stop guarding these actions — no dedupe at all  |
+
+```ruby
+class OrdersController < ApplicationController
+  dedupe_requests on: %i[approve cancel]   # adds approve/cancel to the inherited create/update
+end
+
+class DraftsController < ApplicationController
+  dedupe_requests skip: %i[create]           # guards everything inherited except create
+end
+```
+
+#### Per-action TTL
+
+A `ttl:` applies to exactly the actions named on its line. Give different actions different windows by repeating the line — a list shares one TTL:
+
+```ruby
+class PaymentsController < ApplicationController
+  dedupe_requests on: %i[create charge], ttl: 120   # create + charge → 120s
+  dedupe_requests on: [:refund],         ttl: 600   # refund → 600s
+end
+```
+
+An action with no `ttl:` falls back to the global `config.ttl`; re-declaring an action updates its TTL.
+
+You never specify HTTP verbs per action — the route already determines the verb, and the gem only ever guards POST/PUT/PATCH.
+
+### 3. Per-caller identity (`caller_id`)
+
+Dedup is scoped per caller, so two different users sending the same payload don't collide. `caller_id` is a callable given the **controller**, so it can read whatever identifies the caller:
+
+```ruby
+DedupeRequests.configure do |c|
+  c.caller_id = ->(controller) { controller.current_user&.id }                       # current_user
+  # c.caller_id = ->(controller) { controller.request.get_header("HTTP_X_API_KEY") }  # a header
+  # c.caller_id = ->(controller) { controller.some_method }                           # any controller method
+end
+```
+
+If you don't set it, the default derives identity from the `Authorization` header, falling back to a Rails session cookie — so token- and cookie-auth apps work with no configuration.
+
+> **Note:** make sure you configure `caller_id` correctly for your API. If it can't derive an identity (no `Authorization` header and no session cookie), it falls back to `nil` — and then *different* callers sending the same payload to the same endpoint are treated as one request, so the second gets a 409. That's probably not what you want, so set `caller_id` to whatever identifies a caller in your app.
+
+## Modes and safe rollout
+
+`mode` has three states:
+
+- `:off` — disabled; no fingerprinting, no storage.
+- `:observe` — **shadow mode**: compute and store fingerprints and fire the metrics hooks, but never return a 409. Duplicates are detected and reported only.
+- `:enforce` — detect, store, and reject duplicates with a 409.
+
+Recommended rollout on a live service: enable `:observe`, build a dashboard from the `duplicate_detected` hook, watch real volume for a week or two, then flip to `:enforce`.
+
+## Observability
+
+Wire the hooks to your metrics/logging backend (Datadog, StatsD, logs — your choice):
+
+```ruby
+DedupeRequests.configure do |c|
+  c.on_duplicate_detected = ->(info) { StatsD.increment("dedupe.detected", tags: { controller: info[:controller], action: info[:action], verb: info[:verb] }) }
+  c.on_duplicate_rejected = ->(info) { StatsD.increment("dedupe.rejected", tags: { controller: info[:controller], action: info[:action], verb: info[:verb] }) }
+end
+```
+
+Each hook receives `{ fingerprint:, controller:, action:, verb:, path: }`. `duplicate_detected` fires in both `observe` and `enforce`; `duplicate_rejected` only when a 409 is actually returned.
+
+When tagging metrics, use only `controller`, `action`, and `verb` — these come from a small fixed set. Do **not** tag with `fingerprint` or `path`: the fingerprint is unique per request and the path usually contains record ids, so tagging with them creates a separate counter per request (a surprise bill on Datadog, or dropped series and broken dashboards). Log those instead if you need them.
+
+## The 409 response
+
+Default body (override via `config.conflict_body`, and status via `config.conflict_status`):
+
+```json
+{
+  "errors": [{
+    "error_key": "base",
+    "category": "duplicate_operation",
+    "message": "Duplicate request detected. A matching request is in-flight or recently completed."
+  }]
+}
+```
+
+A `409` is deliberate: well-behaved retrying clients do **not** loop on a 409 (they do on 5xx), so a duplicate is rejected cleanly without triggering further retries.
+
+## Reliability
+
+- **Fail open.** If Redis is unreachable, the request proceeds normally — a Redis outage never blocks traffic. Redis errors are rescued and logged (set `config.logger`). The logger is used **only** for these Redis/fail-open errors — not for normal duplicate handling (use the hooks above for that) — and it is wired automatically only when the store is built from `config.redis`. If you inject your own `config.store`, pass it a logger directly.
+- **Token-safe release.** Each claim stores a random token; release deletes the key only if it still holds that token (via a Lua check-and-del), so a slow request whose TTL expired can't wipe a newer request's fresh claim.
+- **Compile Ruby with OpenSSL — for speed.** The fingerprint hashes the request body on the hot path. It uses `OpenSSL::Digest`, which runs on the CPU's SHA instructions (SHA-NI / ARM crypto) at ~1.5–2 GB/s. If your Ruby is built **without** OpenSSL, the gem still works — it falls back to the stdlib `Digest` — but that's a portable software implementation (~300–500 MB/s, no SHA instructions), several times slower on large bodies. So build Ruby with OpenSSL in production.
+
+## Configuration reference
+
+| Option                   | Default              | Purpose                                                            |
+| ------------------------ | -------------------- | ----------------------------------------------------------------- |
+| `redis`                  | `nil`                | A Redis client or a connection pool.                              |
+| `store`                  | built from `redis`   | Inject a custom store responding to `claim` / `release`.          |
+| `mode`                   | `:enforce`           | `:off` / `:observe` / `:enforce`.                                 |
+| `ttl`                    | `90`                 | Dedup window, in seconds.                                         |
+| `digest`                 | `:sha256`            | `:sha256` / `:sha512` / `:sha1` / `:md5`, or a callable.          |
+| `namespace`              | `"dedupe_requests"`  | Redis key prefix (`<namespace>:dedup:<hash>`).                    |
+| `caller_id`              | Authorization / session cookie | Callable **given the controller**, returns a per-caller identity (e.g. `->(c){ c.current_user&.id }`, a header via `c.request`, or any controller method). Default derives it from the Authorization header / session cookie. |
+| `fingerprint`            | `nil`                | Callable **given the request**, returns the fingerprint string — fully overriding the default computation. |
+| `conflict_status`        | `409`                | Status returned for a rejected duplicate.                        |
+| `conflict_body`          | structured errors    | JSON body for a rejected duplicate.                              |
+| `logger`                 | `nil`                | Where Redis errors are logged.                                   |
+| `on_duplicate_detected`  | `nil`                | Hook fired when a duplicate is seen.                             |
+| `on_duplicate_rejected`  | `nil`                | Hook fired when a duplicate is rejected with a 409.             |
+
+> **Why `caller_id` is given the controller but `fingerprint` is given the request:** they answer different questions at different layers. `caller_id` identifies *who* is calling — an app-level question that often needs controller context like `current_user`, so it receives the controller. `fingerprint` characterizes *which request* this is — a pure function of the HTTP request (verb + path + query + body), computed in the framework-agnostic core where the body is hashed on the hot path, so it receives the request directly. Each callable is handed the object that matches its job.
+
+## Limitations
+
+Auto-hashing the payload means two *genuinely separate* requests with identical content (e.g. deliberately creating two identical records in quick succession) look like a duplicate, and the second gets a 409. Mitigations: keep the TTL short, and opt specific actions out with `skip_dedupe_requests` (or `skip:`). This is best-effort de-duplication, not exactly-once semantics. It does **not** use client-supplied idempotency keys at all — an `Idempotency-Key` (or any similar) header is ignored and has no effect on the fingerprint; de-duplication is entirely server-computed.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/examples/README.md

@@ -0,0 +1,156 @@
+# dedupe_requests — runnable example & end-to-end test
+
+This directory holds a small but real Rails API service that uses `dedupe_requests`, plus an automated test that drives it over real HTTP. It exists to show the gem working in a realistic setup and to prove, end to end, both the inheritance behavior (baseline at `ApplicationController`, then refine per subclass) and the request-lifecycle behavior (per-caller scoping, concurrency, claim release on failure, the verb filter, redirects, observe mode, and the configuration hooks — `on_duplicate_detected`, `on_duplicate_rejected`, and the `fingerprint` override).
+
+There is no in-process stubbing here: the test boots a real Puma server on a real TCP socket, sends real HTTP requests with `Net::HTTP`, and asserts on the status codes that come back. The gem writes its claims to a real Redis; Redis expires them on its own TTL. The test never reads or writes Redis — it only speaks HTTP.
+
+## Files
+
+| File                  | What it is                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------ |
+| `config.ru`           | The Rails API service: one `ApplicationController` baseline, its subclasses, and the routes       |
+| `end_to_end_test.rb`  | The automated test: boots `config.ru` under Puma, fires HTTP at it, checks every scenario         |
+
+## Running it
+
+You need a running Redis (the gem talks to it, not the test) and the bundle installed.
+
+```
+redis-server &                       # if one isn't already running
+bundle install
+bundle exec rake integration         # or: bundle exec ruby examples/end_to_end_test.rb
+```
+
+The test prints a per-scenario report and exits `0` if every check passes, `1` otherwise.
+
+By default it uses `redis://localhost:6379/15` and port `9377`. Override with the `REDIS_URL` and `PORT` environment variables. It does not flush or otherwise touch Redis — each run tags its requests with a unique per-run id (a `?run=<uuid>` query) so a rerun never collides with claims still alive from a previous run.
+
+### Poking at it by hand
+
+You can also boot the service on its own and hit it with `curl`:
+
+```
+redis-server &
+bundle exec puma examples/config.ru -p 9292
+
+curl -i -XPOST localhost:9292/widgets -H 'content-type: application/json' \
+     -H 'authorization: Bearer token-alice' -d '{"name":"Blue Widget","color":"blue","quantity":3}'   # 201 Created
+# the exact same request again, within the TTL:
+curl -i -XPOST localhost:9292/widgets -H 'content-type: application/json' \
+     -H 'authorization: Bearer token-alice' -d '{"name":"Blue Widget","color":"blue","quantity":3}'   # 409 Conflict (duplicate)
+```
+
+## The controller hierarchy
+
+Everything inherits from one `ApplicationController` that declares the app-wide baseline. Each subclass then refines it, which is the whole point of the exercise:
+
+| Controller             | Declares                          | What it demonstrates                                      |
+| ---------------------- | --------------------------------- | -------------------------------------------------------- |
+| `ApplicationController`| `dedupe_requests on: %i[create update]` | the app-wide baseline                              |
+| `WidgetsController`    | *(nothing)*                       | the baseline reaches a subclass that declares nothing    |
+| `OrdersController`     | `dedupe_requests on: [:approve]`  | adds an action on top of the inherited create/update     |
+| `DraftsController`     | `dedupe_requests skip: [:create]` | drops one inherited action; the rest stay guarded        |
+| `PaymentsController`   | `dedupe_requests on: [:create], ttl: 5` | overrides the TTL for one action                   |
+
+A few more subclasses exist only to exercise the request-lifecycle behavior (they all inherit the baseline):
+
+| Controller             | What it is for                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `SlowController`       | a deliberately slow `create` (sleeps ~1s) so two requests can be genuinely in flight at once      |
+| `FailuresController`   | a `create` that returns 422 and an `update` that raises — to show the claim is released on failure |
+| `ReadController`       | `index`/`destroy` guarded **by name** but reached via GET/DELETE, which are never deduplicated     |
+| `RedirectsController`  | a `create` that returns a 303 redirect, to show a redirect keeps the claim                         |
+| `HookedController`     | a clean guarded `create` used only by the hooks scenario, so its recorded events are unambiguous   |
+| `DebugController`      | test-only: exposes the recorded hook invocations at `GET /_hooks` so the test can read them        |
+
+Two things worth remembering about how this works (both are tested below):
+
+- Deduplication only ever applies to **POST/PUT/PATCH**. GET and DELETE are never deduplicated.
+- The guarded actions are matched **by action name**. Once the baseline names `create`, every controller that inherits it deduplicates its own `create` — not just `ApplicationController`'s.
+
+## What makes two requests a "duplicate"
+
+The gem fingerprints **caller + verb + path + query string + body**. Two requests collide (the second is a duplicate) only when all of those match. In this example:
+
+- The **caller** is taken from the `Authorization` header — the gem's default `caller_id`. The test sends a different `Authorization: Bearer <token>` per simulated caller (`alice`, `bob`, `carol`), so the same payload from two different callers is **not** a duplicate.
+- The **body** is a realistic per-endpoint JSON payload. Each distinct logical request uses its own payload, so within a run only an intentional repeat looks like a duplicate.
+- The **`?run=<uuid>` query** is only there to isolate one test run from the next; it is not meant to represent a real-world payload.
+
+The service runs in `:enforce` mode by default, so a detected duplicate is rejected with **409 Conflict**. A first (or non-duplicate) request returns **201 Created**. Two later scenarios boot extra servers: one in `:observe` mode (where a duplicate is detected but allowed through), and one with a custom `fingerprint`.
+
+The configuration hooks are wired up so the test can check they actually fire: `config.ru` records every `on_duplicate_detected`, `on_duplicate_rejected`, `fingerprint`-override, and `caller_id`-override invocation in memory and exposes them at `GET /_hooks`, which the test reads over HTTP.
+
+## The scenarios
+
+The test runs scenarios (1)–(10) and (12) against one enforce-mode server, then boots a second server in observe mode for scenario (11), a third with a custom fingerprint for scenario (13), and a fourth with a custom caller_id for scenario (14).
+
+### (1) Baseline at the application-controller level
+
+`WidgetsController` declares nothing of its own — it only inherits the baseline. The test confirms a repeated `POST /widgets` (and a repeated `PATCH /widgets/:id`) from the same caller is rejected with 409. This proves the baseline declared on `ApplicationController` guards a subclass that never mentions `dedupe_requests`.
+
+### (2) Skipping a baseline action in a subclass
+
+`DraftsController` does `skip: [:create]`. The test sends the same `POST /drafts` twice and expects **201 both times** (create is no longer guarded here), while a repeated `PATCH /drafts/:id` is still rejected with 409 (update is still inherited). This proves `skip:` removes exactly one action and leaves the rest of the inherited set intact.
+
+### (3) Adding an action in a subclass
+
+`OrdersController` does `on: [:approve]`. The test confirms a repeated `POST /orders/:id/approve` is rejected with 409 (the added action is now guarded), and that a repeated `POST /orders` is still rejected too (the inherited create/update baseline is untouched). This proves `on:` adds to the inherited set rather than replacing it.
+
+### (4) Changing the TTL in a subclass — proven by real expiry
+
+`PaymentsController` overrides the TTL for `create` (5s) while everything else uses the global TTL (2s). The test proves the difference purely by behavior, with real waiting:
+
+1. Open a claim on `POST /orders` (2s) and on `POST /payments` (5s); duplicates of each are rejected with 409.
+2. Wait ~3s. Now `POST /orders` is allowed again (its 2s window expired) while `POST /payments` is still rejected (its 5s window is still open).
+3. Wait ~3s more. Now `POST /payments` is allowed again too (its 5s window finally expired).
+
+This is the most "real life" check in the suite: nothing inspects Redis or the claim TTL directly — the test just lets real time pass and watches the shorter window reopen first.
+
+### (5) Per-caller scoping
+
+`alice` posts a payment and her immediate repeat is rejected with 409. Then `bob` and `carol` post the **exact same payload** and both get 201 — a different caller is a different request, not a duplicate. `bob`'s own repeat is then rejected with 409. This proves deduplication is scoped per caller, so two different users sending identical content do not collide.
+
+### (6) Different payload, same caller
+
+`alice` posts a red widget (201), then a green widget (201) — a different body is a different request, not a duplicate — then the red widget again (409). This is the complement of scenario (5): same caller, *different* payload is allowed; same caller, *same* payload is blocked.
+
+### (7) Concurrent in-flight duplicate
+
+Two identical `POST /slow` requests are fired from the same caller at the same instant, in separate threads, against an action that sleeps ~1s. Exactly one wins (201) and the other is rejected (409). This is the scenario the gem exists for: the claim is taken *before* the action runs and held for its duration, so a second request that arrives while the first is still in flight is rejected — not just a duplicate that arrives after the first has finished.
+
+### (8) Release on failure
+
+A failed request frees its claim so an identical retry is allowed instead of wrongly blocked. `POST /failures` returns 422 twice (not 409) — a 4xx/5xx response releases the claim. `PATCH /failures/:id` raises, returning 500 twice (not 409) — a raised exception releases the claim too. Only a successful (2xx/3xx) request keeps its claim.
+
+### (9) GET and DELETE are never deduplicated
+
+`ReadController` guards `index` and `destroy` **by name**, but they are reached via GET and DELETE. Two identical `GET /reads` and two identical `DELETE /reads/:id` all return 200 — never 409. This proves the verb filter: only POST/PUT/PATCH are ever deduplicated, even when the action name is in the guarded set.
+
+### (10) A 3xx redirect keeps the claim
+
+`POST /redirects` returns a 303 redirect (the Post/Redirect/Get pattern, which is a *successful* create). The first returns 303 and the duplicate is rejected with 409 — a redirect keeps the claim for the full TTL, just like a 2xx, so a duplicate is still blocked.
+
+### (11) Observe mode lets duplicates through
+
+This runs against a second server booted with `DEDUPE_MODE=observe`. `alice` posts a payment (201) and the identical repeat also returns **201** — in observe mode a duplicate is detected but allowed through instead of being rejected with 409. The test then reads `GET /_hooks` and confirms `on_duplicate_detected` **did** fire while `on_duplicate_rejected` did **not** — that difference is the whole point of observe mode, and it's how you roll the gem out in shadow mode before enforcing.
+
+### (12) Duplicate-notification hooks fire
+
+On the enforce server, `alice` posts to `/hooked` (201, claimed) and repeats it (409). The test then reads `GET /_hooks` and confirms `on_duplicate_detected` fired exactly once and `on_duplicate_rejected` fired exactly once for `/hooked`, and that the detected event carried the expected data (`action: "create"`, `verb: "POST"`, and a non-empty fingerprint). This proves both notification hooks run, with the right arguments, in enforce mode.
+
+### (13) The fingerprint override is used
+
+This runs against a third server booted with a custom `fingerprint` callable that keys only on **verb + path** (ignoring caller and body). `alice` posts a widget (201); a *different* body (201 normally) now returns **409**, and so does a post from a *different caller* — because the custom fingerprint ignores both. The test also confirms via `GET /_hooks` that the override was invoked once per mutating request. This proves the `fingerprint` config replaces the default fingerprint logic entirely.
+
+### (14) The caller_id override is used
+
+This runs against a fourth server booted with a custom `caller_id` callable that reads an **`X-Api-Key`** header (instead of the `Authorization` header the default uses). Two requests with the same `X-Api-Key` but *different* `Authorization` collide (the second is a **409**) — which only happens if the identity comes from `X-Api-Key` — while a request with a *different* `X-Api-Key` is treated as a new caller (201). The test also confirms via `GET /_hooks` that the override ran on each request and saw the expected key values. This proves a custom `caller_id` is what drives the per-caller scoping.
+
+## Notes
+
+- The short TTLs (2s and 5s) exist so the expiry test in scenario (4) runs quickly; they are set via the `DEDUPE_TTL` and `DEDUPE_PAYMENT_TTL` environment variables that `config.ru` reads. The slow action's duration is set by `DEDUPE_SLOW_SECONDS` (default 1s).
+- `DEDUPE_MODE` selects `enforce` (default) or `observe`; the test boots the observe-mode server on `PORT + 1`.
+- `DEDUPE_CUSTOM_FINGERPRINT=1` swaps in the custom `fingerprint` callable; the test boots that server on `PORT + 2`.
+- `DEDUPE_CUSTOM_CALLER_ID=1` swaps in the custom `caller_id` callable (reads `X-Api-Key`); the test boots that server on `PORT + 3`.
+- `GET /_hooks` is a test-only endpoint that returns the hook invocations the server recorded; it is not part of the dedupe demo.
+- The Puma output is written to a log in your temp directory (`dedupe_puma_<port>.log`) and is printed only if the server fails to start.

data/examples/config.ru

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+#
+# A real Rails API service that exercises every dedupe_requests feature, booted
+# as a REAL HTTP server (Puma) for examples/end_to_end_test.rb.
+#
+# Run it standalone to poke at it by hand:
+#
+#   redis-server &                                    # needs a running Redis
+#   bundle exec puma examples/config.ru -p 9292       # boot the server
+#
+#   curl -i -XPOST localhost:9292/widgets -d '{"a":1}' -H 'content-type: application/json'  # 201
+#   curl -i -XPOST localhost:9292/widgets -d '{"a":1}' -H 'content-type: application/json'  # 409 (duplicate)
+#
+# The controllers below form one inheritance tree off ApplicationController. A
+# single boot covers the inheritance features and the request-lifecycle behavior:
+#
+#   (1) baseline at the application-controller level   -> WidgetsController (declares nothing)
+#   (2) skipping a baseline action in a subclass        -> DraftsController  (skip: [:create])
+#   (3) adding an action in a subclass                  -> OrdersController  (on: [:approve])
+#   (4) changing the TTL in a subclass                  -> PaymentsController (on: [:create], ttl)
+#   - a slow action (for the concurrent in-flight test) -> SlowController
+#   - actions that fail / raise (claim is released)     -> FailuresController
+#   - GET/DELETE actions guarded by name (never deduped) -> ReadController
+#   - a 3xx redirect (claim is kept)                    -> RedirectsController
+#
+# DEDUPE_MODE selects :enforce (default) or :observe so the test can boot a second
+# server to check observe-mode pass-through.
+
+require "logger" # ActiveSupport < 7.1 references ::Logger before requiring it
+require "securerandom"
+require "action_controller"
+require "action_dispatch"
+require "redis"
+require_relative "../lib/dedupe_requests"
+
+# Short TTLs on purpose: the integration test proves the TTL difference by waiting
+# for the shorter window to expire while the longer one is still open.
+GLOBAL_TTL  = Integer(ENV.fetch("DEDUPE_TTL", "2"))
+PAYMENT_TTL = Integer(ENV.fetch("DEDUPE_PAYMENT_TTL", "5"))
+
+# Test instrumentation: every hook invocation is appended here (one Puma process,
+# many threads, so a Mutex is enough), and exposed at GET /_hooks so the test can
+# assert — over HTTP — that the right hooks fired with the right data.
+HOOK_EVENTS = []
+HOOK_MUTEX  = Mutex.new
+def record_hook(event)
+  HOOK_MUTEX.synchronize { HOOK_EVENTS << event }
+end
+
+DedupeRequests.configure do |c|
+  c.redis = Redis.new(url: ENV.fetch("REDIS_URL", "redis://localhost:6379/15"))
+  c.mode  = ENV.fetch("DEDUPE_MODE", "enforce").to_sym
+  c.ttl   = GLOBAL_TTL
+  # caller_id is left at its default, which derives the caller identity from the
+  # request's Authorization header. The integration test sends a different
+  # `Authorization: Bearer <token>` per simulated caller, so the same payload from
+  # two different callers fingerprints differently and is NOT treated as a duplicate.
+
+  # Record the duplicate-notification hooks. on_duplicate_detected fires whenever a
+  # duplicate is seen (observe AND enforce); on_duplicate_rejected fires only when a
+  # duplicate is actually rejected (enforce mode).
+  c.on_duplicate_detected = ->(info) { record_hook(info.merge(hook: "detected")) }
+  c.on_duplicate_rejected = ->(info) { record_hook(info.merge(hook: "rejected")) }
+
+  # When asked, replace the whole fingerprint with a custom one that keys only on
+  # verb + path + query (ignoring caller AND body), so the test can prove the
+  # override took effect: two different bodies — or two different callers — now
+  # collide. It also records that the hook was invoked.
+  if ENV["DEDUPE_CUSTOM_FINGERPRINT"] == "1"
+    c.fingerprint = lambda do |request|
+      record_hook(hook: "fingerprint", path: request.path, verb: request.request_method)
+      "#{request.request_method}:#{request.path}?#{request.query_string}"
+    end
+  end
+
+  # When asked, replace caller_id with a custom one that identifies the caller by
+  # an X-Api-Key header (ignoring the Authorization header the default would use),
+  # so the test can prove this callable is what drives the per-caller scoping. It
+  # also records that the hook was invoked.
+  if ENV["DEDUPE_CUSTOM_CALLER_ID"] == "1"
+    c.caller_id = lambda do |controller|
+      key = controller.request.get_header("HTTP_X_API_KEY")
+      record_hook(hook: "caller_id", path: controller.request.path, key: key)
+      key
+    end
+  end
+end
+
+# Most actions just return 201 with a unique id, tagged with the resource name so
+# a manual curl shows which controller answered.
+module RenderOk
+  def render_ok(resource, extra = {})
+    render json: { ok: true, id: SecureRandom.uuid, resource: resource }.merge(extra), status: :created
+  end
+end
+
+# (1) Application-controller level: the baseline lives here. Every subclass
+#     inherits it, including ones that declare nothing of their own.
+class ApplicationController < ActionController::API
+  include RenderOk
+  include DedupeRequests::Controller
+  dedupe_requests on: %i[create update]
+end
+
+# Declares NOTHING — proves the baseline reaches a bare subclass. The GET #index
+# is reached below to show GET is never deduplicated.
+class WidgetsController < ApplicationController
+  def create
+    render_ok("widget")
+  end
+
+  def update
+    render_ok("widget")
+  end
+
+  def index
+    render json: { widgets: [] }, status: :ok
+  end
+end
+
+# (3) Adds :approve on top of the inherited create/update.
+class OrdersController < ApplicationController
+  dedupe_requests on: [:approve]
+
+  def create
+    render_ok("order")
+  end
+
+  def update
+    render_ok("order")
+  end
+
+  def approve
+    render_ok("order", approved: true)
+  end
+end
+
+# (2) Skips :create from the baseline; :update stays guarded.
+class DraftsController < ApplicationController
+  dedupe_requests skip: [:create]
+
+  def create
+    render_ok("draft")
+  end
+
+  def update
+    render_ok("draft")
+  end
+end
+
+# (4) Overrides the TTL for :create only (PAYMENT_TTL instead of GLOBAL_TTL).
+class PaymentsController < ApplicationController
+  dedupe_requests on: [:create], ttl: PAYMENT_TTL
+
+  def create
+    render_ok("payment")
+  end
+end
+
+# A deliberately slow action so the test can fire two requests that are genuinely
+# in flight at the same time. :create is guarded by the inherited baseline.
+class SlowController < ApplicationController
+  def create
+    sleep Float(ENV.fetch("DEDUPE_SLOW_SECONDS", "1"))
+    render_ok("slow")
+  end
+end
+
+# Failing actions. The claim is released on a 4xx/5xx response (#create) or a
+# raised exception (#update), so an identical retry is NOT blocked.
+class FailuresController < ApplicationController
+  def create
+    render json: { error: "unprocessable" }, status: :unprocessable_entity
+  end
+
+  def update
+    raise "simulated failure"
+  end
+end
+
+# Actions guarded BY NAME, but reached via GET/DELETE — which the gem never
+# deduplicates. Repeats are allowed even though :index/:destroy are in the set.
+class ReadController < ApplicationController
+  dedupe_requests on: %i[index destroy]
+
+  def index
+    render json: { items: [] }, status: :ok
+  end
+
+  def destroy
+    render json: { deleted: true }, status: :ok
+  end
+end
+
+# A 3xx redirect (Post/Redirect/Get) is treated as a successful create, so the
+# claim is KEPT and a duplicate is still blocked. :create is baseline-guarded.
+class RedirectsController < ApplicationController
+  def create
+    redirect_to "/widgets", status: :see_other
+  end
+end
+
+# A clean guarded endpoint used only by the hooks scenario, so its recorded
+# detected/rejected events are unambiguous. :create is baseline-guarded.
+class HookedController < ApplicationController
+  def create
+    render_ok("hooked")
+  end
+end
+
+# Test-only: exposes the recorded hook invocations so the test can read them over
+# HTTP. Not part of the dedupe demo — it just reports what the hooks captured.
+class DebugController < ActionController::API
+  def hooks
+    render json: { events: HOOK_EVENTS }, status: :ok
+  end
+end
+
+ROUTES = ActionDispatch::Routing::RouteSet.new
+ROUTES.draw do
+  post   "/widgets"            => "widgets#create"
+  patch  "/widgets/:id"        => "widgets#update"
+  get    "/widgets"            => "widgets#index"
+
+  post   "/orders"             => "orders#create"
+  patch  "/orders/:id"         => "orders#update"
+  post   "/orders/:id/approve" => "orders#approve"
+
+  post   "/drafts"             => "drafts#create"
+  patch  "/drafts/:id"         => "drafts#update"
+
+  post   "/payments"           => "payments#create"
+
+  post   "/slow"               => "slow#create"
+
+  post   "/failures"           => "failures#create"
+  patch  "/failures/:id"       => "failures#update"
+
+  get    "/reads"              => "read#index"
+  delete "/reads/:id"          => "read#destroy"
+
+  post   "/redirects"          => "redirects#create"
+
+  post   "/hooked"             => "hooked#create"
+
+  get    "/_hooks"             => "debug#hooks"
+end
+
+run ROUTES