concerns_on_rails 1.14.1 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cbda4a7f45769f7997d0f5367d04a594946bee53e45e759a461bb73a535522e
-  data.tar.gz: 692b5092f4b784a113dd09935eda88fc16bd1f0a484f349ae53c77f8b945b14d
+  metadata.gz: dbe5bebe66a84e336f6dbffff99b12d12ed65f6238ea000b9a149908b1a78e0c
+  data.tar.gz: 8478287a2750b501288e02e30394cfb79a45e2208190c14e8fce945457229e2b
 SHA512:
-  metadata.gz: 215b94501afdbb59bfed5633eaa649efb244e2c9a01e21ac30a63ea1bf4de0ffa9f5b2c71da92d5fd980f90cc7d8ef397f17fa0c708d16be31059f7d29facf91
-  data.tar.gz: 3778aa7588aef6315a40707fdfd1d01b2092d65fb4b5717a16a4ac4f81300f23086aa4a3f0133d86a84d84acbb9b210a7ee45f23d2806e6c9d8ade8797238733
+  metadata.gz: 06bd9e4b6a3493047ea48b60f2ff75517bb3d117c8cbe4712071f7464db173c8cb73f7a3763d22a4376f458ba1d85deffca47648544ec4879642d14dc40e6a78
+  data.tar.gz: 042252611fb6ef6a41c671d3cf2a17e29ee7dcf82349f8f84b22d04274ebbcd2c48c23a2b6a03291325e0d072daedf29981b84bc2fb0a11a6cf832d5f79a572e

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 <!-- CHANGELOG.md -->
 
+## 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.
+
+### Fixed
+- **Controllers::SecureHeadable**: `content_security_policy_for(report_only: true)` no longer silently drops the policy block — the policy is defined via `content_security_policy` and report-only mode is toggled separately (a report-only rollout previously registered no policy at all).
+- **Controllers::Authorizable**: `require_role` / actor resolution now find a private or `helper_method` `current_user` (`respond_to?(.., true)`), so Devise-style private `current_user` is no longer denied.
+- **Controllers::Sortable**: uses `reorder` so the requested sort replaces a model `default_scope` ORDER BY instead of becoming a silent secondary key.
+- **Controllers::Paginatable**: the total count no longer breaks on grouped relations (it returned a Hash); it collapses to the group count.
+- **Controllers::Filterable**: a nested-hash param in direct-where mode no longer raises a user-triggerable 500 — non-scalar values are ignored.
+- **Controllers::Localizable**: the `Accept-Language` parser honors q-values (rejects `q=0`, orders by preference) per RFC 7231.
+- **Controllers::ErrorHandleable**: the 404 handler renders a generic message instead of the raw `RecordNotFound` message, which leaked the model class name and queried attribute/value.
+- **Models::SoftDeletable**: `deleted_within` uses an explicit `>=` predicate (the previous endless range was unsupported on Rails 5.x); `soft_delete_all` / `restore_all` roll the whole batch back when a record fails.
+- **Models::Sluggable**: backfills a blank slug on save even when the source is unchanged, and no longer overwrites an explicitly-assigned slug.
+- **Models::Publishable**: scopes branch on the column type so a boolean publishable column uses equality predicates instead of nonsensical timestamp comparisons.
+- **Models::Hashable**: validates that `length` is positive; `:integer` drops dead padding code.
+- **Models::Taggable**: `tagged_with` matches consistently (all branches use LIKE) and escapes the delimiter so a wildcard delimiter matches literally.
+- **Models::Monetizable** / **Support::Money**: no spurious `-` for amounts that round to zero; `subunit_to_unit: 0` is rejected.
+- **Models::Sequenceable**: the generation-time clock is memoized so a record's period anchor stays consistent (no boundary straddle).
+- **gemspec**: `spec.metadata` is merged rather than reassigned, preserving the `license` key.
+
+### Added
+- **Models::Activatable** / **Models::Expirable**: `prefix:` / `suffix:` options to affix scope names, so `.active` / `.expired` can coexist with the same-named scopes from sibling concerns on one model.
+- **Models::Publishable**: `before/after_publish` and `before/after_unpublish` lifecycle hooks.
+- **Models::Stateable**: `before/after_transition` hooks fired by guarded `<event>!` transitions.
+- **Models::Hashable**: `unique: true` retries on an in-Ruby collision before insert (parity with Tokenizable).
+- **Controllers::Sortable**: applies multiple whitelisted columns from a comma-separated `params[:sort]`.
+- **Controllers::Paginatable**: `pagination_meta(relation)` for body-based pagination (composes with `Respondable`'s `meta:`).
+
+### Changed
+- **Controllers::ErrorHandleable**: the default 404 message is now generic (`"Resource not found"`); override `handle_record_not_found` to surface detail in non-production environments.
+
+### Docs
+- Rewrote `CLAUDE.md` to cover all 29 concerns and 7 support modules, the model/controller layout, the macro conventions, the supported dependency ranges, and the release process.
+- Noted native Rails 7.1+ alternatives (`normalizes`, `generates_token_for`) in `Normalizable` / `Tokenizable`.
+
 ## 1.14.1 (2026-06-07)
 
 ### Fixed

data/README.md

@@ -43,6 +43,7 @@ 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")
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -55,6 +56,7 @@ 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)
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -64,7 +66,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Eighteen model concerns + eight controller concerns**, all production-ready
+- **Nineteen model concerns + twelve 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 +937,39 @@ 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.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1299,6 +1334,33 @@ 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.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:
@@ -1334,7 +1396,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/authorizable.rb

