concerns_on_rails 1.21.1 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87a3ceebf2b9eb0f8a00c9d6a8cc57d8f50c8b1ff698be887aef42da64eb08c3
-  data.tar.gz: 1a82dd3dbe363e65f3a0d91c66cb453d54415032def91e90a388663ce2e90dab
+  metadata.gz: 7414e40bd04fc80a1b87b4c27b908ff169c5a9c2f9c50e66d8ab8d75198b9f40
+  data.tar.gz: 6f458ab30c720e633cd50f34515b7941ec9b6b8a8ef208f3beed909860ac1d9f
 SHA512:
-  metadata.gz: ebfb6e59e582240aab7bc0fe18e64e48f1f291f482b38df2dac97c3cc843f5731857594724868484fee75b9269ccaca923f6d229d862b3ce4ddfdf49c3f9aa27
-  data.tar.gz: 53d1b47d39588d102a4b6527b43b1801a1f87c47c1da7a67b823fb2138160e0dc8e1de9ea6d3b16070a2a33ca247a88832556de01e512b8ac474a9b5de288b6e
+  metadata.gz: dbbcf38ca1645b801c05e8949f869e587752607bb0d679c279eeac2bc8904c446d7da7ee865498b8578ca5d1d8212477b60cb840d0e3c53e1a1d9593065805af
+  data.tar.gz: 524c14d7bd3e5824c0d266a3ab84e13cd21d622d7637dc4bde38225ff40e88d24559eb36055c16eaa60edb53b99c025c96effa4a458e1701b36a0826bd8a12b5

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 <!-- CHANGELOG.md -->
 
