concerns_on_rails 1.28.5 → 1.28.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c6fcd158fd0dce6d1744e9ad6be5d921bf283e921e717a8327f04f53e8668f4
-  data.tar.gz: fe3b93a06be3a0cbb4b0e1904a976393b77d24c4075f1d8dccb98e13d3ac6597
+  metadata.gz: d01a41891ae267bab705b85ab63d6555e7057719a218738bd82c858c63febfa9
+  data.tar.gz: 3bcaebd299e65af41029baebb90ba1670a3502fde222071bffeeef86a4e1fb7b
 SHA512:
-  metadata.gz: 1a113631bd4810decc66aad97ba5fc9fe8866d92dcfd1ab1908c2cdafe7e990e961c3655933ad124ae8275f1a199c4275a7ba72a06cc172ecf248e2825eb42de
-  data.tar.gz: 7102f8a5cb83e21eabe46066f7a62956adf0950dbe926dc8706c9abd217a87577b6004d625c71d179dc2cf4083dc7fdefd25b47883e1a085fee1ec5bb691b41c
+  metadata.gz: 602d50edd8fd84224c73a6ddc09e756bf322f4b3b4e526d34e55774caa88594c54c3ba05d1920005c2152986035b230e2f982e5b6916c2a3a2ec402e1ac2c3c6
+  data.tar.gz: 9ab3f9c635ab132b284d673861c3a3a8282f93aa370f6f75cb1890a1205b9e3c924705b52afd7d182a94fb5247fdc38f51e94bcc4d2a0b1c8de39ea53ee03b54

data/CHANGELOG.md