@@ -50,8 +50,11 @@ module ConcernsOnRails
 
           wanted = roles.map(&:to_s)
           check = proc do
-            actor = respond_to?(via) ? send(via) : nil
-            actor.respond_to?(role_method) && wanted.include?(actor.public_send(role_method).to_s)
+            # respond_to?(via, true): current_user is usually private (Devise) or
+            # a helper_method (which keeps it private on the instance), so the
+            # default public-only check would resolve nil and deny everyone.
+            actor = respond_to?(via, true) ? send(via) : nil
+            actor.respond_to?(role_method, true) && wanted.include?(actor.send(role_method).to_s)
           end
           add_authorization_rule(check: check, only: only, except: except, status: status, message: message)
         end
@@ -113,7 +116,8 @@ module ConcernsOnRails
       end
 
       def authorization_actor
-        respond_to?(:current_user) ? current_user : nil
+        # include_private: true — current_user is typically private/helper_method.
+        respond_to?(:current_user, true) ? current_user : nil
       end
 
       def authorization_action_name

data/lib/concerns_on_rails/controllers/error_handleable.rb

@@ -30,9 +30,12 @@ module ConcernsOnRails
         rescue_from "ActiveRecord::RecordInvalid",        with: :handle_record_invalid
       end
 
-      def handle_record_not_found(error)
+      def handle_record_not_found(_error)
+        # Use a generic message: the raw RecordNotFound message leaks the model
+        # class name and the queried attribute/value to API clients. Subclasses
+        # can override this method to surface detail in non-production envs.
         render_error_envelope(
-          message: error.message,
+          message: "Resource not found",
           code: "not_found",
           status: :not_found
         )

data/lib/concerns_on_rails/controllers/filterable.rb

@@ -60,10 +60,24 @@ module ConcernsOnRails
           options[:with].call(relation, value)
         elsif options[:scope]
           relation.public_send(options[:scope])
-        else
+        elsif filterable_scalar?(value)
           relation.where(field => value)
+        else
+          # A nested/structured param (e.g. ?status[gt]=5) in direct-where mode
+          # would raise TypeError ("can't quote Hash") and surface as a 500.
+          # Ignore it instead — hash/array shaping must go through a `with:` lambda.
+          relation
         end
       end
