concerns_on_rails 1.15.0 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d0ca1b10759cf285948bef864e3cba343b3d1caa5e461b000af0486b4d51781
-  data.tar.gz: 1006768d58216c32a190c551ede050eb2e12ac24d13daf847600e83d1f219f52
+  metadata.gz: 5759f8cf9f86e11087369181f53f807875909047c17fe8abb19a5b6bafaae697
+  data.tar.gz: d6e34235431b2c54a36de7126b4829b9892b05f66f0fc6b476ff561731452100
 SHA512:
-  metadata.gz: 7b8c99595c6fbdd34ba4eb2ed011dee168c6178cffbee5bd1803195e83d5e2301bb87db99bc2dbf1143ba6d5e584f708d44aefbbea13248af2bc0d6eba0772d2
-  data.tar.gz: b43057a24fd64599ee62ef31dcbddd0daf3b985193a36dd02811c17721ebebf0e73f5793c73ffb41c98524ca9b5bec1a100c9c3619ccf8ceb896ce5ce11051cc
+  metadata.gz: 2b101b659f6d47f0adcface39ef7069a978d8342e6499661d358af12037c12fb1b7d317cdd075ca9b5593989df2941e121ecf46e02d51c11e4f445cdf91801dd
+  data.tar.gz: 984342a4be9bae7692c880bb2436de85cd86a3a0e8cd4ba1c167168db297bf4a0ce42a3a7025de910b7e33495d67e8352667ea302b8d47e12c1824cd7bd4ae31

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 <!-- CHANGELOG.md -->
 
+## 1.17.0 (2026-06-10)
+
+Two new concerns, hardened by two adversarial review rounds (in-memory state is restored when a raising lock/unlock hook rolls the write back, so retries can't silently no-op; a hook aborting via `ActiveRecord::Rollback` makes `lock_access!`/`unlock_access!` return false instead of a fake success; invalid-UTF-8 signature headers fail closed instead of raising). 679 examples, 0 failures.
+
+### Added
+- **Models::Lockable**: failed-attempt tracking + account lockout ("Devise lockable-lite") for apps on Rails 8 native auth / `has_secure_password`. `lockable_by attempts: :failed_attempts, locked_at: :locked_at, max_attempts: 5, unlock_in: 15.minutes, prefix:/suffix:` — `register_failed_attempt!` increments SQL-side (`update_counters`: atomic under concurrency, NULL-coalescing) and auto-locks at the threshold; `access_locked?` / `lock_expired?` / `lock_expires_at` / `attempts_remaining` readers are side-effect free with lazy expiry (the boundary instant counts as unlocked); `lock_access!` / `unlock_access!` persist via `update_columns` (validations/callbacks bypassed so an invalid record can still be locked) with `before/after_lock`, `before/after_unlock` hooks in a transaction; `reset_failed_attempts!` is the hook-free successful-login path; expiry-aware `.locked` / `.unlocked` scopes (affixable, Ruby-computed cutoff so the SQL stays portable). An expired lock is cleared quietly on the next failed attempt — no unlock hooks fire from an attacker's guess. The attempts column is validated to be an integer column. Zero new runtime dependencies.
+- **Controllers::WebhookVerifiable**: HMAC signature verification for inbound webhooks (Stripe/GitHub/Shopify and generic `:hex`/`:base64`). `verify_webhook *actions, secret:, scheme:, header:, tolerance:, digest:` appends rules (first match wins; no actions = catch-all); the `verify_webhook_signature!` before_action (public, skip-able) renders 401 (`webhook_signature_missing`/`webhook_signature_invalid`/`webhook_timestamp_stale`) or 400 (`webhook_signature_malformed`) and halts the action. Comparison is constant-time (digest-collapsed `secure_compare`, portable to Rails 5.0) and the attacker-controlled header is never decoded — garbage including invalid UTF-8 is scrubbed and fails closed instead of raising. Stripe: signs `"#{t}.#{body}"`, tries every `v1` (≤16), ignores unknown keys, first `t` feeds both the symmetric tolerance check (default 300s) and the payload so a re-stamped stale header stays dead. Secrets: String / callable (`instance_exec`'d per request, multi-tenant) / Array (rotation, any match passes); a secret resolving blank at request time raises `ArgumentError` (misconfiguration should page, not 401 into the provider's retry loop). `:shopify`/`:base64` encode via `pack("m0")` (no base64-gem dependency on Ruby 3.4). Delegates error bodies to `render_error` when Respondable is present. Zero new runtime dependencies.
+
+## 1.16.0 (2026-06-10)
+
+Two new concerns, hardened by an adversarial edge-case review. 574 examples, 0 failures.
+
+### Added
+- **Models::Auditable**: lightweight single-column change history ("paper_trail-lite"). `auditable_by :price, :status, into: :audit_log, actor: -> { Current.user&.email }, max_entries: 100` appends one JSON entry per changed field per save (creates record `from: nil`) into one text column — no extra tables, written in the same INSERT/UPDATE via `before_save`. Readers: `audit_trail`, `last_change_for(:field)`, `audited_changes_since(time)`, `clear_audit_trail!`. Tolerant JSON decode (corrupt column → `[]`), newest-N trimming (default 200), opt-in value truncation (`max_value_length:` stores the first N characters of long String values + `…`), values JSON-coerced (times → ISO8601 UTC, BigDecimal → precision-safe string, non-finite floats → `"NaN"`/`"Infinity"` strings), `"by"` omitted when no actor. Entries build on the persisted trail, so a save aborted by a later callback cannot duplicate entries on retry. Zero new runtime dependencies.
+- **Controllers::Idempotentable**: Stripe-style `Idempotency-Key` support with an injectable store (`self.idempotency_store = Rails.cache`; contract: `#read`, `#write(expires_in:, unless_exist:)`, `#delete` — no in-process default on purpose). `idempotent_actions :create, ttl: 24.hours, lock_ttl: 1.minute, header: "Idempotency-Key", required: false` claims each key atomically, caches 2xx–4xx responses and replays them with `X-Idempotency-Replayed: true`; concurrent duplicates get 409 + `Retry-After`, payload mismatches get 422 (`idempotency_key_reuse`, fingerprint overridable), 5xx/exceptions release the claim so retries re-execute. Keys are validated (≤255 chars, control characters rejected to prevent response-header injection via the echoed `X-Idempotency-Key`), SHA256-hashed, and scoped per `controller#action`. Error bodies delegate to `render_error` when Respondable is present. Zero new runtime dependencies.
+
 ## 1.15.0 (2026-06-10)
 
 A review-driven release: 23 correctness/safety fixes (each with a regression spec) and 7 backward-compatible enhancements. 510 examples, 0 failures.

data/README.md

@@ -43,6 +43,8 @@ Article.published.without_deleted.find("hello-world")
   - [Sanitizable](#-sanitizable) — opt-in HTML sanitization (XSS defense-in-depth)
   - [Maskable](#-maskable) — non-destructive display masking of sensitive fields
   - [Monetizable](#-monetizable) — integer-cents money columns (BigDecimal)
+  - [Auditable](#-auditable) — single-column change history ("paper_trail-lite")
+  - [Lockable](#-lockable) — failed-attempt tracking + account lockout
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -55,6 +57,8 @@ Article.published.without_deleted.find("hello-world")
   - [Authorizable](#-authorizable) — per-action 403 authorization gate (block-based)
   - [Throttleable](#-throttleable) — rate limiting with 429 + `X-RateLimit-*` headers
   - [Timezoneable](#-timezoneable) — per-request `Time.zone` from params / header / cookie
+  - [Idempotentable](#-idempotentable) — `Idempotency-Key` request replay (409 on concurrent duplicates)
+  - [WebhookVerifiable](#-webhookverifiable) — HMAC verification for inbound webhooks (Stripe/GitHub/Shopify)
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -64,7 +68,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Eighteen model concerns + eight controller concerns**, all production-ready
+- **Twenty model concerns + thirteen controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -935,6 +939,71 @@ product.formatted_price # => "$19.99"
 
 ---
 
+## 📜 Auditable
+
+Lightweight change history ("paper_trail-lite") stored as JSON entries in **one text column** on the same table — no extra tables, no versioning engine.
+
+```ruby
+class Product < ApplicationRecord
+  include ConcernsOnRails::Auditable
+
+  auditable_by :price, :status                       # default column :audit_log
+  # auditable_by :price, into: :history,
+  #              actor: -> { Current.user&.email },  # stamps "by" on each entry
+  #              max_entries: 50                     # keep the newest 50
+end
+
+product.update!(price: 200)
+product.audit_trail
+# => [{"field"=>"price", "from"=>100, "to"=>200, "at"=>"2026-06-10T12:34:56Z", "by"=>"admin@shop.com"}]
+product.last_change_for(:price)            # newest entry for one field
+product.audited_changes_since(1.day.ago)   # recent entries, oldest first
+product.clear_audit_trail!                 # wipe the column (skips callbacks)
+```
+
+One entry is recorded **per changed field per save** (creates record `"from" => nil`), appended in the same `INSERT`/`UPDATE` via `before_save` — zero extra queries.
+
+**Options**: `into:` (`:audit_log`), `actor:` (callable, `instance_exec`'d on the record; `"by"` omitted when absent), `max_entries:` (`200`; keeps the newest N, `nil` = unlimited), `max_value_length:` (`nil`; truncates long String `from`/`to` values to the first N characters + `…`).
+
+**Notes**
+- Writes that skip callbacks (`update_column(s)`, `touch`, `increment!`) are **not** audited; `save(validate: false)` is.
+- Values are JSON-coerced (times → ISO8601 UTC strings, `BigDecimal` → precision-safe numeric string); a corrupt column decodes as `[]` and is replaced on the next tracked save.
+- Per-record and bounded by design — reach for [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) when you need reify/undo or audit queries across models.
+
+---
+
+## 🔐 Lockable
+
+Failed-attempt tracking + **account lockout** ("Devise lockable-lite") for apps rolling their own authentication (Rails 8 auth generator / `has_secure_password`) — which ships **no brute-force protection** out of the box. Two columns on the model's own table; no tokens, no mailers.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Lockable
+
+  lockable_by max_attempts: 5, unlock_in: 15.minutes
+  # lockable_by attempts: :failed_logins, locked_at: :locked_until_at,
+  #             prefix: :account          # => .account_locked / .account_unlocked
+end
+
+user.register_failed_attempt!   # atomic SQL increment; locks at max_attempts
+user.access_locked?             # true while locked (lapses after unlock_in)
+user.attempts_remaining         # => 3   (for "3 attempts remaining" messaging)
+user.reset_failed_attempts!     # call on successful login
+user.lock_access!               # manual lock     (hooks: before/after_lock)
+user.unlock_access!             # manual unlock   (hooks: before/after_unlock)
+User.locked / User.unlocked     # expiry-aware scopes
+```
+
+**Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `prefix:` / `suffix:` (affix the scope names).
+
+**Notes**
+- The increment is SQL-side (`COALESCE(attempts, 0) + 1` via `update_counters`), so concurrent failures never lose updates and a NULL counter needs no column default; a locked account stops counting.
+- Expiry is **lazy**: readers and scopes treat a stale lock as unlocked but never write. The column is cleared by the next `unlock_access!` or failed attempt (quietly there — no unlock hooks fire from a failed login).
+- `lock_access!` / `unlock_access!` persist via `update_columns` — validations and AR callbacks deliberately bypassed so an otherwise-invalid record can still be locked (this also skips `updated_at`/`Auditable`). The `before/after_lock`, `before/after_unlock` hooks run in a transaction; `after_lock` is the place for the "account locked" email.
+- Reach for Devise's `lockable` when you need unlock tokens, unlock emails, or per-strategy unlocks.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1299,6 +1368,72 @@ Resolution order: `params[param]` → `Time-Zone` header → cookie (if enabled)
 
 ---
 
+## 🔁 Idempotentable
+
+Stripe-style **`Idempotency-Key`** support for mutating endpoints, with a **store-agnostic, injectable** backend. The first request with a key runs the action and caches the response; a retry **replays** the cached response; a concurrent duplicate gets **409**.
+
+```ruby
+class PaymentsController < ApplicationController
+  include ConcernsOnRails::Controllers::Idempotentable
+
+  self.idempotency_store = Rails.cache    # must support #read / #write(expires_in:, unless_exist:) / #delete
+
+  idempotent_actions :create, ttl: 24.hours, required: true
+end
+```
+
+Per-key lifecycle: claim atomically (`write unless_exist`, TTL `lock_ttl:`) → run action → cache 2xx–4xx responses for `ttl:`; 5xx and raised exceptions release the claim so the client can retry. Replays carry `X-Idempotency-Replayed: true`; duplicates in flight get 409 + `Retry-After`; reusing a key with a **different payload** gets 422 (`idempotency_key_reuse`, fingerprint overridable via `idempotency_fingerprint`).
+
+**Options**: `*actions` (allow-list, required), `ttl:` (`24.hours`), `lock_ttl:` (`1.minute`), `header:` (`"Idempotency-Key"`), `required:` (`false`).
+
+**Notes**
+- Cache keys are scoped per `controller#action` and the client key is SHA256-hashed, so the same key on different endpoints never collides.
+- There is **no in-process default store** on purpose: the first keyed request raises `ArgumentError` until you set `idempotency_store`.
+- When `Respondable` is included, the 400/409/422 bodies delegate to `render_error`.
+- Declare halting filters (authentication, `Throttleable`) **before** including this concern — a 401/403 rendered by an inner filter would be cached and replayed for the full TTL. Responses rendered by `rescue_from` handlers are never cached.
+- Keys must be ≤255 chars with no control characters (the raw key is echoed in `X-Idempotency-Key`); set `lock_ttl:` above the slowest declared action's worst case.
+
+---
+
+## 🪝 WebhookVerifiable
+
+HMAC **signature verification for inbound webhooks** — the receiving side of Stripe/GitHub/Shopify-style integrations. The action runs only when the signature over the **raw request body** verifies; otherwise a 401/400 is rendered and the action never executes.
+
+```ruby
+class WebhooksController < ApplicationController
+  include ConcernsOnRails::Controllers::WebhookVerifiable   # declare BEFORE Idempotentable
+
+  verify_webhook :stripe,  secret: -> { ENV["STRIPE_WEBHOOK_SECRET"] },    scheme: :stripe
+  verify_webhook :github,  secret: -> { ENV["GITHUB_WEBHOOK_SECRET"] },    scheme: :github
+  verify_webhook :shopify, secret: [ENV["NEW_SECRET"], ENV["OLD_SECRET"]], scheme: :shopify  # rotation
+  verify_webhook :custom,  secret: "s3cr3t", scheme: :hex, header: "X-Acme-Signature"
+  # verify_webhook secret: ...   # no actions = catch-all (declare specific rules first)
+
+  def stripe
+    event = JSON.parse(request.raw_post)   # parse the raw body — it is what was signed
+    # ...
+  end
+end
+```
+
+| Scheme | Header (default) | Format |
+|--------|------------------|--------|
+| `:github` | `X-Hub-Signature-256` | `sha256=<hex>` |
+| `:shopify` | `X-Shopify-Hmac-Sha256` | strict Base64 of the binary HMAC |
+| `:stripe` | `Stripe-Signature` | `t=<unix>,v1=<hex>[,v1=…]` — signs `"#{t}.#{body}"`, every `v1` tried, `tolerance:` rejects stale **and** future timestamps |
+| `:hex` / `:base64` | — (`header:` required) | plain hex / strict Base64 HMAC of the body |
+
+**Options**: `*actions` (none = catch-all; the first matching rule wins), `secret:` (String, callable `instance_exec`'d per request, or Array for rotation — any match passes), `scheme:` (`:hex`), `header:` (overrides the preset), `tolerance:` (Stripe only, `300`s default), `digest:` (`:sha256`; `:sha1`/`:sha512` for `:hex`/`:base64` only).
+
+**Notes**
+- Comparison is constant-time and the attacker-controlled header is **never decoded** — garbage (including invalid UTF-8 bytes) just fails with 401, it cannot raise.
+- A secret that resolves **blank at request time raises `ArgumentError`** — a misconfigured endpoint should page you, not 401 into the provider's silent retry loop.
+- Failure codes: `webhook_signature_missing` / `webhook_signature_invalid` / `webhook_timestamp_stale` → 401; `webhook_signature_malformed` (unparseable Stripe header) → 400. With `Respondable`, bodies delegate to `render_error`; override `webhook_verification_failed` to customize.
+- Declare **before** `Idempotentable` (a 401 cached by its around filter would be replayed) and before `Throttleable` (forged traffic shouldn't burn rate budget). Webhook endpoints also need `skip_before_action :verify_authenticity_token`.
+- In tests: `skip_before_action :verify_webhook_signature!`, or sign payloads for real with `OpenSSL::HMAC`. After a pass, `webhook_verified?` is true.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:
@@ -1334,7 +1469,7 @@ Both forms reference the same module, so you can freely mix them.
 | Association-cascade soft delete / sentinel-aware unique indexes | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
 | Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
 | Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
-| Audit trails / version history | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
+| Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
 
 `Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
 

data/lib/concerns_on_rails/controllers/idempotentable.rb

@@ -0,0 +1,300 @@
+require "active_support/concern"
+require "digest"
+require "json"
+
+module ConcernsOnRails
+  module Controllers
+    # Stripe-style `Idempotency-Key` support for mutating endpoints, with a
+    # store-agnostic, injectable backend. The first request with a key executes
+    # the action and caches the rendered response; a retry with the same key
+    # replays the cached response instead of re-running the action; a concurrent
+    # duplicate while the first is still in flight is halted with 409.
+    #
+    #   class PaymentsController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Idempotentable
+    #
+    #     self.idempotency_store = Rails.cache    # must support #read / #write(expires_in:, unless_exist:) / #delete
+    #
+    #     idempotent_actions :create, ttl: 24.hours, required: true
+    #   end
+    #
+    # Lifecycle per key (scoped to controller#action, so the same client key on
+    # different endpoints never collides):
+    #   * claim won  -> action runs; 2xx-4xx responses are cached for `ttl:`;
+    #                   5xx responses and raised exceptions release the claim so
+    #                   the client can retry.
+    #   * done       -> the cached status/body/content type is replayed with
+    #                   `X-Idempotency-Replayed: true`.
+    #   * in flight  -> 409 with code "idempotency_conflict" and `Retry-After`.
+    #   * same key, different request payload -> 422 "idempotency_key_reuse"
+    #     (override `idempotency_fingerprint` to customize payload matching).
+    #
+    # The claim is taken atomically via `write(..., unless_exist: true)`
+    # (memcached `add` / Redis `SET NX` through Rails.cache); a store without
+    # that atomicity is best-effort under concurrency. There is no in-process
+    # default store on purpose — configure one explicitly or the first keyed
+    # request raises ArgumentError. Note that responses rendered by
+    # `rescue_from` handlers bypass the around filter's success path and are
+    # never cached.
+    #
+    # IMPORTANT — callback ordering: declare halting filters (authentication,
+    # authorization, rate limiting) BEFORE including this module. A
+    # before_action that runs *inside* the around filter and halts (401/403)
+    # has its response cached and replayed for the full `ttl:` — the client
+    # cannot fix credentials and retry until it expires. Rails offers no
+    # reliable way for the around filter to detect a halted inner chain.
+    # Likewise set `lock_ttl:` above the worst-case duration of the slowest
+    # declared action — if the action outlasts the claim, a concurrent retry
+    # can win the expired key and execute the action a second time.
+    module Idempotentable
+      extend ActiveSupport::Concern
+
+      DEFAULT_HEADER = "Idempotency-Key".freeze
+      MAX_KEY_LENGTH = 255
+      IGNORED_FINGERPRINT_KEYS = %w[controller action format].freeze
+
+      included do
+        class_attribute :idempotency_rules, instance_accessor: false, default: []
+        class_attribute :idempotency_store, instance_accessor: false, default: nil
+        around_action :enforce_idempotency
+      end
+
+      module ClassMethods
+        # Declare idempotent actions. `ttl:` is the cached-response lifetime,
+        # `lock_ttl:` the in-flight claim lifetime (kept short so a crashed
+        # worker cannot wedge a key), `header:` the request header to read, and
+        # `required:` whether a missing key is a 400. Each call appends a rule;
+        # the first rule listing the current action wins.
+        def idempotent_actions(*actions, ttl: 86_400, lock_ttl: 60, header: DEFAULT_HEADER, required: false)
+          actions = actions.flatten.map(&:to_s)
+          validate_idempotent!(actions, ttl: ttl, lock_ttl: lock_ttl, header: header, required: required)
+
+          rule = { actions: actions, ttl: ttl.to_i, lock_ttl: lock_ttl.to_i, header: header.to_s, required: required }
+          self.idempotency_rules = idempotency_rules + [rule]
+        end
+
+        private
+
+        def validate_idempotent!(actions, ttl:, lock_ttl:, header:, required:)
+          prefix = "ConcernsOnRails::Controllers::Idempotentable"
+          raise ArgumentError, "#{prefix}: pass at least one action" if actions.empty?
+          raise ArgumentError, "#{prefix}: :ttl must be a positive duration" unless ttl.to_i.positive?
+          raise ArgumentError, "#{prefix}: :lock_ttl must be a positive duration" unless lock_ttl.to_i.positive?
+          raise ArgumentError, "#{prefix}: :header must be a non-blank String" if header.to_s.strip.empty?
+          raise ArgumentError, "#{prefix}: :required must be true or false" unless [true, false].include?(required)
+        end
+      end
+
+      # around_action entry point. Public so subclasses can override and specs
+      # can drive it directly with a block standing in for the action.
+      def enforce_idempotency(&)
+        rule = idempotency_rule_for_action
+        return yield unless rule
+
+        raw = read_idempotency_header(rule)
+        return idempotency_handle_missing_key(rule, &) if raw.nil?
+
+        key = raw.to_s.strip
+        unless valid_idempotency_key?(key)
+          return idempotency_error_response(message: "#{rule[:header]} is invalid (expected 1-#{MAX_KEY_LENGTH} characters).",
+                                            status: :bad_request, code: "idempotency_key_invalid")
+        end
+
+        @idempotency_key = key
+        run_with_idempotency(rule, key, &)
+      end
+
+      # The raw key sent for the matched rule (nil when absent). Handy for logging.
+      def idempotency_key
+        @idempotency_key
+      end
+
+      # Digest of the request payload, used to reject reusing one key for a
+      # different request. Public override point — e.g. for raw-body APIs:
+      #   def idempotency_fingerprint = Digest::SHA256.hexdigest(request.raw_post)
+      # Override it for multipart endpoints too: an uploaded file stringifies
+      # with its object id, so retried uploads never match and 422 — digest
+      # stable parts instead (e.g. params[:file]&.original_filename).
+      def idempotency_fingerprint
+        raw = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+        filtered = raw.reject { |k, _| IGNORED_FINGERPRINT_KEYS.include?(k.to_s) }
+        Digest::SHA256.hexdigest(JSON.generate(idempotency_deep_sort(filtered)))
+      end
+
+      # Public override point for how a cached response is replayed.
+      def replay_idempotent_response(record)
+        return unless respond_to?(:response) && response
+
+        emit_idempotency_replayed_header(true)
+        options = { body: record["body"], status: record["status"] }
+        options[:content_type] = record["content_type"] if record["content_type"]
+        render(options)
+      end
+
+      # Single funnel for all error outcomes. Uses Respondable's render_error
+      # when available, otherwise the same inline envelope as Throttleable.
+      def idempotency_error_response(message:, status:, code:)
+        return unless respond_to?(:response) && response
+
+        return render_error(message: message, status: status, code: code) if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: message, code: code } }, status: status
+      end
+
+      private
+
+      def idempotency_rule_for_action
+        action = respond_to?(:action_name) ? action_name.to_s : nil
+        return nil unless action
+
+        self.class.idempotency_rules.find { |rule| rule[:actions].include?(action) }
+      end
+
+      def idempotency_handle_missing_key(rule, &)
+        return yield unless rule[:required]
+
+        idempotency_error_response(message: "#{rule[:header]} header is required for this action.",
+                                   status: :bad_request, code: "idempotency_key_missing")
+      end
+
+      def valid_idempotency_key?(key)
+        # Control characters are rejected because the raw key is echoed in the
+        # X-Idempotency-Key response header — CR/LF would enable header
+        # injection on servers that don't validate header values (Rack 2).
+        !key.empty? && key.length <= MAX_KEY_LENGTH && !key.match?(/[[:cntrl:]]/)
+      end
+
+      def run_with_idempotency(rule, key, &)
+        store = idempotency_store!
+        cache_key = idempotency_cache_key(key)
+        fingerprint = idempotency_fingerprint
+        emit_idempotency_key_header(key)
+
+        claim = { "state" => "in_flight", "fingerprint" => fingerprint, "claimed_at" => Time.now.to_i }
+        if store.write(cache_key, claim, expires_in: rule[:lock_ttl], unless_exist: true)
+          idempotency_execute_and_store(store, cache_key, rule, fingerprint, &)
+        else
+          idempotency_resolve_existing(store, cache_key, rule, fingerprint)
+        end
+      end
+
+      def idempotency_execute_and_store(store, cache_key, rule, fingerprint)
+        emit_idempotency_replayed_header(false)
+        completed = false
+        begin
+          yield
+          completed = true
+        ensure
+          # Covers raise and throw alike, so a retry can re-execute.
+          store.delete(cache_key) unless completed
+        end
+
+        status = idempotency_response_status
+        return store.delete(cache_key) if status >= 500
+
+        record = { "state" => "done", "status" => status, "body" => idempotency_response_body,
+                   "content_type" => idempotency_response_content_type, "fingerprint" => fingerprint }
+        store.write(cache_key, record, expires_in: rule[:ttl])
+      end
+
+      def idempotency_resolve_existing(store, cache_key, rule, fingerprint)
+        record = store.read(cache_key)
+
+        if record && record["fingerprint"] != fingerprint
+          return idempotency_error_response(message: "#{rule[:header]} was already used with a different request payload.",
+                                            status: :unprocessable_entity, code: "idempotency_key_reuse")
+        end
+
+        return replay_idempotent_response(record) if record && record["state"] == "done"
+
+        # In flight — or the claim expired between our failed write and this
+        # read (rare); answering 409 is the conservative, retry-safe choice.
+        idempotency_conflict_response(rule)
+      end
+
+      def idempotency_conflict_response(rule)
+        response.set_header("Retry-After", rule[:lock_ttl].to_s) if respond_to?(:response) && response
+        idempotency_error_response(message: "A request with this #{rule[:header]} is already in progress.",
+                                   status: :conflict, code: "idempotency_conflict")
+      end
+
+      def read_idempotency_header(rule)
+        return nil unless respond_to?(:request) && request.respond_to?(:headers) && request.headers
+
+        request.headers[rule[:header]]
+      end
+
+      def idempotency_cache_key(key)
+        # The user key is hashed so any validated key is safe in any backend
+        # (memcached limits key length and bans whitespace/control characters).
+        "idempotentable:#{idempotency_scope}:#{Digest::SHA256.hexdigest(key)}"
+      end
+
+      def idempotency_scope
+        controller = respond_to?(:controller_path) ? controller_path : self.class.name || "anonymous"
+        action = respond_to?(:action_name) ? action_name.to_s : ""
+        "#{controller}##{action}"
+      end
+
+      def idempotency_store!
+        store = self.class.idempotency_store
+        return store if store
+
+        raise ArgumentError,
+              "ConcernsOnRails::Controllers::Idempotentable: no store configured. " \
+              "Set `self.idempotency_store = Rails.cache` " \
+              "(must support #read, #write(expires_in:, unless_exist:) and #delete)."
+      end
+
+      def idempotency_response_status
+        return 200 unless respond_to?(:response) && response.respond_to?(:status)
+
+        response.status.to_i
+      end
+
+      def idempotency_response_body
+        return nil unless respond_to?(:response) && response.respond_to?(:body)
+
+        response.body
+      end
+
+      def idempotency_response_content_type
+        return nil unless respond_to?(:response) && response
+
+        # media_type (real Rails) excludes the charset; the harness only has content_type.
+        if response.respond_to?(:media_type) && response.media_type
+          response.media_type
+        elsif response.respond_to?(:content_type)
+          response.content_type
+        end
+      end
+
+      def emit_idempotency_key_header(key)
+        response.set_header("X-Idempotency-Key", key) if respond_to?(:response) && response
+      end
+
+      def emit_idempotency_replayed_header(replayed)
+        response.set_header("X-Idempotency-Replayed", replayed.to_s) if respond_to?(:response) && response
+      end
+
+      # Deterministic JSON regardless of param insertion order: hashes become
+      # sorted [key, value] pairs, arrays keep their (significant) order, and
+      # non-JSON-primitive leaves are stringified so nothing can raise.
+      def idempotency_deep_sort(value)
+        case value
+        when Hash then value.map { |k, v| [k.to_s, idempotency_deep_sort(v)] }.sort_by(&:first)
+        when Array then value.map { |v| idempotency_deep_sort(v) }
+        else idempotency_scalar(value)
+        end
+      end
+
+      def idempotency_scalar(value)
+        case value
+        when Float then value.finite? ? value : value.to_s # JSON.generate raises on NaN/Infinity
+        when nil, true, false, Integer, String then value
+        else value.to_s
+        end
+      end
+    end
+  end
+end