concerns_on_rails 1.28.6 → 1.28.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d01a41891ae267bab705b85ab63d6555e7057719a218738bd82c858c63febfa9
-  data.tar.gz: 3bcaebd299e65af41029baebb90ba1670a3502fde222071bffeeef86a4e1fb7b
+  metadata.gz: 5b713f3fd8cd14e5f3a12db7b3c390111118df1fa143d5d833dee009544a8a64
+  data.tar.gz: 16f6d5447ac1d44c5be3dc1cdb0113d9a9e64457de14b87d4199bb95993189d8
 SHA512:
-  metadata.gz: 602d50edd8fd84224c73a6ddc09e756bf322f4b3b4e526d34e55774caa88594c54c3ba05d1920005c2152986035b230e2f982e5b6916c2a3a2ec402e1ac2c3c6
-  data.tar.gz: 9ab3f9c635ab132b284d673861c3a3a8282f93aa370f6f75cb1890a1205b9e3c924705b52afd7d182a94fb5247fdc38f51e94bcc4d2a0b1c8de39ea53ee03b54
+  metadata.gz: 7afa091b97fe9359b7294f965593af629d5d66d797e77a7c3ebde396eddc7fcdf627937fae2c90c2ee0c034c23e91f3713ac3827ab201ee8edda0438094ad89c
+  data.tar.gz: 683d74ea9d1b258e1c79bcdcd7243bcbcd22b10ba5c862946267e5baab118c3753c69baf7af496436a7424286cbd33be9f5e6bfba889928f6f212b190d9ed3ca

data/CHANGELOG.md

@@ -1,5 +1,139 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.7 (2026-09-19)
+
+The eight PRs held back from 1.28.6, released as a patch by request. Each carried a
+CRITICAL or a design-level defect found in review; each now carries the fix, and in
+most cases a spec that was verified to fail against the unfixed code. Read the
+`### Fixed` section: several of these defects were live in the PRs' own green CI,
+and two of them are security-shaped.
+
+Also in this release: the Rails 8.1 component bumps are unblocked, and `json` is
+pinned below 3 (json 3 removes `JSON.generate(..., quirks_mode:)`, which
+ActiveSupport 7.1 calls, and changes `JSON.parse`'s positional options, which
+ActiveSupport 8.1 uses — with json 3.0.2 the suite fails in Storable's decode path).
+1730 examples, 0 failures.
+
+### Added
+- **Controllers::Cacheable**: `etag_with` folds request context into the ETag —
+  presets `:locale` / `:format` / `:query`, controller-method Symbols, or a block — so
+  locale-, fieldset- or role-dependent representations of one resource never share a
+  validator; each source adds its implied `Vary` (`vary:` overrides, `vary: false`
+  suppresses), merged with the `http_cache_actions` policy. `stale_resource?` /
+  `set_cache_validators` gain a per-call `extras:`. (#48)
+- **Controllers::Authorizable**: denials instrument
+  `authorization_denied.concerns_on_rails` (controller, action, actor_id, actor_type,
+  rule name, status, message) via the `on_authorization_denied(rule)` override point;
+  `authorize_by`/`require_role` accept `name:`. `skip_authorization only:/except:`
+  exempts actions from every rule, inherited ones included. `authorized?(action)`
+  evaluates the rules without rendering, for view predicates. (#68)
+- **Controllers::Timezoneable**: `persist:` writes a param-chosen zone into the
+  `cookie:` cookie; `response_header:` emits the resolved zone (`X-Time-Zone` or a
+  custom name) and appends `Vary: Time-Zone`; `time_zone_source` reports which source
+  won. (#71)
+- **Controllers::Sortable**: `params[:sort]` accepts JSON:API-style `-key` / `+key`
+  per-column direction prefixes, and `sortable_by` accepts rule hashes —
+  `key: { column: "table.column", joins:, join: :left|:inner, nulls: :first|:last }` —
+  for association-column sorting (lazy LEFT OUTER JOIN by default) and NULLs pinned
+  first or last (Rails 6.1+). (#63)
+- **Models::Searchable**: `searchable_by ..., ranked: true` orders `search` results by
+  relevance — exact, then prefix, then substring, earlier-declared columns first
+  within a tier — via a portable CASE expression; the relation's existing ORDER BY
+  becomes the tiebreaker. `search(q, ranked:)` overrides per call and `search_rank(q)`
+  exposes the score expression. (#64)
+- **Models::Normalizable**: `with:` accepts an Array of presets/callables applied left
+  to right, validated at class load. New presets `:strip`, `:capitalize`, `:titleize`,
+  `:parameterize`, `:nullify_blank` and `:url`. `Model.normalize(field, value)` applies
+  a field's rule to a bare value for lookups and params. (#66)
+- **Models::Sanitizable**: `sanitized_attributes` and a `sanitized:` serialization
+  option — `as_json(sanitized: true | [:fields])` — which composes with
+  `only:`/`except:`, is carried into `include:` children, and sanitizes the *serialized*
+  value so a Maskable mask survives. `Model.sanitize_all!(*fields)` rewrites legacy rows
+  in place for the current scope (by default the `on: :write` fields only), transactional
+  via `Support::BatchOps`, refreshing Encryptable blind indexes. (#72)
+- **Models::Storable**: `where_<accessor>(value)` scope per key — equality on a stored
+  key via `json_extract` (SQLite), `->>` (PostgreSQL) or `JSON_UNQUOTE(JSON_EXTRACT())`
+  (MySQL). Values are cast as the writer stores them; `where_<key>(nil)` matches
+  unset/null. Opt out per key or per macro with `query: false`. (#76)
+- **Support::VaryHeader**: shared `Vary` appender used by Timezoneable and Localizable —
+  seeds Rails' own `Accept` dimension, appends rather than clobbers, de-duplicates
+  case-insensitively and leaves `Vary: *` alone. (#71)
+
+### Changed
+- **Controllers::Cacheable**: a response whose ETag varies on a dimension `Vary` cannot
+  express — a block or controller-method source, or any source with `vary: false` — is
+  now emitted as `Cache-Control: private` regardless of the rule's declared
+  `visibility:`. Such a response is not shareable, and there is no `Vary` that makes it
+  so. (#48)
+- **Controllers::Sortable**: PostgreSQL uses native `NULLS FIRST/LAST`; every other
+  adapter gets the portable `CASE WHEN col IS NULL` equivalent. A `default:` outside the
+  allow-list orders the relation without becoming client-selectable, repeated sort keys
+  collapse to their first occurrence, and `+` must be percent-encoded as `%2B` (Rack
+  decodes a raw `+` to a space). `sort_requests` is the override point; `sort_fields` is
+  read-only. (#63)
+- **Controllers::Authorizable**: the denial payload carries `actor_id:`/`actor_type:`
+  rather than the `current_user` object — notification payloads are not filtered by
+  `config.filter_parameters`. (#68)
+- **Models::Normalizable**: `:url` accepts only `http`/`https`; a value carrying any
+  other scheme is returned stripped rather than blessed as normalized. `:titleize` is
+  deliberately **not** `String#titleize`. (#66)
+- **Models::Storable**: a `where_<key>` scope whose name is already taken no longer
+  aborts the declaration — it is skipped with a deprecator warning, so an existing model
+  defining that method still boots after an upgrade. (#76)
+- **Models::Searchable**: a grouped relation is returned unranked, since a rank
+  `ORDER BY` over `GROUP BY` is an error on PostgreSQL and on MySQL under
+  `ONLY_FULL_GROUP_BY`. (#64)
+
+### Fixed
+- **Controllers::Authorizable**: `skip_authorization except: []` (or `false`, or `""`)
+  exempted **every** action of the controller and all its subclasses — each of those
+  values is truthy while matching no real action name, so the `!except.include?(action)`
+  test was true everywhere. `except: Rails.env.production? && :destroy` is the realistic
+  spelling. Now rejected at class load, along with non-Symbol/String entries; `only:`
+  still accepts them, where they are inert. (#68)
+- **Models::Sanitizable**: `serializable_hash` re-read the raw column instead of
+  post-processing the serialized value, so on a model including both Maskable and
+  Sanitizable it overwrote the mask with sanitized plaintext — order-dependently, and
+  therefore silently. (#72)
+- **Controllers::Timezoneable**: the `cookie:` source now works on a real
+  `ActionController::Base`. `#cookies` is PRIVATE there, so the `respond_to?(:cookies)`
+  guard was always false and the documented cookie source silently did nothing in every
+  real Rails app; only the specs' public-`cookies` double made it look alive. Both guards
+  now ask `respond_to?(:cookies, true)`. (#71)
+- **Controllers::Timezoneable**: `Vary` is no longer written before the action runs,
+  which suppressed Rails' own `Vary: Accept` (`_set_vary_header` only adds it when `Vary`
+  is blank) and let a shared cache serve a JSON body to an HTML request. (#71)
+- **Controllers::Sortable**: MySQL is detected by behaviour rather than by adapter name.
+  The previous `adapter_name.include?("mysql")` test was false for Trilogy, so a
+  `nulls:` rule emitted PostgreSQL syntax against MySQL 8 — a 1064 parse error on every
+  request using that sort key. A dotted Symbol column (`sortable_by :"authors.name"`)
+  is quoted correctly again; it had regressed to `"posts"."authors.name"`. Sort keys are
+  de-duplicated, so `?sort=` with thousands of repeated keys no longer builds thousands
+  of ORDER BY terms. (#63)
+- **Models::Normalizable**: `:titleize` no longer destroys data. It was
+  `Inflector.titleize`, i.e. `humanize(underscore(v))`, which deleted characters —
+  `"Jean-Luc Picard"` → `"Jean Luc Picard"`, `"customer_id"` → `"Customer"` — and ran in
+  `before_validation`, so the original was gone. `:url` no longer drops a URL's
+  `userinfo` on Ruby's newer `uri` versions. (#66)
+- **Models::Storable**: `serialize :settings, coder: JSON, type: Hash` — the form Rails
+  7.1's own deprecation message directs users to — was misclassified as a non-JSON coder,
+  so the whole query feature refused to run on a perfectly queryable column. A blank or
+  corrupt store value no longer makes every `where_` query raise on SQLite. A read-only
+  finder no longer mutates the caller's `Time`. Key names are validated at macro time.
+  (#76)
+- **Models::CounterCacheable**: the locking spec added in 1.28.6 matched the SQLite
+  transaction statement with `start_with?("begin")`; Rails 7.2+ switched SQLite to
+  IMMEDIATE transactions and upcased it, so the assertion silently found nothing on
+  Rails 8.x. Test-only.
+
+### Internal
+- `json` is pinned to `< 3` in the Gemfile. Verified against a real 8.1.3.1 gemset:
+  with json 3.0.2 the suite fails in Storable's decode path; with `json < 3` Rails
+  8.1.3.1 is green.
+- `require "active_support/notifications"` added to `authorizable.rb` and
+  `error_handleable.rb`, which instrument without requiring it — a direct require of
+  either file used to `NameError` on the first event. (#68)
+
 ## 1.28.6 (2026-09-18)
 
 Ten feature PRs deepening existing concerns, released as a patch by request: no new

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,624 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,730 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -724,7 +724,7 @@ expirable_by :valid_until
 
 ## ✨ Normalizable
 
-Auto-normalize attribute values in `before_validation` — strip whitespace, downcase emails, dedupe spaces, run any custom transform.
+Auto-normalize attribute values in `before_validation` — strip whitespace, downcase emails, dedupe spaces, chain transforms, run any custom lambda.
 
 ```ruby
 class User < ApplicationRecord
@@ -733,27 +733,37 @@ class User < ApplicationRecord
   normalizable :email,                  with: :email                       # strip + downcase
   normalizable :phone,                  with: :phone                       # digits only
   normalizable :first_name, :last_name, with: :whitespace                  # strip — same rule, multiple fields
-  normalizable :slug,                   with: ->(v) { v.to_s.parameterize } # custom lambda
+  normalizable :display_name,           with: %i[squish titleize]          # a chain, applied left to right
+  normalizable :bio,                    with: %i[squish nullify_blank]     # "" / "   " → nil
+  normalizable :website,                with: :url                         # "Example.COM/x" → "https://example.com/x"
+  normalizable :slug,                   with: ->(v) { v.to_s.parameterize } # custom lambda (chains with presets too)
 end
 
 User.create(email: "  ALICE@Example.com  ").email   # => "alice@example.com"
 User.create(phone: "+1 (415) 555-1234").phone       # => "14155551234"
+
+# The same rule outside a record — lookups and params see what the DB sees:
+User.find_by(email: User.normalize(:email, params[:email]))
 ```
 
 **Built-in presets**
 
-| Preset       | Transform                                |
-|--------------|------------------------------------------|
-| `:email`     | `strip` + `downcase`                     |
-| `:phone`     | digits only (`gsub(/\D/, "")`)           |
-| `:whitespace`| `strip`                                  |
-| `:squish`    | `squish` (collapse inner whitespace)     |
-| `:downcase`  | `downcase`                               |
-| `:upcase`    | `upcase`                                 |
+| Preset          | Transform                                                            |
+|-----------------|----------------------------------------------------------------------|
+| `:email`        | `strip` + `downcase`                                                 |
+| `:phone`        | digits only (`gsub(/\D/, "")`)                                       |
+| `:whitespace` / `:strip` | `strip`                                                     |
+| `:squish`       | `squish` (collapse inner whitespace)                                 |
+| `:downcase` / `:upcase` / `:capitalize` | the String method of the same name                   |
+| `:titleize`     | upcase each word's first letter and downcase the rest, **in place** — deliberately *not* `String#titleize` (that is `humanize(underscore(v))`, which splits `"Jean-Luc"` into `"Jean Luc"` and drops the `_id` of `"customer_id"`). No character is added or removed, so hyphens and underscores survive; only case changes, so `"DVD player"` → `"Dvd Player"` |
+| `:parameterize` | `parameterize` (URL slug)                                            |
+| `:nullify_blank`| `""` or whitespace-only → `nil` (content untouched)                  |
+| `:url`          | strip, default scheme to `https://` (`host:port` counts as schemeless), lowercase scheme + host, keep userinfo/path/query, drop a redundant default port. Only `http`/`https` are canonicalized — any other scheme (`mailto:`, `tel:`, `javascript:`, `data:`) and unparseable input come back stripped for your format validator to reject |
 
 **Notes**
 - Runs in `before_validation`, so DB constraints and AR validations see the normalized value.
-- `nil` values are skipped — no `nil → ""` coercion.
+- `with:` takes a preset, a Proc, or an Array of them (applied in order); every entry is validated at class load.
+- `nil` values are skipped — no `nil → ""` coercion (use `:nullify_blank` for the opposite direction).
 - Preset normalizers pass non-string values through unchanged.
 - Works on Rails 5+ (no dependency on Rails 7.1's built-in `normalizes`).
 
@@ -787,13 +797,24 @@ Article.search("ruby framework")  # title OR body must contain "ruby" AND "frame
 # match: :prefix           — term%  (starts with)
 # match: :exact            — term   (full match)
 searchable_by :sku, match: :prefix
+
+# ranked: true — best matches first: exact, then prefix, then substring hits;
+# within a tier the earlier-declared column wins. Portable CASE expression, no index needed.
+searchable_by :title, :body, ranked: true
+Article.search("ruby")                        # "ruby" (title) → "Ruby" (body) → "Rubyists…" → "…about ruby"
+Article.search("ruby", ranked: false)         # per-call override (and `ranked: true` opts in per call)
+Article.recent.search("ruby")                 # relevance leads; the existing ORDER BY breaks ties
+Article.group(:author_id).search("ruby")      # grouped relations are returned unranked
+Article.search(q).pluck(:id, Article.search_rank(q))  # the score itself (0 = exact hit on the first column)
 ```
 
 **Notes**
 - Uses Arel's `matches`, which emits `ILIKE` on Postgres (case-insensitive) and `LIKE` elsewhere.
 - The query is escaped before interpolation — `%`, `_`, and `\` from user input are treated as literals, not wildcards.
 - Blank or nil queries return the relation unchanged, so it's safe to drop into a controller pipeline.
-- Reach for `pg_search` / Elasticsearch when you need ranking, stemming, or full-text indexes.
+- `ranked:` uses `reorder`, so relevance leads — until something reorders again. `Controllers::Sortable#sorted` and `CursorPaginatable` both reorder unconditionally, so chain `.search` **after** them (`paginated(sorted(Article.all).search(q))`), not before.
+- Grouped relations are returned unranked (ORDER BY on a non-grouped column is a hard error on Postgres/MySQL), so `Article.group(:author_id).search(q).count` is safe; pass `ranked: false` when the `group`/`distinct` comes after the search. Under `mode: :all` the per-term scores are summed.
+- Reach for `pg_search` / Elasticsearch when you need stemming, weighting by frequency, or full-text indexes.
 
 ---
 
@@ -1200,9 +1221,25 @@ article.sanitized_body  # => "<b>Hi</b>alert(1)"                    (script tag
 | `Hash`       | `{ tags: [...], attributes: [...] }` allow-list.                       |
 | `Proc`       | Used as-is (you own the non-String guard).                             |
 
+**Serialization & clean-up**
+
+```ruby
+article.sanitized_attributes                 # => { "body" => "<b>Hi</b>alert(1)", "summary" => "sum" } — every declared field, cleaned
+article.as_json(sanitized: true)             # declared fields swapped for their sanitized form, the rest raw
+render json: article.as_json(sanitized: [:body], only: %i[id body])   # subset; composes with only:/except:/methods:
+article.as_json(sanitized: true, include: :comments)                  # nested records are sanitized too
+article.as_json(sanitized: true, include: { comments: { sanitized: false } })  # …unless a child opts out
+
+Article.sanitize_all!                        # repair on: :write rows in place → count changed (on: :read columns stay raw)
+Article.sanitize_all!(:body)                 # name an on: :read field to overwrite it — destroys the raw value
+Article.where(legacy: true).sanitize_all!(:body)   # scope-aware, subset of fields
+```
+
 **Notes**
 - `on: :read` (default) is **non-destructive**: it adds a `sanitized_<field>` reader and leaves the stored column untouched.
 - `on: :write` overwrites the column in `before_validation` — **lossy and irreversible** (never use it on code, Markdown, math, or prices), and bypassed by `update_column` / `update_all` / raw SQL.
+- `sanitize_all!` is the repair tool for that bypass (and for rows written before the concern was added): one `update_columns` per row that actually changes, skipping validations/callbacks on purpose, inside a transaction. A bare call repairs the `on: :write` fields only — with none declared it returns `0` without a query.
+- `sanitized:` sanitizes the **serialized** value, so it composes with [Maskable](#-maskable) in either include order: `as_json(masked: true, sanitized: true)` never falls back to the raw column.
 - For full user-authored rich text, prefer [Action Text](https://guides.rubyonrails.org/action_text_overview.html).
 
 ---
@@ -1420,16 +1457,20 @@ account.notifications?           # boolean keys get a predicate
 account.items_per_page_changed?  # per-key dirty (and items_per_page_was)
 account.reset_theme              # drop the key → the default applies again
 account.flag_beta                # affixed accessor
+
+Account.where_theme("dark")       # one scope per key, cast like the writer — SQLite json_extract,
+Account.active.where_flag_beta(true).where_items_per_page(50)   # PostgreSQL ->>, MySQL JSON_EXTRACT
+Account.where_theme(nil)         # unset key, explicit null, or NULL column
 ```
 
-**Options** (per key): `type:` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:json`), `default:` (a value, or a Proc `instance_exec`'d per read), `in:` (inclusion validation, errors on the accessor name). Macro options: `prefix:` / `suffix:` affix the generated method names (the collision escape hatch). The macro is repeatable — repeat calls for the same column merge keys, different columns are independent, and subclasses can add keys without affecting the parent.
+**Options** (per key): `type:` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:json`), `default:` (a value, or a Proc `instance_exec`'d per read), `in:` (inclusion validation, errors on the accessor name), `query:` (`false` skips this key's `where_` scope). Macro options: `prefix:` / `suffix:` affix the generated method names (the collision escape hatch), `query:` sets the default for every key in the call. The macro is repeatable — repeat calls for the same column merge keys, different columns are independent, and subclasses can add keys without affecting the parent.
 
 **Notes**
 - Works on a plain `text` column (JSON encoded/decoded internally), a native `json`/`jsonb` column, or a column the host app already `serialize`d — detected automatically. `serialize` itself is never used, so the Rails 7.1 API drift is irrelevant.
 - nil vs unset: a written `nil` (explicit JSON null) reads back as `nil` and does **not** fall back to the default; `reset_<key>` removes the key so the default applies again. `:decimal` is stored as a precision-safe string, `:date`/`:datetime` as ISO8601 (datetime in UTC at microsecond precision).
 - Writing one key dirties (and saves) the **whole column** — concurrent writers to different keys are last-write-wins on the hash. Undeclared keys are preserved. `:json` readers return a dup: reassign, don't mutate in place.
 - Generated names are collision-checked against existing methods and columns at macro time (`ArgumentError`; affix to escape). Read-side casting never raises — corrupt column JSON decodes as `{}`, garbage values cast to `nil`.
-- Reach for [`store_attribute`](https://github.com/palkan/store_attribute) / [`jsonb_accessor`](https://github.com/madeintandem/jsonb_accessor) when you need to **query** into the store (jsonb operators, store-backed scopes).
+- **Querying**: every key gets a `where_<accessor>(value)` equality scope — `json_extract` on SQLite, `->>` on PostgreSQL (a `text` column is cast to `jsonb`), `JSON_UNQUOTE(JSON_EXTRACT())` on MySQL/MariaDB, which also gets a `JSON_TYPE` predicate so a stored JSON `null` is never confused with the string `"null"`. The value is cast exactly as the writer stores it (`where_items_per_page("50")` works; one that will not cast raises), and `where_<key>(nil)` matches an unset key, an explicit JSON null and a `NULL` column on all three. Defaults are **not** queryable (a never-written key is absent in the DB). `:json` keys and other adapters raise; `query: false` opts out, and a `where_<accessor>` the model already defines is left alone with a deprecation warning rather than overwritten. A row holding blank or corrupt JSON reads as an unset key on SQLite (`json_valid` guard) but aborts the whole query on PostgreSQL and MySQL — there is no portable guard. Reach for [`store_attribute`](https://github.com/palkan/store_attribute) / [`jsonb_accessor`](https://github.com/madeintandem/jsonb_accessor) for jsonb operators, ranges or containment queries.
 
 ---
 
@@ -1743,6 +1784,8 @@ class ArticlesController < ApplicationController
   include ConcernsOnRails::Controllers::Sortable
 
   sortable_by :created_at, :title, :published_at,
+              author: { column: "authors.name", joins: :author },  # an association column
+              price:  { nulls: :last },                            # NULLs after the values
               default: :created_at, direction: :desc
 
   def index
@@ -1751,11 +1794,14 @@ class ArticlesController < ApplicationController
 end
 ```
 
-**URL params**: `?sort=title&direction=asc`
+**URL params**: `?sort=-created_at,title` or `?sort=title&direction=asc`
 
-- `params[:sort]` selects the column; non-whitelisted values fall back to the declared default.
-- `params[:direction]` accepts `asc` / `desc` (case-insensitive); invalid values fall back to the declared default direction.
-- If no `default:` is given, the **first** declared field is used.
+- `params[:sort]` is a comma-separated list of sort **keys**, each optionally prefixed with `-` (descending) or `+` (ascending) — the JSON:API convention. A `+` must be percent-encoded as `%2B`, since a raw `+` in a query string decodes to a space. Non-whitelisted keys are dropped and a repeated key collapses to its first occurrence; when nothing valid remains the declared default applies.
+- Un-prefixed keys take `params[:direction]` (`asc` / `desc`, case-insensitive), then the declared default direction.
+- A plain Symbol sorts by that column of the relation's own table. A `key: { ... }` rule can point elsewhere: `column: "table.column"` plus `joins:` (anything `left_outer_joins` accepts — LEFT OUTER by default so rows without the association are kept; `join: :inner` drops them), and/or `nulls: :first | :last` (Rails 6.1+). Joins are added only when that key is requested.
+- `sorted` uses `reorder`, so the requested columns **replace** any prior `ORDER BY` (including a model `default_scope` order).
+- `nulls:` uses PostgreSQL's native `NULLS FIRST/LAST`; on every other adapter it emits the portable `CASE WHEN col IS NULL` equivalent, so the row order is the same and nothing sends MySQL syntax it rejects.
+- If no `default:` is given, the **first** declared key is used. A `default:` that is *not* in the allow-list is legal — it orders the relation but stays unselectable by clients.
 
 > Distinct from `Models::Sortable` (which manages list position via `acts_as_list`). Both can coexist on a model + its controller.
 
@@ -2037,25 +2083,35 @@ A declarative, **block-only** per-action authorization gate. Each rule is a pred
 class Api::BaseController < ApplicationController
   include ConcernsOnRails::Controllers::Authorizable
 
-  authorize_by { current_user.present? }                          # every action
+  authorize_by(name: :signed_in) { current_user.present? }        # every action
   authorize_by(only: %i[update destroy]) { |_action, user| user.admin? }
   require_role :admin, :editor, only: :publish                    # role sugar
 end
+
+class Api::PagesController < Api::BaseController
+  skip_authorization only: %i[index show]                         # public pages — even the inherited rules skip
+  helper_method :authorized?                                      # <%= link_to "Delete", ... if authorized?(:destroy) %>
+end
 ```
 
 The predicate runs via `instance_exec`, so `current_user` (and any helper) resolves on the controller. It is **arity-safe** — write it with zero, one (`|action|`), or two (`|action, user|`) parameters.
 
 **API**
 
-| Method         | Signature                                                                                  |
-|----------------|--------------------------------------------------------------------------------------------|
-| `authorize_by` | `authorize_by(only: nil, except: nil, status: :forbidden, message: "Forbidden", &block)`   |
-| `require_role` | `require_role(*roles, via: :current_user, role_method: :role, only:, except:, status:, message:)` |
+| Method                    | Signature                                                                                  |
+|---------------------------|--------------------------------------------------------------------------------------------|
+| `authorize_by`            | `authorize_by(only: nil, except: nil, status: :forbidden, message: "Forbidden", name: nil, &block)` |
+| `require_role`            | `require_role(*roles, via: :current_user, role_method: :role, only:, except:, status:, message:, name:)` |
+| `skip_authorization`      | `skip_authorization(only: %i[index show])` / `skip_authorization(except: %i[destroy])` / bare — exempt actions from every rule, inherited ones included; bare form exempts all |
+| `authorized?`             | `authorized?(action = action_name)` — evaluate the rules without rendering (for views / conditional UI) |
+| `on_authorization_denied` | `on_authorization_denied(rule)` — override point; instruments `authorization_denied.concerns_on_rails` (call `super` to keep the event) |
 
 **Notes**
 - Rules run in declaration order; the first failing rule renders and halts.
+- Every denial emits `authorization_denied.concerns_on_rails` with `controller`, `action`, `actor_id`, `actor_type`, `rule` (the `name:`), `status`, `message` — subscribe for audit logs or alerting on repeated denials. The actor is reduced to scalars on purpose: notification payloads aren't filtered by `config.filter_parameters`.
 - When `Respondable` is also included, denials delegate to `render_error` (envelope `{ success: false, error: { message:, code: "forbidden" } }`); otherwise the same envelope is rendered inline.
 - `only:` / `except:` are mutually exclusive (passing both raises `ArgumentError`); `authorize_by` requires a block and `require_role` requires at least one role.
+- `skip_authorization` validates its arguments at class-load time, because every mistake there fails **open**: a nil `only:`/`except:`, or an empty/non-action `except:` (`[]`, `false`, `""` — what `except: Rails.env.production? && :destroy` collapses to), raises instead of exempting every action of the controller *and its subclasses*. Only the bare form grants a blanket skip. The skip is inherited and outranks rules a subclass declares afterwards; `skip_authorization only: []` switches it back off.
 - **Non-goals**: no policy objects, no ability DSL, no resource inference — reach for [`pundit`](https://github.com/varvet/pundit) / [`cancancan`](https://github.com/CanCanCommunity/cancancan) when you outgrow a predicate per action.
 
 ---
@@ -2101,15 +2157,18 @@ class ApplicationController < ActionController::Base
 
   timezoneable available: ["UTC", "Eastern Time (US & Canada)"], default: "UTC"
   # timezoneable param: :tz, header: false, cookie: :time_zone
+  # timezoneable cookie: :time_zone, persist: true          # ?time_zone=London sticks for a year
+  # timezoneable response_header: true                       # X-Time-Zone: London (+ Vary: Time-Zone)
 end
 ```
 
 Resolution order: `params[param]` → `Time-Zone` header → cookie (if enabled) → `default` → the current `Time.zone`. Every value — the configured `available:` / `default:` **and** each request candidate — is resolved through `ActiveSupport::TimeZone[...]`, so a zone accepted at boot can never be rejected at request time.
 
-**Options**: `available:` (allow-list applied to param/header/cookie matching; `default:` bypasses it, mirroring Localizable), `default:`, `param:` (default `:time_zone`), `header:` (default `true`, reads the `Time-Zone` header), `cookie:` (default `false`; `true` reads the `:time_zone` cookie, or pass a cookie name).
+**Options**: `available:` (allow-list applied to param/header/cookie matching; `default:` bypasses it, mirroring Localizable), `default:`, `param:` (default `:time_zone`), `header:` (default `true`, reads the `Time-Zone` header), `cookie:` (default `false`; `true` reads the `:time_zone` cookie, or pass a cookie name), `persist:` (default `false`; `true` or a Hash of cookie options — writes a **param**-chosen zone into the `cookie:` so a settings link makes it stick; needs `cookie:`), `response_header:` (default `false`; `true` emits `X-Time-Zone`, or pass a header name — `Vary: Time-Zone` is appended when the header source is on).
 
 **Notes**
-- An unknown `available:` / `default:` zone raises `ArgumentError` at declaration time (fail-fast on misconfiguration).
+- An unknown `available:` / `default:` zone raises `ArgumentError` at declaration time (fail-fast on misconfiguration); so does `persist:` without `cookie:`.
+- `time_zone_source` tells you which source won (`:param`, `:header`, `:cookie`, `:default`, `:current`) — handy for a "times shown in London (from your browser)" hint.
 - Pairs naturally with the model concerns that read the clock (`Schedulable`, `Publishable`, `Expirable`, `SoftDeletable`).
 
 ---
@@ -2224,6 +2283,7 @@ class Api::ArticlesController < ApplicationController
 
   http_cache_actions :index, :show, max_age: 5.minutes,
                      visibility: :public, vary: "Accept"
+  etag_with :locale                           # the body depends on I18n.locale → folded into the ETag, Vary: Accept-Language
 
   def show
     @article = Article.find(params[:id])
@@ -2234,7 +2294,7 @@ end
 
 # A matching response then carries:
 #   Cache-Control: public, max-age=300
-#   Vary: Accept
+#   Vary: Accept-Language, Accept
 #   ETag: W/"…"
 #   Last-Modified: Thu, 01 Jan 2026 12:00:00 GMT
 ```
@@ -2243,6 +2303,15 @@ end
 
 **Options** (`http_cache_actions *actions, …`, repeatable; no actions = catch-all; **last matching rule wins**): `visibility:` (`:private` default | `:public`), `max_age:` (Integer/Duration), `must_revalidate:`, `no_store:` (overrides everything → bare `no-store`), `stale_while_revalidate:`, `vary:` (String or Array, appended to any existing `Vary`).
 
+**ETag context** (`etag_with`, repeatable — the analogue of Rails' class-level `etag { }`): when the representation depends on more than the record — the locale, the requested fields, the caller's role — declare it and the values are folded into the ETag so two representations of one resource never share a validator. Sources are presets (`:locale` → also `Vary: Accept-Language`, `:format` → `Vary: Accept`, `:query`), Symbols naming controller methods, or a block (`instance_exec`'d); `vary:` overrides the implied header(s), `vary: false` suppresses them; nil values are ignored. Per call: `stale_resource?(@article, extras: [params[:fields]])`. An explicit `etag:` stays verbatim only when there is no context to fold in.
+
+**A source with no `Vary` forces `private`.** A controller method, a block, or a preset with `vary: false` folds a dimension into the ETag that no cache can key on — `Vary` has no way to say *who is asking* — so the response is not shareable and `Cache-Control` is emitted as `private` whatever the rule declared. (`:query` is exempt: the URL already carries it.)
+
+```ruby
+http_cache_actions :show, max_age: 30, visibility: :public
+etag_with { current_user&.role }             # => Cache-Control: private, max-age=30
+```
+
 **Conditional-GET correctness**
 - Weak ETag `W/"<md5>"` from the resource's cache key (collections fold their members' keys + size); `If-None-Match` is matched with **weak comparison**, honours `*`, and accepts a comma-separated list.
 - `Last-Modified` is an IMF-fixdate via `Time#httpdate` (not hand-rolled ISO 8601); `If-Modified-Since` is compared at whole-second granularity.
@@ -2335,7 +2404,7 @@ Both forms reference the same module, so you can freely mix them.
 | Complex state machines (callbacks, transition logging) | [`aasm`](https://github.com/aasm/aasm) |
 | Sentinel-aware unique indexes on soft-deleted rows (`deleted_at` in the index) | [`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 |
+| Indexed full-text search — stemming, tsvector/GIN, typo tolerance (`Searchable` ranks LIKE matches, but never builds an index) | [`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` |
 | Deep clone with per-attribute regex/prepend rules or belongs_to graph copying | [`amoeba`](https://github.com/amoeba-rb/amoeba) |
@@ -2367,9 +2436,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,624 examples)
+bundle exec rspec                               # run the test suite (1,730 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.6.gem      # install locally
+gem install ./concerns_on_rails-1.28.7.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000