+## 1.22.0 (2026-07-26)
+
+A fixes-and-optimizations release driven by a full-library review of all 40 concerns: one data-loss bug, three request-crashing 500s verified through real ActionController dispatch, security headers restored on rescued error responses, a fail-open authorization path closed, and the gem's largest performance defect (unmemoized PBKDF2 per encrypted-value access) eliminated. 1031 examples, 0 failures.
+
+### Fixed
+- **Models::SoftDeletable**: `really_destroy_all` now hard-deletes only the records matching the calling relation (soft-deleted included) — previously it ran `unscoped.delete_all` and deleted the ENTIRE table regardless of scope (`User.where(account_id: 1).really_destroy_all` wiped every account). Note `unscope` also drops a caller's own predicate on the soft-delete column, so `only_deleted.really_destroy_all` widens to the whole relation — use `soft_deleted.delete_all` to purge trash.
+- **Controllers::Includable**: sparse fieldsets (`?fields[articles]=id,title`) no longer 500 — in a real controller `params[:fields]` is an `ActionController::Parameters`, which has no `each_with_object`; every documented fieldsets request raised `NoMethodError`. Verified through a new real-ActionController integration harness.
+- **Controllers::Paginatable / CursorPaginatable**: `?page[]=1`, `?per_page[x]=5` and friends no longer 500 — untrusted param reads route through the new `Support::ScalarParam` (Filterable's guard, now shared; Filterable also rejects arrays *containing* nested hashes, the `?status[][x]=1` shape).
+- **Controllers::SecureHeadable**: security headers are now also applied via `prepend_before_action` — Rails skips `after_action` callbacks entirely when `rescue_from` handles an exception, so every handled 404/422/500 previously shipped with NO security headers. (Opting out now requires `skip_before_action :apply_secure_headers` alongside the existing `skip_after_action`.)
+- **Controllers::Cacheable**: `no_store` policies are likewise applied early, so rescued error responses on `no_store` endpoints carry `Cache-Control: no-store`; positive freshness deliberately stays post-action (a rescued 500 must never become CDN-cacheable). `stale_resource?` no longer writes ETag/Last-Modified validators for unsafe (non-GET/HEAD) requests, and the 304 path is a single write.
+- **Controllers::Authorizable**: fails CLOSED — a denial that cannot be rendered (no response object) now raises instead of silently letting the action run; `require_role` supports actors whose role method returns an Array (`roles: ["admin"]` previously stringified and was always denied).
+- **Controllers::Localizable**: regional locales match — `Accept-Language: fr-CA` now tries the full tag before falling back to the primary subtag (previously the region was discarded, so `available: [:"fr-CA"]` could never match).
+- **Controllers::Throttleable**: the first-hit seed uses `unless_exist:` so two concurrent first requests can't under-count the window; a nil/blank discriminator (e.g. `-> { current_user&.id }` on an anonymous request) raises instead of collapsing every client into one shared bucket.
+- **Controllers::Idempotentable**: the 409 conflict's `Retry-After` reports the remaining lock time (from the claim's `claimed_at`) instead of the full `lock_ttl`.
+- **Controllers::Deprecatable**: `link:`/`successor:` values are validated against control characters and `<`/`>` at macro time (Link-header injection).
+- **Support::ColumnGuard** (all 24 model concerns): macros no longer raise when the schema is unreachable — models using these concerns previously could not even load without a migrated database, breaking `db:create`, fresh `db:migrate`, `assets:precompile`, and CI bootstrap. Validation is skipped (never silently for a *reachable* schema with a missing column) and the guard is shared with CounterCacheable/Aliasable/Storable, which had each hand-rolled their own.
+- **Models::Sortable**: a bare `sortable_by` no longer crashes with `NoMethodError` (uses the documented `:position` default); the `default_scope` no longer re-validates the schema on every relation construction; new `default_scope: false` opt-out with a `sorted` scope for explicit ordering.
+- **Models::Monetizable**: the money setter casts garbage input (`"abc"`, `""`) to nil — ActiveModel convention — instead of raising `ArgumentError` out of a form assignment.
+- **Models::Encryptable**: `where_<field>(nil)` / `find_by_<field>(nil)` return `none`/nil instead of matching every row without a fingerprint; encrypted field names now register with Rails' parameter filtering through a live registry + railtie (`before: "active_record.set_filter_attributes"`), so redaction works with boot-time snapshots (ActiveRecord `filter_attributes`, lograge-style initializers) and lazily-loaded model classes.
+- **Models::Sequenceable**: with `reset:` enabled, `created_at` is pinned to the period-anchor instant during `before_create`, so a row can no longer be numbered for one year/month/day but timestamped into the next.
+- **Models::Sluggable**: the slug column itself is validated at macro time (a missing `slug` column previously failed at first save with an opaque friendly_id error).
+- **Models::Schedulable**: `reschedule!` accepts either/both keywords (single-column windows no longer fabricate the missing kwarg) and raises when a value targets an unconfigured column instead of silently dropping it.
+- **Models::CounterCacheable**: `touch: true` raises at macro time on Rails < 6.0 (`update_counters` lacks the option there and would read it as a column named `touch`).
+
+### Changed
+- **Models::SoftDeletable**: `soft_delete_all` / `restore_all` (and the `destroy_all` alias) now return the Integer count of records transitioned and raise `ActiveRecord::RecordNotSaved` (rolling the batch back) when a record fails — previously the rollback happened silently and the methods returned nil/records. With `touch: false` and no overridden hooks both collapse to a single `UPDATE`.
+- **Models::Publishable / Stateable**: lifecycle hooks now share one transaction with the state write (SoftDeletable's pattern) — a raising `after_publish`/`after_transition` rolls the change back instead of leaving it committed with the side effect half-done. `publish_at!` now fires the publish hooks.
+- **Models::Encryptable + Auditable**: the encrypted×audited overlap is rejected at macro time from BOTH declaration orders (Auditable gained the mirror guard); the per-save backstop callback is gone.
+- **Models::Hashable / Tokenizable**: `regenerate_<field>!` goes through the same uniqueness path as create-time assignment (precheck + bounded retry on `ActiveRecord::RecordNotUnique` via the new `Support::UniqueRetry`) — previously one blind `update!` with no collision handling. Hashable's `type: :integer` now generates fixed-width codes (`length: 6` is always 6 digits).
+- **Effective Rails support documented**: the gemspec keeps `rails >= 5.0, < 9`, but Ruby 3.2 (required) means Rails 7.0.4+ in practice; README updated accordingly.
+
+### Performance
+- **Support::Encryptor**: PBKDF2-derived keys are memoized (bounded, mutex-guarded, keyed by digest+salt+iterations) — previously EVERY encrypt/decrypt/blind-index call re-ran the 65,536-iteration KDF, turning a 200-row load of one encrypted column into seconds of key stretching. `configure_encryption` purges the cache.
+- **Models::Storable**: per-record decode memoization — readers/writers/dirty-checks/validation shared one `JSON.parse` per raw column value instead of re-parsing per key access (a ten-key form save cost dozens of parses). Read-back semantics are byte-identical (pinned by spec); the native-hash column detection is now mutex-guarded and never caches a negative result taken without a reachable schema.
+- **Models::Auditable**: saves that touch no tracked field skip building the changes hash (`will_save_change_to_attribute?` pre-check); `audit_trail` is memoized per raw column value (returns a fresh Array each call; entry hashes shared, treat as read-only).
+- **Controllers::Paginatable**: `paginated` + `pagination_meta` (no argument) now share one memoized COUNT — the documented records+meta composition ran the identical COUNT twice. The COUNT also strips `:select` and uses `count(:all)`, so custom SELECT lists and DISTINCT relations no longer produce invalid SQL or skewed totals.
+- **Models::Stateable**: the state default uses `attribute ... default:` instead of an `after_initialize` that ran for every row materialized from the database. (Edge: `Model.new(state_field => nil)` now keeps the explicit nil.)
+- **Models::CounterCacheable**: `recount_counter_caches!` runs in a transaction (a crash mid-repair could previously leave every counter zeroed) and groups parents by tally value — O(distinct counts) UPDATEs instead of one per parent row.
+- **Models::Normalizable / Addressable**: normalization skips fields that are not part of the current save on persisted records; `resolved_country` is memoized per raw value (was computed three times per validation cycle).
+- **Controllers::Localizable / Timezoneable / Deprecatable / CursorPaginatable**: per-request memoization of the resolved locale/zone/deprecation rule; the timezone wrapper is skipped when it would be a no-op; the row-predicate adapter check is cached per model class.
+- **Support::RandomValue / Money**: batched CSPRNG draws with rejection sampling (one `SecureRandom` call per token instead of per character); single-pass thousands delimiter.
+
+### Internal
+- New support modules: `ScalarParam` (shared untrusted-param coercion), `UniqueRetry` (bounded `RecordNotUnique` retry — also usable directly: `UniqueRetry.with_retries { Invoice.create!(attrs) }`), `ErrorEnvelope` (the `render_error`-or-inline dance, previously hand-copied across seven controller concerns — custom `render_error(message:, status:, code:)` overrides keep working), `FilterParameterRegistry` + `ConcernsOnRails::Railtie`.
+- `ConcernsOnRails.deprecator` / `.encryption` / `.filter_parameter_registry` memoization is now thread-safe; every concern file explicitly requires the support modules it uses (files are self-contained under direct `require`).
+- New real-ActionController integration harness (`spec/support/integration_harness.rb`) — the dependency-free FakeController cannot reproduce `ActionController::Parameters` or `rescue_from` semantics, which is how the fixed 500s previously stayed green; regression specs now assert mechanisms (statement counts, parse counts, KDF invocations) through real dispatch.
+
 ## 1.21.1 (2026-07-18)
 
 Blind-index support for Models::Encryptable, making encrypted fields queryable by exact match — the follow-up promised in 1.21.0. 991 examples, 0 failures.

data/README.md

@@ -65,6 +65,7 @@ Article.published.without_deleted.find("hello-world")
 | [🪞 Aliasable](#-aliasable) | Full read / write / query association aliases |
 | [⚙️ Storable](#-storable) | Typed accessors over one JSON column ("store_attribute-lite") |
 | [🧮 CounterCacheable](#-countercacheable) | Conditional denormalized counters ("counter_culture-lite") |
+| [🔏 Encryptable](#-encryptable) | Transparent field encryption (AES-256-GCM) + blind-index lookups |
 
 ### 🎮 Controller concerns
 
@@ -91,7 +92,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Twenty-three model concerns + sixteen controller concerns**, all production-ready
+- **Twenty-four model concerns + sixteen 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
@@ -104,7 +105,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.11"
+gem "concerns_on_rails", "~> 1.22"
 ```
 
 Or pull the latest from GitHub:
@@ -124,7 +125,7 @@ bundle install
 ## 🧪 Compatibility
 
 - **Ruby**: 3.2+
-- **Rails**: 5.0 through 8.x
+- **Rails**: declared 5.0 through 8.x — in practice the Ruby 3.2 requirement means Rails 7.0.4+ is what can actually install the gem; the test suite runs against Rails 7.1
 
 ---
 
@@ -325,13 +326,17 @@ User.unscoped             # everything (deleted + non-deleted)
 **Bulk operations**
 
 ```ruby
-User.soft_delete_all      # soft-deletes all matching records (explicit — preferred)
-User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility)
-User.really_destroy_all   # hard-deletes all matching records
-User.restore_all          # restores all soft-deleted records
+User.soft_delete_all      # soft-deletes all matching records; returns the count (explicit — preferred)
+User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility; returns a count, not records)
+User.really_destroy_all   # hard-deletes the records matching the CURRENT relation (soft-deleted included)
+User.restore_all          # restores the matching soft-deleted records; returns the count
 ```
 
-All of these run in a transaction, so a raising hook rolls the whole batch back.
+A record that fails to transition raises `ActiveRecord::RecordNotSaved` and rolls the whole
+batch back. With `touch: false` and no overridden hooks, `soft_delete_all` / `restore_all`
+collapse to a single `UPDATE`. Note that `really_destroy_all` peels the soft-delete
+predicate off the relation, so `only_deleted.really_destroy_all` widens to the whole
+relation — purge trash with `User.soft_deleted.delete_all` instead.
 
 **Lifecycle hooks** — override these methods on the model:
 
@@ -1129,6 +1134,39 @@ Counters are adjusted with `update_counters` (a single atomic SQL `COALESCE(col,
 
 ---
 
+## 🔏 Encryptable
+
+Transparent per-field encryption for sensitive columns (SSN, DOB, cards) — AES-256-GCM on stdlib OpenSSL, zero new dependencies. Reads and writes stay plaintext in memory; the DB column holds a versioned, authenticated Base64 envelope.
+
+```ruby
+ConcernsOnRails.configure_encryption { |c| c.key = ENV["ENCRYPTION_KEY"] }
+
+class Patient < ApplicationRecord
+  include ConcernsOnRails::Models::Encryptable
+
+  encryptable :ssn, :notes                 # transparent string encryption
+  encryptable :dob, type: :date            # decrypts back to a Date
+  encryptable :email, blind_index: true    # + a queryable fingerprint column
+end
+
+patient.ssn                          # => "123-45-6789" (plaintext in memory)
+patient.ssn_ciphertext               # => "AQEA..." (what's actually at rest)
+patient.ssn_encrypted?               # => true
+Patient.find_by_email("a@b.com")     # exact-match lookup via the blind index
+Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
+```
+
+**Options** (`encryptable *fields, …`, repeatable): `type:` (cast the decrypted value — `:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`), `key:` (per-field override; a String or lazy Proc), `blind_index:` (`true`, or `{ column:, expression: }` — maintains a deterministic keyed-HMAC companion column, default `<field>_bidx`, for equality lookups; `expression:` normalizes symmetrically on write and query).
+
+**Notes**
+- The declared column must be `text`/binary (it stores an opaque envelope, not the logical type); a blind-index column holds a 64-char hex digest — add an index on it.
+- Ciphertext is non-deterministic (random IV), so `where(ssn: ...)` matches nothing — query through a blind index. `nil` stays `nil`; presence checks work normally.
+- Never `update_column(s)` an encrypted field — that bypasses the type and writes raw plaintext. Declaring a field with both `encryptable` and `auditable_by` raises (either order).
+- Wrong key / tampered ciphertext / malformed envelope raise `Encryption::DecryptionError`. Encrypted field names are auto-registered with Rails' `filter_parameters` (via the gem's railtie), so they're redacted from request logs.
+- Reach for [`lockbox`](https://github.com/ankane/lockbox) or Rails 7+ native `encrypts` when you need key rotation today or Rails-managed key infrastructure (rotation is planned — the envelope already reserves the `key_id` byte).
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1700,6 +1738,7 @@ Both forms reference the same module, so you can freely mix them.
 | 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 |
 | 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) |
+| Field encryption with managed key rotation / Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
 
 `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.
 
@@ -1711,7 +1750,7 @@ Both forms reference the same module, so you can freely mix them.
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.11.2.gem      # install locally
+gem install ./concerns_on_rails-1.22.0.gem      # install locally
 ```
 
 The test suite uses an in-memory SQLite database and a lightweight `FakeController` harness for controller-concern specs — no Rails routes or boot required.

data/lib/concerns_on_rails/controllers/authorizable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 
 module ConcernsOnRails
   module Controllers
@@ -54,7 +55,11 @@ module ConcernsOnRails
             # 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)
+            # Array() handles both a scalar role and an array-valued `roles`
+            # method — pre-1.22 an actor with roles = ["admin"] stringified to
+            # '["admin"]' and was always denied.
+            actor.respond_to?(role_method, true) &&
+              Array(actor.send(role_method)).any? { |role| wanted.include?(role.to_s) }
           end
           add_authorization_rule(check: check, only: only, except: except, status: status, message: message)
         end
@@ -87,13 +92,16 @@ module ConcernsOnRails
         nil
       end
 
-      # Public override point for how a denial is rendered.
+      # Public override point for how a denial is rendered. Fails CLOSED: when
+      # there is no response object to render into, raise — returning nil here
+      # (the pre-1.22 behavior) let the action run unauthorized.
       def authorization_denied(status:, message:)
-        return unless respond_to?(:response) && response
-
-        return render_error(message: message, status: status, code: "forbidden") if respond_to?(:render_error)
+        unless respond_to?(:response) && response
+          raise "ConcernsOnRails::Controllers::Authorizable: denial for '#{authorization_action_name}' " \
+                "could not be rendered (no response object) — refusing to fail open"
+        end
 
-        render json: { success: false, error: { message: message, code: "forbidden" } }, status: status
+        ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: status, code: "forbidden")
       end
 
       private

data/lib/concerns_on_rails/controllers/cacheable.rb

@@ -61,6 +61,13 @@ module ConcernsOnRails
 
       included do
         class_attribute :cacheable_rules, instance_accessor: false, default: []
+        # no_store is applied EARLY as well: rescue_from-rendered errors skip
+        # after_action entirely, and for a no_store endpoint (tokens, PII) even
+        # the error response must not be stored. Positive freshness policies
+        # deliberately do NOT move early — rescued errors already get Rails'
+        # safe `max-age=0, private` default, and emitting `public, max-age` on
+        # a rescued 500 would let shared caches serve the error.
+        prepend_before_action :apply_http_no_store if respond_to?(:prepend_before_action)
         after_action :apply_http_cache_headers
       end
 
@@ -143,12 +150,26 @@ module ConcernsOnRails
         nil
       end
 
+      # Early half of the policy (see the included block): only no_store, and
+      # idempotent with apply_http_cache_headers re-applying it after render.
+      def apply_http_no_store
+        rule = http_cache_rule_for_action
+        return unless rule && rule[:no_store]
+        return unless respond_to?(:response) && response
+
+        response.set_header("Cache-Control", "no-store")
+      end
+
       # Set ETag/Last-Modified validators for the resource, then — for a safe
       # request whose precondition matches — send 304 and return false. Returns
       # true when the client must be sent a fresh body. Mirrors Rails `stale?`.
       def stale_resource?(resource = nil, etag: nil, last_modified: nil)
-        validators = set_cache_validators(resource, etag: etag, last_modified: last_modified)
+        # Unsafe methods get neither a 304 nor validators: a POST response must
+        # not advertise an ETag a client could replay against GET (pre-1.22 the
+        # validators were written before the safe-method check).
         return true unless http_cache_safe_request?
+
+        validators = set_cache_validators(resource, etag: etag, last_modified: last_modified)
         return true unless request_matches_cache?(etag: validators[:etag], last_modified: validators[:last_modified])
 
         http_cache_send_not_modified
@@ -225,13 +246,10 @@ module ConcernsOnRails
       end
 
       def http_cache_send_not_modified
-        response.status = 304 if respond_to?(:response) && response
+        return head(:not_modified) if respond_to?(:head)
 
-        if respond_to?(:head)
-          head :not_modified
-        else
-          render(status: :not_modified)
-        end
+        response.status = 304 if respond_to?(:response) && response
+        render(status: :not_modified)
       end
 
       def http_cache_safe_request?

data/lib/concerns_on_rails/controllers/cursor_paginatable.rb

@@ -1,4 +1,6 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
+require "concerns_on_rails/support/scalar_param"
 require "json"
 require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
 
@@ -56,6 +58,9 @@ module ConcernsOnRails
       CURSOR_DIRECTIONS = %w[next prev].freeze
       # Adapters whose SQL supports row-value (tuple) comparison: (a, b) > (x, y).
       ROW_PREDICATE_ADAPTERS = /postgres|mysql|trilogy|sqlite/i
+      # Deliberately mutable: memoizes adapter row-predicate support per model
+      # class — stable for the life of the process, benign write race.
+      ROW_PREDICATE_SUPPORT_CACHE = {} # rubocop:disable Style/MutableConstant
 
       # Raised when params[:cursor] is malformed, tampered with, or was minted
       # under a different table/order configuration. Auto-rescued to a 400 when
@@ -195,16 +200,16 @@ module ConcernsOnRails
       # Public override point (mirrors ErrorHandleable's public handlers):
       # delegates to Respondable#render_error when available.
       def render_invalid_cursor(error)
-        return render_error(message: error.message, status: :bad_request, code: "invalid_cursor") if respond_to?(:render_error)
-
-        render json: { success: false, error: { message: error.message, code: "invalid_cursor" } }, status: :bad_request
+        ConcernsOnRails::Support::ErrorEnvelope.render(
+          self, message: error.message, status: :bad_request, code: "invalid_cursor"
+        )
       end
 
       # Same override contract for unknown ?order= preset names.
       def render_invalid_order_preset(error)
-        return render_error(message: error.message, status: :bad_request, code: "invalid_order_preset") if respond_to?(:render_error)
-
-        render json: { success: false, error: { message: error.message, code: "invalid_order_preset" } }, status: :bad_request
+        ConcernsOnRails::Support::ErrorEnvelope.render(
+          self, message: error.message, status: :bad_request, code: "invalid_order_preset"
+        )
       end
 
       private
@@ -311,7 +316,9 @@ module ConcernsOnRails
       end
 
       def cursor_per_page(override)
-        requested = (override || params[:per_page]).to_i
+        # ScalarParam: `?per_page[]=50` arrives as an Array and .to_i on it was
+        # a 500 (mirrors Paginatable).
+        requested = ConcernsOnRails::Support::ScalarParam.to_i(override || params[:per_page], default: 0)
         requested = self.class.cursor_paginatable_per_page if requested < 1
         cap = self.class.cursor_paginatable_max_per_page
         cap.positive? ? [requested, cap].min : requested
@@ -462,7 +469,15 @@ module ConcernsOnRails
 
           return true
         end
-        uniform && model.connection.adapter_name.match?(ROW_PREDICATE_ADAPTERS)
+        uniform && cursor_adapter_row_predicate?(model)
+      end
+
+      def cursor_adapter_row_predicate?(model)
+        key = model.name || model.table_name
+        cached = ROW_PREDICATE_SUPPORT_CACHE[key]
+        return cached unless cached.nil?
+
+        ROW_PREDICATE_SUPPORT_CACHE[key] = model.connection.adapter_name.match?(ROW_PREDICATE_ADAPTERS)
       end
 
       def cursor_row_predicate(model, pairs, values)

data/lib/concerns_on_rails/controllers/deprecatable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 require "active_support/notifications"
 require "date"
 require "time"
@@ -122,9 +123,14 @@ module ConcernsOnRails
 
         def validate_deprecation_link!(name, value)
           return if value.nil?
-          return if value.is_a?(String) && !value.strip.empty?
 
-          raise ArgumentError, "#{LABEL}: :#{name} must be a non-blank String"
+          raise ArgumentError, "#{LABEL}: :#{name} must be a non-blank String" unless value.is_a?(String) && !value.strip.empty?
+          return unless value.match?(/[[:cntrl:]<>]/)
+
+          # These values are interpolated into the Link header: a control
+          # character would split the header (response splitting), and <> would
+          # terminate or forge the URI-Reference delimiters.
+          raise ArgumentError, "#{LABEL}: :#{name} must not contain control characters or '<'/'>'"
         end
 
         # Eager parse to a UTC Time. A bare Date (or date-only String) becomes
@@ -194,14 +200,17 @@ module ConcernsOnRails
       private
 
       def deprecation_rule_for_action
-        action = deprecation_action_name
-        return nil unless action
+        # Memoized (nil included) — the before_action plus the two public
+        # predicates each re-scanned the rule list every request.
+        return @deprecation_rule_for_action if defined?(@deprecation_rule_for_action)
 
+        action = deprecation_action_name
         # Last match wins — see the module comment. reverse_each.find returns the
         # most recently declared rule covering this action (catch-all or not).
-        self.class.deprecatable_rules.reverse_each.find do |rule|
-          rule[:actions].empty? || rule[:actions].include?(action)
-        end
+        @deprecation_rule_for_action =
+          action && self.class.deprecatable_rules.reverse_each.find do |rule|
+            rule[:actions].empty? || rule[:actions].include?(action)
+          end
       end
 
       def emit_deprecation_headers(rule)
@@ -238,10 +247,9 @@ module ConcernsOnRails
         return unless deprecation_sunset_reached?(rule)
 
         message = "This endpoint was sunset on #{rule[:sunset_at].httpdate}."
-        return render_error(message: message, status: :gone, code: "endpoint_sunset") if respond_to?(:render_error)
-        return unless respond_to?(:response) && response
+        return unless respond_to?(:render_error) || (respond_to?(:response) && response)
 
-        render json: { success: false, error: { message: message, code: "endpoint_sunset" } }, status: :gone
+        ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: :gone, code: "endpoint_sunset")
       end
 
       # Inclusive: the boundary instant itself counts as sunset.

data/lib/concerns_on_rails/controllers/error_handleable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 
 module ConcernsOnRails
   module Controllers
@@ -64,11 +65,9 @@ module ConcernsOnRails
       private
 
       def render_error_envelope(message:, code:, status:, errors: nil)
-        return render_error(message: message, code: code, status: status, errors: errors) if respond_to?(:render_error)
-
-        error = { message: message, code: code }
-        error[:details] = errors if errors
-        render json: { success: false, error: error }, status: status
+        ConcernsOnRails::Support::ErrorEnvelope.render(
+          self, message: message, code: code, status: status, details: errors
+        )
       end
     end
   end

data/lib/concerns_on_rails/controllers/filterable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/scalar_param"
 
 module ConcernsOnRails
   module Controllers
@@ -70,13 +71,12 @@ module ConcernsOnRails
         end
       end
 
-      # Scalars (and arrays, which AR turns into `IN (...)`) are safe to pass to
-      # .where; a Hash / ActionController::Parameters is not.
+      # Scalars (and arrays of scalars, which AR turns into `IN (...)`) are safe
+      # to pass to .where; a Hash / ActionController::Parameters is not — and
+      # since 1.22 neither is an array CONTAINING one (`?status[][x]=1` used to
+      # slip through as [Parameters] and 500 with a TypeError).
       def filterable_scalar?(value)
-        return false if value.is_a?(Hash)
-        return false if defined?(ActionController::Parameters) && value.is_a?(ActionController::Parameters)
-
-        true
+        ConcernsOnRails::Support::ScalarParam.where_safe?(value)
       end
     end
   end

data/lib/concerns_on_rails/controllers/idempotentable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 require "digest"
 require "json"
 
@@ -136,9 +137,7 @@ module ConcernsOnRails
       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
+        ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: status, code: code)
       end
 
       private
@@ -209,15 +208,25 @@ module ConcernsOnRails
 
         # 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)
+        idempotency_conflict_response(rule, record)
       end
 
-      def idempotency_conflict_response(rule)
-        response.set_header("Retry-After", rule[:lock_ttl].to_s) if respond_to?(:response) && response
+      def idempotency_conflict_response(rule, record = nil)
+        response.set_header("Retry-After", idempotency_retry_after(rule, record).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
 
+      # Remaining lock time (floored at 1s), not the full lock TTL — the claim
+      # record carries when it was taken, so clients don't back off for a lock
+      # that is about to expire.
+      def idempotency_retry_after(rule, record)
+        claimed_at = record.is_a?(Hash) ? record["claimed_at"] : nil
+        return rule[:lock_ttl] unless claimed_at
+
+        [rule[:lock_ttl] - (Time.now.to_i - claimed_at.to_i), 1].max
+      end
+
       def read_idempotency_header(rule)
         return nil unless respond_to?(:request) && request.respond_to?(:headers) && request.headers
 

data/lib/concerns_on_rails/controllers/includable.rb

@@ -65,7 +65,11 @@ module ConcernsOnRails
         return {} unless raw.respond_to?(:each_pair)
 
         allowed = self.class.includable_fields
-        raw.each_with_object({}) do |(table, cols), memo|
+        # Iterate via each_pair: in a real controller `raw` is an
+        # ActionController::Parameters, which has each_pair but no Enumerable —
+        # calling each_with_object directly on it was a guaranteed
+        # NoMethodError 500 for every ?fields[...]= request.
+        raw.each_pair.with_object({}) do |(table, cols), memo|
           key = table.to_sym
           next unless allowed.key?(key)
 

data/lib/concerns_on_rails/controllers/localizable.rb

@@ -46,12 +46,16 @@ module ConcernsOnRails
       end
 
       # The locale chosen for this request — always one I18n can switch to.
+      # Memoized per request (the wrapper plus any helpers may read it several
+      # times; parsing the Accept-Language header repeatedly is waste).
       def resolved_locale
-        opts = self.class.localizable_options
-        allowed = opts[:available].presence || I18n.available_locales
-        candidate = locale_from_param(opts, allowed) || locale_from_header(opts, allowed) || opts[:default]
+        @resolved_locale ||= begin
+          opts = self.class.localizable_options
+          allowed = opts[:available].presence || I18n.available_locales
+          candidate = locale_from_param(opts, allowed) || locale_from_header(opts, allowed) || opts[:default]
 
-        candidate && I18n.available_locales.include?(candidate.to_sym) ? candidate.to_sym : I18n.default_locale
+          candidate && I18n.available_locales.include?(candidate.to_sym) ? candidate.to_sym : I18n.default_locale
+        end
       end
 
       private
@@ -78,21 +82,26 @@ module ConcernsOnRails
 
       def parse_accept_language(header, allowed)
         ranked_accept_languages(header).each do |lang|
-          match = match_locale(lang, allowed)
+          # Full tag first (fr-CA matches an available :"fr-CA"), then the
+          # primary subtag (fr). Pre-1.22 the region was discarded outright,
+          # so a regional locale in available: could never match its own
+          # Accept-Language tag.
+          match = match_locale(lang, allowed) || match_locale(lang.split("-").first, allowed)
           return match if match
         end
         nil
       end
 
-      # Languages from an Accept-Language header, q=0 dropped, highest-q first
-      # (RFC 7231 preference order).
+      # Language tags from an Accept-Language header (kept whole — see
+      # parse_accept_language for region handling), 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 = token.to_s.strip
           [lang, quality] if lang.present?
         end
         pairs.sort_by { |(_lang, quality)| -quality }.map(&:first)