@@ -1,5 +1,114 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.6 (2026-09-18)
+
+Ten feature PRs deepening existing concerns, released as a patch by request: no new
+concerns and no dependency changes, though several add an optional column or option.
+Every PR was reviewed before merge and carries the review's fixes; the `### Changed`
+and `### Fixed` sections below are those fixes, and they are the ones to read — a few
+tighten validation or start raising where the code used to accept bad input silently.
+Eight further PRs were reviewed in the same pass and held back: they carry defects
+that need more than a patch-sized change.
+
+### Added
+- **Models::Maskable**: `masked_attributes` (every declared field masked, keyed like
+  `attributes`) and a `masked:` serialization option — `as_json(masked: true)` /
+  `to_json(masked: true)` / `serializable_hash(masked: true)` swap the declared fields
+  for their masked forms (`masked: [:email]` for a subset; undeclared fields raise).
+  Composes with `only:`/`except:`/`methods:`/`include:`; plain serialization is
+  unchanged. (#65)
+- **Models::Activatable**: `before_activate` / `after_activate` / `before_deactivate` /
+  `after_deactivate` hooks (one transaction with the write; a raising after-hook rolls
+  back, a failed update skips it; overriding one moves that direction's batch verb to
+  the per-record path) and `activatable_by timestamps:` (`true` → `activated_at` /
+  `deactivated_at` stamped on each transition, or a Hash to rename/drop a side). The
+  batch fast path stamps too. (#78)
+- **Models::Hashable**: `prefix:` prepends a literal to generated values (Stripe-style
+  public IDs such as `ord_k7m3pq9a`; string types only), and `to_param: true` makes the
+  hashed field the URL parameter (falls back to the id while blank). Both validated at
+  class load. (#70)
+- **Models::Tokenizable**: `tokenizable_by … expires_in:` gives a token a lifetime —
+  `<field>_expires_at` is stamped on every generation, `authenticate_by_<field>` refuses
+  an expired token, `<field>_expired?` and the `<field>_expired` scope report it. New
+  `consume_<field>(value)` (every field) authenticates and revokes in one race-safe step
+  for single-use tokens. (#51)
+- **Models::Auditable**: `ConcernsOnRails.setup { |c| c.audit_actor = -> { Current.user&.id } }`
+  sets the `"by"` actor once for every audited model that passes no `actor:` (resolved
+  per save, `instance_exec`'d on the record); `actor: false` opts a model out, and
+  `actor: :method_name` stamps a record method's value. (#50)
+- **Models::CounterCacheable**: `recount_counter_caches!(association, parents:)` repairs
+  only the given parents (ids, records or a relation) — locked, zeroed and re-tallied in
+  one transaction, other rows untouched — so a post-import fix is O(their children).
+  Empty `parents:` is a no-op; the association is required when more than one is
+  declared. (#75)
+- **Controllers::Includable**: nested include allow-lists — `includable :author,
+  comments: :author` accepts `?include=comments.author` (a path must match every
+  segment). `requested_includes(as: :query | :paths | :json)` returns the sanitized
+  includes for `includes`/`preload`, JSON:API serializers, or `as_json(include:)`;
+  `requested_include_paths` exposes the dotted paths. `default:` loads named paths when
+  `?include` is absent (blank opts out); `strategy:` picks
+  `includes`/`preload`/`eager_load`. New `Support::IncludeTree`. (#69)
+- **Controllers::Idempotentable**: replays now carry the original response's `Location`,
+  `Content-Location`, `ETag`, `Last-Modified` and `Link` headers, so a retried `create`
+  still says where the resource lives. `idempotent_actions … headers:` tunes the
+  allow-list (`[]` to capture none). Records written before this release replay
+  unchanged. (#47)
+- **Controllers::Throttleable**: `throttle_by … if:/unless:` per-request skip conditions
+  (Symbol method or callable; both must pass), mirroring Rails 7.2's `rate_limit`. A
+  throttled request instruments `rate_limited.concerns_on_rails` (rule, discriminator,
+  count/limit/period, reset_at/retry_after, controller, action) through the new public
+  `on_rate_limited(rule, result)` hook. (#44)
+- **Controllers::Respondable**: `respondable_by error_format: :problem_details,
+  problem_type_base:` makes `render_error` emit RFC 9457 `application/problem+json`
+  documents (`type`, `title`, `status`, `detail`, `instance`, plus `code`/`errors`
+  extensions). Every concern that renders errors through Respondable follows, so the
+  switch is app-wide. The default stays `:envelope`. (#57)
+
+### Changed
+- **Controllers::Throttleable**: with several applicable rules the `X-RateLimit-*`
+  headers now describe the tightest passing rule (fewest remaining) instead of the last
+  one declared, and a tie on remaining is broken by the rule that resets *last* — so the
+  advertised `X-RateLimit-Reset` can no longer promise a 60-second wait when an hourly
+  rule is the real budget. `result[:discriminator]` is now available to
+  `throttled_response`. Note it is raw personal data (an IP or a user id) in the
+  instrumentation payload too; override `on_rate_limited` to hash or drop it. (#44)
+- **Controllers::Throttleable**: `if:`/`unless:` conditions are now arity-aware — a
+  one-argument callable receives the controller, a zero-arity Proc is still
+  `instance_exec`'d. Previously a `->(c) { … }` condition raised `ArgumentError` on
+  every request. (#44)
+- **Models::Auditable**: an explicit `actor: nil` now keeps meaning "never record who"
+  and no longer falls through to the gem-wide `config.audit_actor`; only omitting
+  `actor:` takes the fallback. `config.audit_actor` accepts a non-Proc callable and
+  `false` (a synonym for nil), and rejects a lambda that demands arguments at
+  configuration time rather than raising inside `before_save`. (#50)
+- **Models::CounterCacheable**: `recount_counter_caches!` now raises `ArgumentError`
+  for an association with no declared counter, instead of returning `{}` as a silent
+  success; and a scoped repair locks the named parent rows before tallying, so a
+  concurrent child write can no longer be lost. (#75)
+- **Controllers::Idempotentable**: response-header capture is case-insensitive, so an
+  app that sets `location` rather than `Location` (correct under Rack 3) is captured on
+  every supported Rails version, not only 7.1+. `idempotency_scope` is now a documented
+  public override point — the default namespace has no per-principal component, so two
+  users sharing a client-chosen key can be served each other's cached response. (#47)
+- **Controllers::Respondable**: the problem-details media type is emitted as bare
+  `application/problem+json`, with no `charset` parameter — RFC 9457 registers none, and
+  strict clients reject the parameterised form. (#57)
+
+### Fixed
+- **Models::Activatable**: lifecycle hooks are invoked with `send`, so a `private` hook
+  override runs instead of raising `NoMethodError` — which in a batch verb aborted and
+  rolled back the whole run. (#78)
+- **Models::Hashable**: the `to_param: true` / Sluggable conflict now raises in *either*
+  declaration order. With Hashable declared first, friendly_id's `to_param` used to land
+  above Hashable's and silently win, so `to_param: true` did nothing. (#70)
+- **Models::Tokenizable**: `expires_in:` now requires an `ActiveSupport::Duration` or a
+  `Numeric`. `expires_in: 2.hours.from_now` was accepted as ~1.8 billion seconds (tokens
+  effectively never expired) and `expires_in: "2 hours"` as 2 seconds. A model missing
+  both token columns now reports them in one error. (#51)
+- **Controllers::Includable**: `requested_includes(as: :paths)` returns a fresh array on
+  the `default:` path; it previously handed back the class attribute itself, so a caller
+  mutating the result corrupted every later request in the process. (#69)
+
 ## 1.28.5 (2026-09-17)
 
 Eight feature PRs deepening existing concerns, released as a patch by request:

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,522 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,624 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
 
 ---
@@ -183,6 +183,7 @@ instead of per controller class:
 # config/initializers/concerns_on_rails.rb
 ConcernsOnRails.setup do |config|
   config.cache_store = -> { Rails.cache }   # fallback for Throttleable / Idempotentable
+  config.audit_actor = -> { Current.user&.id } # fallback "by" for every Auditable model
 end
 
 # Encryptable's key lives in its own config (see the Encryptable section):
@@ -541,7 +542,7 @@ end
 
 ## 🔐 Hashable
 
-Auto-generate random values on create — tokens, codes, UUIDs, or anything from a custom alphabet.
+Auto-generate random values on create — tokens, codes, UUIDs, or anything from a custom alphabet — and, optionally, use them as the public ID in your URLs.
 
 ```ruby
 class Order < ApplicationRecord
@@ -570,13 +571,24 @@ hashable_by :external_id, type: :uuid
 hashable_by :code,        type: :integer, length: 6
 hashable_by :code,        type: :custom,  length: 8,
             alphabet: "ABCDEFGHJKMNPQRSTUVWXYZ23456789"   # Crockford-style, no ambiguous chars
+
+# Public IDs: a Stripe-style prefix and the value as the URL parameter
+hashable_by :public_id, type: :custom, length: 14, prefix: "ord_", unique: true, to_param: true,
+            alphabet: "abcdefghijklmnopqrstuvwxyz0123456789"
+order.public_id          # => "ord_k7m3pq9a2x5n8v"
+order_path(order)        # => "/orders/ord_k7m3pq9a2x5n8v"
+Order.find_by!(public_id: params[:id])
+# while backfilling, accept both shapes — to_param falls back to the integer id when public_id is blank
+Order.find_by(public_id: params[:id]) || Order.find(params[:id])
 ```
 
 **Notes**
 - Auto-assigns in `before_create` only when the field is blank — callers can pass an explicit value.
 - A `regenerate_<field>!` instance method is defined dynamically.
+- `prefix:` is prepended to every generated value (string types only — not `:integer`); the uniqueness check sees the full prefixed value.
+- `to_param: true` overrides `to_param` to return the hashed field, falling back to the id while it is blank — pair it with `find_by!(field: params[:id])`, or with `find_by(field: params[:id]) || find(params[:id])` while a backfill is still in flight (a blank field puts an integer in the URL). Raises at class load alongside Sluggable, in either declaration order — friendly_id overrides `to_param` too.
+- `unique: true` prechecks for collisions and retries a bounded number of times (still add a unique index — that is the real guarantee).
 - For fixed-width numeric codes (e.g. `000042`), use a **string** column — integer columns drop leading zeros.
-- No uniqueness retry is built in. For collision-prone configs (short integer codes), add a unique index and rescue at the app level.
 - If your model has `validates :<field>, presence: true`, switch this concern's hook to `before_validation` in your model — it uses `before_create` by default.
 
 ---
@@ -795,6 +807,10 @@ class Subscription < ApplicationRecord
 
   activatable_by               # defaults to :active
   # activatable_by :enabled    # custom column name
+  # activatable_by timestamps: true                                    # stamps activated_at / deactivated_at
+  # activatable_by timestamps: { activated_at: :enabled_at, deactivated_at: nil }
+
+  def after_deactivate = Billing.pause!(self)   # before/after_activate, before/after_deactivate hooks
 end
 
 sub = Subscription.create!(active: true)
@@ -814,18 +830,23 @@ Subscription.inactive.activate_all     # => 12
 Subscription.active.deactivate_all     # => 3
 ```
 
-Both target the relation, return an Integer count, and run in a transaction. With
-`activate!`/`deactivate!` unoverridden and no validations on the model — neither
+Both target the relation, return an Integer count, and run in a transaction. Gating is per
+direction: with `activate!`, `before_activate` and `after_activate` unoverridden and no
+validations on the model — neither
 `validates`/`validates_with`, a custom `validate :method`, nor an association's autosave
 validation (a bare `has_many` registers one, so most models with associations take the
-streaming path) — they collapse to a single
-`UPDATE`, which bumps `updated_at` exactly as the per-record path does; otherwise they stream
-per record so validations still run, and a record that fails to save raises
-`ActiveRecord::RecordNotSaved` and rolls the whole batch back. `toggle_active!`'s row lock has
+streaming path) — `activate_all` collapses to a single
+`UPDATE`, which bumps `updated_at` exactly as the per-record path does; otherwise it streams
+per record so the hooks and validations still run, and a record that fails to save raises
+`ActiveRecord::RecordNotSaved` and rolls the whole batch back. `deactivate_all` is gated the
+same way by `deactivate!`/`before_deactivate`/`after_deactivate`, so overriding only
+`after_deactivate` leaves `activate_all` on the fast path. `toggle_active!`'s row lock has
 no batch analogue.
 
 **Notes**
 - `NULL` is treated as inactive (same convention as most apps' "unset = off").
+- Hooks (`before_activate` / `after_activate` / `before_deactivate` / `after_deactivate`) share one transaction with the write: a raising after-hook rolls the flip back, a failed `update` (validation) skips the after-hook and returns `false`. `toggle_active!` and the batch verbs go through the same path.
+- `timestamps: true` stamps `activated_at` on activate and `deactivated_at` on deactivate (the other column keeps its last value, so you can see both the last activation and the last deactivation); a Hash renames either column or drops a side with `nil`. The stamp columns must already exist — `activatable_by` checks that at declaration and raises `ArgumentError` otherwise; the `datetime` type itself is not enforced, it only types the migration hint in that error.
 - The configured column must exist; `activatable_by` raises `ArgumentError` otherwise.
 - `SoftDeletable` also defines a `.active` scope (alias of `.without_deleted`). If both concerns are included on the same model, the later one wins — include the one whose `.active` semantics you want last, or stick to one of them.
 
@@ -840,19 +861,22 @@ class User < ApplicationRecord
   include ConcernsOnRails::Tokenizable
 
   tokenizable_by :api_token                                  # 32-char URL-safe
-  tokenizable_by :reset_password_token, length: 24
+  tokenizable_by :reset_password_token, length: 24, expires_in: 2.hours   # needs reset_password_token_expires_at
   tokenizable_by :invite_code, type: :alphanumeric, length: 8
 end
 
-user = User.create!                       # all three tokens auto-generated
+user = User.create!                       # all three tokens auto-generated (+ the reset token's expiry stamped)
 user.api_token                            # => "k3Jf...g2" (32 URL-safe chars)
 user.api_token?                           # => true
+user.reset_password_token_expired?        # => false, until reset_password_token_expires_at passes
 
-user.regenerate_api_token!                # rotates and persists
-user.revoke_api_token!                    # nils the column
+user.regenerate_api_token!                # rotates and persists (an expiring field gets a fresh expiry too)
+user.revoke_api_token!                    # nils the column (and the expiry)
 
 User.find_by_api_token(token)             # Rails default
-User.authenticate_by_api_token(token)     # timing-safe; returns user or nil
+User.authenticate_by_api_token(token)     # timing-safe; returns user or nil — nil for an EXPIRED token
+User.consume_reset_password_token(token)  # single use: authenticate AND revoke atomically; nil the second time
+User.reset_password_token_expired         # scope: rows whose expiry has passed (cleanup jobs)
 ```
 
 **Options**
@@ -861,12 +885,15 @@ User.authenticate_by_api_token(token)     # timing-safe; returns user or nil
 | -------- | ----------- | ------------------------------------------------------------- |
 | `type:`  | `:urlsafe`  | One of `:urlsafe`, `:hex`, `:alphanumeric`, `:numeric`        |
 | `length:`| `32`        | Character length of the generated token                       |
+| `expires_in:` | `nil`  | A `Duration`/seconds. Stamps `<field>_expires_at` (a `datetime` column you add) on every generation; `authenticate_by_`/`consume_` refuse a stale token; adds `<field>_expired?` and the `<field>_expired` scope |
 
 **Notes**
 - URL-safe by default (`A–Z`, `a–z`, `0–9`, `-`, `_`) — drop straight into URLs and headers.
 - Caller-supplied values are respected: `User.create!(api_token: "preset")` won't be overwritten.
 - Generation does a best-effort uniqueness check before insert and retries up to 10 times. Pair with a `unique` DB index for real safety, especially for short alphanumeric/numeric codes.
-- `.authenticate_by_<field>` uses `ActiveSupport::SecurityUtils.secure_compare` to avoid leaking partial matches via response timing.
+- `.authenticate_by_<field>` uses `ActiveSupport::SecurityUtils.secure_compare` to avoid leaking partial matches via response timing, and returns `nil` once an `expires_in:` token has expired.
+- `.consume_<field>(value)` (every field) is the single-use verb — password resets, invite codes, magic links: it authenticates, then revokes with a **conditional `UPDATE`** keyed on the token still being present, so two concurrent consumers cannot both succeed; the loser gets `nil`. An expired token is refused and left in place.
+- A caller-supplied token on an `expires_in:` field gets the configured lifetime **on create** unless the caller also sets `<field>_expires_at`. Assigning one to an already-persisted row (`user.update!(reset_password_token: "preset")`) stamps nothing, and a row whose expiry is `nil` never expires — rotate with `regenerate_<field>!` (which stamps a fresh expiry) or set `<field>_expires_at` yourself.
 - Distinct from `Hashable`: Hashable handles a single random field; Tokenizable focuses on security tokens (multi-field, URL-safe default, timing-safe lookup, revocation).
 
 ---
@@ -1208,6 +1235,18 @@ end
 
 `mask:` sets the mask character (default `*`). Nil and non-string values pass through untouched. To strip dangerous HTML instead, see [Sanitizable](#-sanitizable).
 
+**Serialization** — mask in the response, not just in the view
+
+```ruby
+user.masked_attributes            # => { "email" => "j****@example.com", "card" => "**** **** **** 4242" }
+user.as_json(masked: true)        # every declared field swapped for its masked form, the rest raw
+user.as_json(masked: [:email])    # just these fields (undeclared ones raise)
+user.to_json(masked: true, only: %i[id email])   # composes with only:/except:/methods:/include:
+render json: users.map { |u| u.as_json(masked: true) }
+```
+
+Plain `as_json` / `to_json` are untouched, so nothing changes until you ask.
+
 ---
 
 ## 💰 Monetizable
@@ -1256,10 +1295,13 @@ class Product < ApplicationRecord
 
   auditable_by :price, :status                       # default column :audit_log
   # auditable_by :price, into: :history,
-  #              actor: -> { Current.user&.email },  # stamps "by" on each entry
+  #              actor: -> { Current.user&.email },  # stamps "by" on each entry (or actor: :updated_by_id)
   #              max_entries: 50                     # keep the newest 50
 end
 
+# Or set the actor once for every audited model — models that omit actor: use it, actor: nil/false opts out:
+ConcernsOnRails.setup { |config| config.audit_actor = -> { Current.user&.id } }
+
 product.update!(price: 200)
 product.audit_trail
 # => [{"field"=>"price", "from"=>100, "to"=>200, "at"=>"2026-06-10T12:34:56Z", "by"=>"admin@shop.com"}]
@@ -1270,7 +1312,7 @@ 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 + `…`).
+**Options**: `into:` (`:audit_log`), `actor:` (a Proc `instance_exec`'d on the record, any other callable `#call`ed, or a Symbol naming a record method such as `:updated_by_id`; omit it to take the gem-wide `config.audit_actor`, an explicit `nil`/`false` opts out of that; `"by"` omitted when it resolves to nil), `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.
@@ -1410,6 +1452,7 @@ end
 
 post.comments_count                # maintained on create / destroy / update
 Comment.recount_counter_caches!    # repair drift / backfill every counter
+Comment.recount_counter_caches!(:post, parents: imported_posts)   # repair just these parents (ids, records or a relation)
 ```
 
 Counters are adjusted with `update_counters` (a single atomic SQL `COALESCE(col,0) ± 1`) inside the record's own save transaction. The update path handles the full matrix: a **foreign-key reparent** moves the count from the old parent to the new one, a **condition flip** increments/decrements in place, and the two compose.
@@ -1419,7 +1462,7 @@ Counters are adjusted with `update_counters` (a single atomic SQL `COALESCE(col,
 **Notes**
 - The `belongs_to` must be declared **before** the macro (the reflection is validated at declaration). Polymorphic associations are not supported.
 - Don't also set native `counter_cache: true` on the same column — both would fire and double-count.
-- Counters track the **persisted** record; writes that skip callbacks (`update_column(s)`, `update_all`, `delete`) are not tracked — run `recount_counter_caches!` to reconcile. It rewrites every parent (portable across adapters, but O(n) for conditional counters) — a maintenance operation, run it offline.
+- Counters track the **persisted** record; writes that skip callbacks (`update_column(s)`, `update_all`, `delete`) are not tracked — run `recount_counter_caches!` to reconcile. Bare, it rewrites every parent (portable across adapters, but O(n) for conditional counters) — a maintenance operation, run it offline. With `parents:` it zeroes and re-tallies only those parents (O(their children)) in one transaction that locks those rows before tallying, so repairing one imported post is safe on the request path.
 - Reach for [`counter_culture`](https://github.com/magnusvk/counter_culture) when you need multi-level rollups, delta columns, or after-commit execution.
 
 ---
@@ -1720,7 +1763,7 @@ end
 
 ## 📦 Respondable
 
-Standardized JSON envelopes for API controllers — two methods, zero state.
+Standardized JSON envelopes for API controllers — two intent-revealing render methods, plus an opt-in app-wide switch to RFC 9457 problem details.
 
 ```ruby
 class Api::ArticlesController < ApplicationController
@@ -1754,12 +1797,27 @@ end
 { "success": false, "error": { "message": "...", "code": "...", "details": [...] } }
 ```
 
+**RFC 9457 problem details** — switch the error format once and every 4xx the gem's concerns render
+through `render_error` (ErrorHandleable, Throttleable, Idempotentable, CursorPaginatable, Deprecatable,
+WebhookVerifiable, Authorizable) becomes an `application/problem+json` document; `render_success` is untouched:
+
+```ruby
+respondable_by error_format: :problem_details, problem_type_base: "https://api.example.com/problems"
+# 422 application/problem+json
+# { "type": "https://api.example.com/problems/record_invalid", "title": "Unprocessable Content", "status": 422,
+#   "detail": "Validation failed", "instance": "/api/articles", "code": "record_invalid", "errors": ["Name can't be blank"] }
+```
+
+`type` is `problem_type_base/<code>` (or `about:blank` without a base or code), `title` the status reason phrase,
+`instance` the request path; `code` and `errors` ride along as extension members.
+
 **API**
 
 | Method            | Signature                                                                                  |
 |-------------------|--------------------------------------------------------------------------------------------|
 | `render_success`  | `render_success(data: nil, status: :ok, meta: {})`                                         |
 | `render_error`    | `render_error(message:, status: :unprocessable_entity, code: nil, errors: nil)`            |
+| `respondable_by`  | `respondable_by(error_format: :envelope, problem_type_base: nil)` — class-level; `error_format:` is `:envelope` (default) or `:problem_details` |
 
 > `data:` is a keyword arg (not positional) on purpose — it sidesteps Ruby 3's behavior of treating hash literals as kwargs when a method declares any keyword params.
 
@@ -1856,18 +1914,20 @@ end
 
 ## 🔗 Includable
 
-Whitelisted association sideloading + sparse fieldsets for JSON APIs — zero arbitrary `.includes` from user input.
+Whitelisted association sideloading + sparse fieldsets for JSON APIs — zero arbitrary `.includes` from user input, nested paths included.
 
 ```ruby
 class ArticlesController < ApplicationController
   include ConcernsOnRails::Controllers::Includable
 
-  includable :author, :comments,
-             fields: { articles: %i[id title published_at], authors: %i[id name] }
+  includable :author, comments: :author,                    # flat + nested, like `includes` arguments
+             fields: { articles: %i[id title published_at], authors: %i[id name] },
+             default: :author,                              # loaded when the client sends no ?include at all
+             strategy: :preload                             # :includes (default) | :preload | :eager_load
 
   def index
     render json: with_includes(Article.all),
-           include: requested_includes,
+           include: requested_includes(as: :json),
            fields:  requested_fields
   end
 end
@@ -1876,19 +1936,22 @@ end
 **URL params**
 
 ```
-GET /articles?include=author,comments&fields[articles]=id,title&fields[authors]=id,name
+GET /articles?include=author,comments.author&fields[articles]=id,title&fields[authors]=id,name
 ```
 
 **API**
 
-| Method               | What it does                                                                               |
-|----------------------|--------------------------------------------------------------------------------------------|
-| `with_includes(rel)` | Parses `params[:include]`, intersects with the allow-list, calls `relation.includes(...)`  |
-| `requested_includes` | Returns the sanitized `[:author, :comments]` array (pass to `render json:, include:`)     |
-| `requested_fields`   | Returns `{ articles: [:id, :title] }` sanitized map (pass to your serializer)             |
+| Method                        | What it does                                                                                     |
+|-------------------------------|--------------------------------------------------------------------------------------------------|
+| `with_includes(rel)`          | Parses `params[:include]`, keeps only allow-listed paths, applies them with the configured strategy |
+| `requested_includes(as:)`     | `:query` (default) → `[:author, { comments: :author }]` for `includes`/`preload`; `:paths` → `["author", "comments.author"]` for JSON:API serializers; `:json` → `[:author, { comments: { include: :author } }]` for `as_json`/`render json:` |
+| `requested_include_paths`     | The sanitized dotted paths in request order (what `as: :paths` returns)                            |
+| `requested_fields`            | Returns `{ articles: [:id, :title] }` sanitized map (pass to your serializer)                      |
 
 **Notes**
-- Non-whitelisted associations are **silently dropped** — no error, no arbitrary eager-loading.
+- A path is kept only if **every** segment follows the allow-list tree (`comments.author` needs `comments: :author`); anything else is **silently dropped** — no error, no arbitrary eager-loading.
+- `default:` applies only when `?include` is absent; `?include=` (blank) means "nothing" and is honoured. Defaults are validated against the allow-list at class load, stored frozen and `dup`ed per request.
+- **A typo in an option name becomes an association.** Inline nested Hashes arrive as `**nested`, so any keyword the macro does not name is registered as an allow-listed association instead of raising: `feilds:` silently leaves `includable_fields` empty — i.e. no sparse-fieldset allow-list at all.
 - Non-whitelisted tables in `params[:fields]` are dropped; non-whitelisted columns within an allowed table are dropped.
 - Pass `requested_fields` to your serializer (e.g. AMS / Blueprinter) — `Includable` itself does not alter the JSON output, only the query.
 
@@ -2010,12 +2073,15 @@ class Api::BaseController < ApplicationController
   throttle_by limit: 100, period: 1.minute                          # by IP (default)
   throttle_by limit: 5,   period: 1.minute, only: :create,
               by: -> { current_user&.id || request.remote_ip }
+  throttle_by limit: 1000, period: 1.hour, unless: :staff?          # skip conditions
 end
 ```
 
 Fixed-window counter: the key embeds a floored time bucket (`epoch / period`) so each window starts clean and `X-RateLimit-Reset` is exact.
 
-**Options**: `limit:` (positive integer), `period:` (a `Duration` or seconds), `by:` (discriminator lambda, default per-IP), `only:` / `except:` (mutually exclusive action scoping), `name:` (disambiguates the counter key).
+**Options**: `limit:` (positive integer), `period:` (a `Duration` or seconds), `by:` (discriminator lambda, default per-IP), `only:` / `except:` (mutually exclusive action scoping), `if:` / `unless:` (a Symbol naming a controller method or a callable, evaluated per request — staff accounts, internal IPs, feature flags; both must pass when both given), `name:` (disambiguates the counter key).
+
+When several rules apply to one request the `X-RateLimit-*` headers describe the **tightest** one (fewest requests remaining, ties going to the rule that resets last), so a client sees the budget that runs out first. A throttled request instruments `rate_limited.concerns_on_rails` (payload: `rule`, `discriminator`, `count`, `limit`, `period`, `reset_at`, `retry_after`, `controller`, `action`) via the public `on_rate_limited(rule, result)` hook before the 429 is rendered — subscribe to alert on abusive clients, or override it (call `super` to keep the event). Note `discriminator` is the **raw** client IP (or user id) — personal data that `filter_parameters` does not reach, so hash, truncate or drop it in `on_rate_limited` if subscribers persist it.
 
 **Notes**
 - The store MUST support **atomic increment-with-expiry** (`Rails.cache` with `#increment`, or Redis) — a non-atomic store under-counts under concurrency.
@@ -2062,12 +2128,13 @@ class PaymentsController < ApplicationController
 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`).
+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` **and the original's `Location` / `Content-Location` / `ETag` / `Last-Modified` / `Link` headers** (captured with the cached response — a replayed 201 still says where the resource lives; tune the allow-list with `headers:`, `[]` to capture none); 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`).
+**Options**: `*actions` (allow-list, required), `ttl:` (`24.hours`), `lock_ttl:` (`1.minute`), `header:` (`"Idempotency-Key"`), `required:` (`false`), `headers:` (response headers replayed with the cached response; default `%w[Location Content-Location ETag Last-Modified Link]` — an allow-list on purpose: `Set-Cookie`, `Date`, request ids and rate-limit headers describe the original exchange and are never replayed).
 
 **Notes**
 - Cache keys are scoped per `controller#action` and the client key is SHA256-hashed, so the same key on different endpoints never collides.
+- The scope carries **no principal**: with client-chosen keys, two users sending the same key and payload to one endpoint share a record (the second is served the first's response, `Location` included). Override `idempotency_scope` — `def idempotency_scope = "#{super}:#{current_user&.id}"`.
 - There is **no in-process default store** on purpose: the first keyed request raises `ArgumentError` until you set `idempotency_store` (or the gem-wide fallback `ConcernsOnRails.setup { |c| c.cache_store = -> { Rails.cache } }`).
 - 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.
@@ -2300,9 +2367,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,522 examples)
+bundle exec rspec                               # run the test suite (1,624 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.5.gem      # install locally
+gem install ./concerns_on_rails-1.28.6.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/configuration.rb

@@ -14,8 +14,32 @@ module ConcernsOnRails
   # #write(expires_in:, unless_exist:) / #delete for idempotency. There is
   # still no in-process default on purpose — a non-atomic store silently
   # under-counts, so the host must opt in explicitly (just once, here).
+  #
+  # `audit_actor` is the fallback actor for Models::Auditable: a zero-arg
+  # callable (a Proc is instance_exec'd on the record at save time, any other
+  # callable is #call'd), whose value is stamped as "by" on every audit entry
+  # of every model that passes no `actor:` of its own (`auditable_by ...,
+  # actor: -> { ... }` still wins; an explicit `actor: nil`/`actor: false`
+  # opts a model out). Typically `-> { Current.user&.id }`; nil or false
+  # means no gem-wide actor.
   class Configuration
     attr_accessor :cache_store
+    attr_reader :audit_actor
+
+    # false is accepted as a synonym for nil ("no gem-wide actor"). A lambda
+    # is arity-strict, so one that demands arguments is rejected here rather
+    # than raising from inside before_save on every audited save.
+    def audit_actor=(value)
+      unless value.nil? || value == false || value.respond_to?(:call)
+        raise ArgumentError, "ConcernsOnRails.config.audit_actor must be callable (respond to #call), nil or false"
+      end
+      unless audit_actor_callable_without_args?(value)
+        raise ArgumentError,
+              "ConcernsOnRails.config.audit_actor lambda must take no arguments (it is instance_exec'd on the record)"
+      end
+
+      @audit_actor = value
+    end
 
     # The fallback store with any callable resolved (per lookup, so a Proc
     # reading Rails.cache follows a swapped-out cache in tests). nil when the
@@ -23,5 +47,16 @@ module ConcernsOnRails
     def resolved_cache_store
       cache_store.respond_to?(:call) ? cache_store.call : cache_store
     end
+
+    private
+
+    # Only lambdas enforce arity: 0 (no parameters) and -1 (*args or optional
+    # parameters only) can still be called with none. Non-lambda Procs and
+    # other callables are left alone.
+    def audit_actor_callable_without_args?(value)
+      return true unless value.is_a?(Proc) && value.lambda?
+
+      value.arity.zero? || value.arity == -1
+    end
   end
 end