+
+      # Scalars (and arrays, which AR turns into `IN (...)`) are safe to pass to
+      # .where; a Hash / ActionController::Parameters is not.
+      def filterable_scalar?(value)
+        return false if value.is_a?(Hash)
+        return false if defined?(ActionController::Parameters) && value.is_a?(ActionController::Parameters)
+
+        true
+      end
     end
   end
 end

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

data/lib/concerns_on_rails/controllers/localizable.rb

@@ -77,14 +77,36 @@ module ConcernsOnRails
       end
 
       def parse_accept_language(header, allowed)
-        header.split(",").each do |part|
-          lang = part.split(";").first.to_s.strip.split("-").first
+        ranked_accept_languages(header).each do |lang|
           match = match_locale(lang, allowed)
           return match if match
         end
         nil
       end
 
+      # Languages from an Accept-Language header, q=0 dropped, highest-q first
+      # (RFC 7231 preference order).
+      def ranked_accept_languages(header)
+        pairs = header.split(",").filter_map do |part|
+          token, *params = part.split(";").map(&:strip)
+          quality = accept_language_quality(params)
+          next if quality <= 0.0
+
+          lang = token.to_s.split("-").first
+          [lang, quality] if lang.present?
+        end
+        pairs.sort_by { |(_lang, quality)| -quality }.map(&:first)
+      end
+
+      # The q-value (relative quality) of an Accept-Language part: 1.0 when
+      # absent, 0.0 when malformed. q=0 means "not acceptable" and is dropped.
+      def accept_language_quality(params)
+        qparam = params.find { |p| p.start_with?("q=") }
+        return 1.0 unless qparam
+
+        Float(qparam[2..], exception: false) || 0.0
+      end
+
       def match_locale(candidate, allowed)
         return nil if candidate.blank?
 

data/lib/concerns_on_rails/controllers/paginatable.rb

@@ -41,7 +41,10 @@ module ConcernsOnRails
         per_page = pagination_per_page
         offset = (page - 1) * per_page
 
-        total = relation.except(:order, :limit, :offset).count
+        counted = relation.except(:order, :limit, :offset).count
+        # `.count` on a grouped relation returns a Hash (group => count); for
+        # offset pagination the meaningful total is the number of groups.
+        total = counted.is_a?(Hash) ? counted.length : counted
         total_pages = per_page.positive? ? (total.to_f / per_page).ceil : 0
 
         records = relation.limit(per_page).offset(offset)
@@ -50,6 +53,21 @@ module ConcernsOnRails
         records
       end
 
+      # Pagination metadata for a relation WITHOUT applying limit/offset — handy
+      # for body-based pagination (compose with Respondable's `meta:`).
+      def pagination_meta(relation)
+        page = pagination_page
+        per_page = pagination_per_page
+        counted = relation.except(:order, :limit, :offset).count
+        total = counted.is_a?(Hash) ? counted.length : counted
+        {
+          total: total,
+          page: page,
+          per_page: per_page,
+          total_pages: per_page.positive? ? (total.to_f / per_page).ceil : 0
+        }
+      end
+
       private
 
       def pagination_page

data/lib/concerns_on_rails/controllers/secure_headable.rb

@@ -85,11 +85,13 @@ module ConcernsOnRails
                   "ActionController::ContentSecurityPolicy (Rails 5.2+)"
           end
 
-          if report_only
-            content_security_policy_report_only(true, **action_opts, &block)
-          else
-            content_security_policy(**action_opts, &block)
-          end
+          # The policy block is ONLY accepted by content_security_policy; the
+          # report-only variant is a flag toggle that takes no block. So always
+          # define the policy via content_security_policy, then additionally mark
+          # it report-only when requested — otherwise a report-only rollout would
+          # silently register no policy at all (the block would be dropped).
+          content_security_policy(**action_opts, &block)
+          content_security_policy_report_only(true, **action_opts) if report_only
         end
       end