concerns_on_rails 1.28.5 → 1.28.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c6fcd158fd0dce6d1744e9ad6be5d921bf283e921e717a8327f04f53e8668f4
-  data.tar.gz: fe3b93a06be3a0cbb4b0e1904a976393b77d24c4075f1d8dccb98e13d3ac6597
+  metadata.gz: 5b713f3fd8cd14e5f3a12db7b3c390111118df1fa143d5d833dee009544a8a64
+  data.tar.gz: 16f6d5447ac1d44c5be3dc1cdb0113d9a9e64457de14b87d4199bb95993189d8
 SHA512:
-  metadata.gz: 1a113631bd4810decc66aad97ba5fc9fe8866d92dcfd1ab1908c2cdafe7e990e961c3655933ad124ae8275f1a199c4275a7ba72a06cc172ecf248e2825eb42de
-  data.tar.gz: 7102f8a5cb83e21eabe46066f7a62956adf0950dbe926dc8706c9abd217a87577b6004d625c71d179dc2cf4083dc7fdefd25b47883e1a085fee1ec5bb691b41c
+  metadata.gz: 7afa091b97fe9359b7294f965593af629d5d66d797e77a7c3ebde396eddc7fcdf627937fae2c90c2ee0c034c23e91f3713ac3827ab201ee8edda0438094ad89c
+  data.tar.gz: 683d74ea9d1b258e1c79bcdcd7243bcbcd22b10ba5c862946267e5baab118c3753c69baf7af496436a7424286cbd33be9f5e6bfba889928f6f212b190d9ed3ca

data/CHANGELOG.md

@@ -1,5 +1,248 @@
 <!-- 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
+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: