concerns_on_rails 1.26.0 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7552b47dbc09add52b4bb8d519e8a8d4ed4e49590457114003fa83b6e9b7036e
-  data.tar.gz: b03171261ba6e24865ce46ab0c1e77a234cfec514e45e50a2dd055e82b5da287
+  metadata.gz: 5f9aef0d5f95ffc23ef6213d5d95ea872a6146763d488a287a334db8be68b922
+  data.tar.gz: b364f4276149a31b1ce1f6efaf170435900f34188eb358035c10020567e8b51d
 SHA512:
-  metadata.gz: 461bbe636a2537cc5b60fe1eb5be3c080c115a3f119ca057a5f75d24dd54da44a6f5833a1f2baff6d2562d829fa77f98e7d1494e57cd8e1402b513f697025d61
-  data.tar.gz: 046a10782bc2259cf8911610a13b71289aa77ce2a1164045fd524fc785b58cc6061756ea99fba3f147d6964145641f63e03ed50b8530656b9a7269a4b83ce2bf
+  metadata.gz: 025306bb013a418c8051db996ddd0fe6f2bf7ac7f657d22335639b5bcceecff8416e85c66ebde92a357656eeaba90f51a2993fab23232267af105e823cf28934
+  data.tar.gz: b0d98d45a2b189b43985e5d5548c3b905a161f2aa0df9022d251a2788b62524360bc002d2981e7e9801a10e4b0f7aa4a7b1d6b0ee5adb4298edeef89a07a8467

data/CHANGELOG.md

@@ -1,5 +1,173 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.0 (2026-09-06)
+
+Pagination is the theme: the four-PR Paginatable stack (#40, #45, #62, #83)
+from the September enhancement loop. Paginatable now paginates in-memory
+collections, both paginators emit RFC 8288 `Link` headers, results that were
+already paginated upstream can pass `total:`, and the page / per-page parameter
+names (including JSON:API's `page[number]` / `page[size]`) are configurable.
+Controller-only: no new columns, migrations or runtime dependencies. 1303
+examples, 0 failures.
+
+### Added
+- **Controllers::Paginatable**: `paginated` / `pagination_meta` accept in-memory
+  collections — an `Array`, `Set`, `Range` or any other non-Hash `Enumerable` —
+  not only ActiveRecord relations. The collection is materialized once, the
+  total is its size and the current page comes back as an `Array` with the same
+  `X-Total-Count` / `X-Page` / `X-Per-Page` / `X-Total-Pages` headers and
+  memoized meta. Relations still paginate in SQL. A `Hash`, `nil` or a
+  non-collection raises `ArgumentError` naming the class received. (#40)
+- **Controllers::Paginatable / CursorPaginatable**: RFC 8288 `Link` response
+  header — `first`/`prev`/`next`/`last` page URLs for Paginatable, `next`
+  (+ `prev` in bidirectional mode, `first` once a cursor is in play) for
+  CursorPaginatable — rebuilt from the current request with every other query
+  param preserved and appended to any existing `Link` header. Opt out with
+  `link_header: false` on either macro. Backed by the new shared
+  `Support::LinkHeader`. (#45)
+- **Controllers::Paginatable**: `paginated(collection, total:)` /
+  `pagination_meta(total:)` for collections that are already one page — an
+  external API's or search service's page N plus its total: nothing is sliced
+  or counted, and `total` drives the `X-*` headers and the `Link` header.
+  `total:` must be a non-negative Integer. (#62)
+- **Controllers::Paginatable**: `paginate_by page_param:` / `per_page_param:`
+  (a top-level name or a nested path such as `%i[page number]`) and
+  `style: :jsonapi` (`?page[number]=&page[size]=`); explicit `*_param:` options
+  win over the style, anything else raises at declaration. Readers dig the path
+  through `ScalarParam`, so a scalar where a Hash is expected falls back to the
+  default instead of raising. The `Link` header URLs are rebuilt under the
+  configured names (nested paths Rack-encoded, sibling keys preserved). (#83)
+
+### Notes
+The `Link` header is **on by default**, so every non-empty paginated response
+grows by one header. Its URLs are built from `request.base_url` + `request.path`,
+i.e. whatever host Rails sees — behind a proxy configure `trusted_proxies` /
+forwarded headers, or pass `link_header: false`. The `X-*` headers are
+unchanged either way, and the existing `?page=&per_page=` behaviour is
+byte-for-byte the same when no `page_param:` / `per_page_param:` / `style:` is
+given.
+
+### Internal
+- New `Support::LinkHeader` (autoloaded): `available?(controller)` — a request
+  exposing `base_url` / `path` / `query_parameters` (the dependency-free
+  `FakeController` has none, so emission is silently skipped); `url_for(request,
+  drop:, **overrides)` — Rack nested-query encoding, nested params survive, Hash
+  override values deep-stringified, `nil` / `drop:` removes a key;
+  `append(response, rels)` — never clobbers an existing `Link`.
+- `Paginatable.paginate_by` moved into `module ClassMethods` alongside its new
+  private helpers (RuboCop scope rule; the Stateable precedent).
+- Development dependencies: simplecov `~> 1.1`, sqlite3 `~> 2.9.6`, rubocop
+  `~> 1.89`; GitHub Actions `checkout` v7, `configure-pages` v6, `deploy-pages`
+  v5, `upload-pages-artifact` v5. The lockfile now resolves `permittable` 0.2.0
+  (the `~> 0.1` runtime pin is unchanged).
+
+## 1.27.0 (2026-08-29)
+
+Scope-name collisions finally have an escape hatch on the eight concerns whose
+generated scope names can collide (Activatable, Expirable, Lockable, Stateable
+and Anonymizable already had it; Publishable, SoftDeletable and Schedulable
+join them here), and the 1.22 batch-operation contract reaches five more
+concerns. No new columns, migrations or dependencies. 1257 examples, 0
+failures.
+
+### Added
+- **Models::Publishable / SoftDeletable / Schedulable**: `prefix:`/`suffix:` on
+  `publishable_by` / `soft_deletable_by` / `schedulable_by` rename the generated
+  scopes, so a model can include SoftDeletable (`.active`) alongside Activatable
+  or Expirable (also `.active`) without one silently clobbering the other. With
+  no affix passed the scope names, default scopes and emitted SQL are unchanged.
+  `prefix: true` (use the configured field name), previously honoured only by
+  Stateable, now works on every affixing concern.
+- **Models::Publishable**: `publish_all` / `unpublish_all`. `publish_all` targets
+  every not-currently-published row — *including scheduled ones*, whose future
+  timestamp it overwrites; chain the draft scope (`Post.draft.publish_all`) to
+  narrow it, which composes because the predicate is built against the current
+  relation rather than routed through the field-unscoping `unpublished` scope.
+  The flip side: on a model with `default_scope: true` the relation is already
+  narrowed to published rows, so a bare `Post.publish_all` matches nothing —
+  chain `.draft` or `.unpublished` (both unscope the column themselves). Both
+  verbs respect the relation, return an Integer count, and run in a
+  transaction.
+- **Models::Expirable**: `expire_all(time = Time.zone.now)`.
+- **Models::Activatable**: `activate_all` / `deactivate_all`.
+- **Models::Lockable**: `unlock_expired` — clears `locked_at` and zeroes the
+  attempts counter on every row whose `unlock_in` window has elapsed, mirroring
+  `unlock_access!`. Returns 0 without querying when `unlock_in` is nil.
+- **Models::Stateable**: `transition_all(event)` — runs one declared transition
+  across the relation, skipping (not failing) records the guard rejects.
+  Deliberately has no single-UPDATE fast path: the per-record path runs
+  validations through `update!` and a bulk UPDATE would skip them.
+
+### Notes
+Validation semantics of the new batch verbs (`publish_all`, `unpublish_all`,
+`expire_all`, `activate_all`, `deactivate_all`, `unlock_expired`): each
+collapses to a **single `UPDATE`** — one SQL statement for the whole batch —
+only when the host model declares **no validations** (and has overridden
+none of the concern's hooks/bang methods; see the per-concern docs for the
+exact method list). "No validations" means neither `validates` /
+`validates_with` **nor** a custom `validate :method` / `validate do … end` —
+the latter registers only a validate callback and leaves `validators` empty,
+so it is detected through `_validate_callbacks` rather than `validators`.
+It also means **no association carrying the default autosave validation**: a
+bare `has_many`/`has_one` registers a `validate_associated_records_*` callback,
+so in practice most models with associations take the streaming per-record
+path. That is deliberate — the gate errs toward the path that honours the
+rollback contract — but it means the single-`UPDATE` optimisation applies to
+simple models, not to every model that merely omits `validates`.
+`unlock_expired` is exempt from the validations check because
+`unlock_access!` writes via `update_columns`, which always skips validations,
+so its two paths are already equivalent. On a model that declares any
+validation, five of these verbs (`publish_all`, `unpublish_all`, `expire_all`,
+`activate_all`, `deactivate_all`) instead stream the relation record-by-record
+inside a transaction, calling the same guarded bang/update method a single
+record would use; a record that fails to save raises
+`ActiveRecord::RecordNotSaved` and rolls the **entire batch** back — nothing
+partially commits.
+
+The single-`UPDATE` path writes `updated_at` (`updated_on` too, when present)
+alongside the concern's own column whenever the model has that column and
+`record_timestamps` is on, so the fast and slow paths agree — the same thing
+Rails' `touch_all` and `update_counters(touch:)` do. `unlock_expired` is
+exempt here as well: it mirrors `unlock_access!`, which writes via
+`update_columns` and deliberately does not touch timestamps.
+
+`transition_all` also always takes the per-record path, regardless of
+validators — for the same underlying reason (validations must run) — but its
+failure mode is different, not the same: the per-record path calls the
+guarded `<event>!`, which calls `update!`, and `update!` raises
+`ActiveRecord::RecordInvalid` **directly** on a validation failure. That
+exception propagates straight out of the batch loop, never reaching the
+`RecordNotSaved` branch the other five verbs use. Code that rescues
+`RecordNotSaved` around a `transition_all` call will not catch a failed row —
+rescue `RecordInvalid` there instead.
+
+One residual, deliberate divergence survives on the fast path: like every
+`*_all` method in Rails, the single-UPDATE path does not fire host-defined
+`before_save`/`after_save` callbacks (only the concern's own
+`before_*`/`after_*` lifecycle hooks are checked when deciding whether the
+fast path applies at all). If your model relies on `before_save`/`after_save`
+for side effects, either add a validation (forcing the slow, per-record path)
+or call the bang method in a loop.
+
+### Internal
+- New `Support::Affix` (affixed-name computation, `prefix: true` normalization,
+  and the guarded scope capture/retirement used by the three newly affixable
+  concerns) replaces six duplicated implementations across Activatable,
+  Expirable, Lockable, Anonymizable, Stateable and Storable.
+- New `Support::BatchOps`: the whole fast-path safety decision
+  (`fast_path?` = hooks/bang methods unoverridden AND no declared validations,
+  detected through both `validators` and `_validate_callbacks`), the
+  ownership-only half (`unoverridden?`, for the two concerns whose per-record
+  path writes via `update_column(s)` and so needs no validations gate), the
+  `updated_at`/`updated_on` bulk-write payload helper (`with_timestamps`), and
+  the transactional `find_each` runner. SoftDeletable's `soft_delete_all` /
+  `restore_all` now route through it, so the contract has one definition.
+- Retiring a default-named scope is guarded three ways — the name must have been
+  recorded by the concern, be owned by the class's own singleton, and still be
+  the exact method captured — so a model's own override survives and a parent's
+  scopes are never removed from a subclass (that case raises with a pointer to
+  the parent).
+
 ## 1.26.0 (2026-08-24)
 
 A fixes-and-performance round from a full audit of the 25 model concerns: one privacy bug (Anonymizable left Encryptable blind-index fingerprints queryable after erasure), four silent-misbehavior fixes, five query-count reductions, and three hardening changes. No new concerns. 1173 examples, 0 failures.

data/README.md

@@ -358,6 +358,58 @@ publishable_by :published_at, default_scope: true
 # Article.unscoped reaches everything
 ```
 
+**Bulk operations**
+
+```ruby
+Post.draft.publish_all       # publishes every not-currently-published post; returns the count
+Post.published.unpublish_all # unpublishes every currently-published post; returns the count
+```
+
+Both respect the current relation, return an Integer count, and run in a transaction — a
+record that fails to save raises `ActiveRecord::RecordNotSaved` and rolls the whole batch
+back. With no overridden `before_publish`/`after_publish`/`before_unpublish`/`after_unpublish`/
+`publish!`/`unpublish!` 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) — both collapse to a
+single `UPDATE`, which bumps `updated_at`
+exactly as the per-record path does; otherwise they stream per record through
+`publish!`/`unpublish!` so validations still run.
+
+`publish_all` targets every not-currently-published row — **including scheduled ones**, whose
+future `published_at` it overwrites — so chain `.draft` (`Post.draft.publish_all`) to exclude
+them. Its predicate composes with your own constraint on the publish column, so that chain
+really does leave scheduled rows alone. The flip side of composing: with `default_scope: true`
+the relation is already narrowed to published rows, so a bare `Post.publish_all` matches
+nothing — chain `.draft` or `.unpublished` first (both unscope the column themselves, so the
+chain resolves to the rows you mean).
+
+**Scope-name collisions**
+
+```ruby
+publishable_by :published_at, prefix: :article   # => Article.article_published / .article_draft
+publishable_by :published_at, suffix: :posts     # => Article.published_posts / .draft_posts
+publishable_by :published_at, prefix: true       # => Article.published_at_published / ...
+```
+
+`prefix:`/`suffix:` rename every scope `publishable_by` generates, so a model can include
+Publishable alongside another concern that would otherwise generate a same-named scope
+(SoftDeletable and Activatable also define `.active`, for instance) without one clobbering
+the other. With no affix passed, scope names, the optional default scope, and the emitted
+SQL are all unchanged.
+
+`prefix:`/`suffix:` mean three different things across the gem, depending on the concern:
+- **Scope-name affix** (renames generated scopes) — Activatable, Expirable, Lockable,
+  Stateable, Anonymizable, Publishable, SoftDeletable, Schedulable.
+- **Accessor-name affix** (renames generated reader/writer methods) — Storable.
+- **A literal string prepended to the generated value itself** — Sequenceable's `prefix:`
+  (e.g. `"INV-"`), unrelated to scope/method naming.
+
+Passing `true` for a scope- or accessor-name affix means "use the configured field name"
+(`publishable_by :published_at, prefix: true` → `published_at_published`/`published_at_draft`).
+
+Unrelated to all three: Searchable's `match: :prefix` is a LIKE-match mode (`term%`), not a
+naming affix.
+
 **Notes**
 - "Published" means `published_at` is set **and** in the past — so future-dated posts stay unpublished until their time arrives.
 - No `default_scope` is added by default; chain `.published` explicitly (or opt in with `default_scope: true`).
@@ -412,6 +464,21 @@ collapse to a single `UPDATE`. Note that `really_destroy_all` peels the soft-del
 predicate off the relation, so `only_deleted.really_destroy_all` widens to the whole
 relation — purge trash with `User.soft_deleted.delete_all` instead.
 
+**Scope-name collisions**
+
+```ruby
+soft_deletable_by :deleted_at, prefix: :account   # => .account_active / .account_soft_deleted / ...
+soft_deletable_by :deleted_at, suffix: :records    # => .active_records / .soft_deleted_records / ...
+soft_deletable_by :deleted_at, prefix: true        # => .deleted_at_active / ...
+```
+
+`prefix:`/`suffix:` rename every scope `soft_deletable_by` generates (`active`,
+`without_deleted`, `soft_deleted`, `only_deleted`, `with_deleted`, `deleted_within`), so a
+model can combine SoftDeletable with another concern that also defines `.active` (Activatable,
+Expirable) without a collision. `prefix: true` uses the configured field name. With no affix
+passed, scope names, the default scope, and the emitted SQL are unchanged. See the
+Publishable section above for how `prefix:`/`suffix:` differ across the gem.
+
 **Lifecycle hooks** — override these methods on the model:
 
 ```ruby
@@ -512,6 +579,18 @@ promo.reschedule!(starts_at: 1.day.from_now,
                   ends_at:   2.days.from_now)
 ```
 
+**Scope-name collisions**
+
+```ruby
+schedulable_by prefix: :promo    # => .promo_current / .promo_upcoming / .promo_expired / .promo_active_at
+schedulable_by suffix: :window   # => .current_window / .upcoming_window / .expired_window / .active_at_window
+schedulable_by prefix: true      # => .starts_at_current / ... (the configured starts_at/ends_at field)
+```
+
+`prefix:`/`suffix:` rename every scope `schedulable_by` generates (`active_at`, `current`,
+`upcoming`, `expired`). With no affix passed, scope names and the emitted SQL are unchanged.
+See the Publishable section above for how `prefix:`/`suffix:` differ across the gem.
+
 **Notes**
 - Boundary semantics: **inclusive start, exclusive end** — active at exactly `starts_at`, not at exactly `ends_at`.
 - A `nil` end means "never expires"; a `nil` start means "not yet started".
@@ -552,6 +631,21 @@ token.extend_expiry!(by: 1.day)     # pushes expiry forward
 - If `expires_at` is `nil` or in the past → new value is `now + by`
 - If `expires_at` is still in the future → `by` is added to the existing value
 
+**Bulk operations**
+
+```ruby
+ApiToken.expiring_within(1.day).expire_all   # => 12
+```
+
+`expire_all(time = Time.zone.now)` expires every currently-active record in the relation and
+returns the Integer count, in a transaction. With `expire!` 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) — it collapses
+to a single `UPDATE`, which bumps `updated_at` exactly as the per-record path does; otherwise it
+streams per record through `expire!` so validations still run, and a record that fails to save
+raises `ActiveRecord::RecordNotSaved` and rolls the whole batch back.
+
 **Custom field name**
 
 ```ruby
@@ -659,6 +753,23 @@ Subscription.active     # WHERE active = TRUE
 Subscription.inactive   # WHERE active = FALSE OR active IS NULL
 ```
 
+**Bulk operations**
+
+```ruby
+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
+`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
+no batch analogue.
+
 **Notes**
 - `NULL` is treated as inactive (same convention as most apps' "unset = off").
 - The configured column must exist; `activatable_by` raises `ArgumentError` otherwise.
@@ -805,6 +916,18 @@ article.may_publish?           # => true  (guard check without raising)
 article.transition_to!(:archived)  # generic move to any declared state
 ```
 
+**Bulk operations**
+
+```ruby
+Article.draft.transition_all(:publish)   # => 12 — runs :publish across every eligible row
+```
+
+Returns the Integer count of records transitioned, running in a transaction; records the
+guard rejects are skipped (not errors). Unlike every other batch verb in this gem,
+`transition_all` has **no single-UPDATE fast path** — it always streams per record through
+the guarded `<event>!` method, because that path runs validations via `update!` while a bulk
+`update_all` would silently skip them.
+
 **Prefix / suffix** — avoid clashes when the state names overlap with other concerns or scopes:
 
 ```ruby
@@ -1094,10 +1217,21 @@ user.reset_failed_attempts!     # call on successful login
 user.lock_access!               # manual lock     (hooks: before/after_lock)
 user.unlock_access!             # manual unlock   (hooks: before/after_unlock)
 User.locked / User.unlocked     # expiry-aware scopes
+
+User.unlock_expired              # => 3 — unlocks every row whose unlock_in window has elapsed
 ```
 
 **Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `prefix:` / `suffix:` (affix the scope names).
 
+**Bulk operations**
+
+`unlock_expired` clears `locked_at` and zeroes the attempts counter on every row whose
+`locked_at + unlock_in` has passed, exactly as `unlock_access!` does — returns the Integer
+count, runs in a transaction. Returns `0` without querying when `unlock_in` is `nil` (manual
+unlock only). Because `unlock_access!` persists via `update_columns` (which already skips
+validations), the single-`UPDATE` fast path and the per-record path are equivalent here —
+unlike Publishable/Expirable/Activatable, this one has no validators gate.
+
 **Notes**
 - The increment is SQL-side (`COALESCE(attempts, 0) + 1` via `update_counters`), so concurrent failures never lose updates and a NULL counter needs no column default; a locked account stops counting.
 - Expiry is **lazy**: readers and scopes treat a stale lock as unlocked but never write. The column is cleared by the next `unlock_access!` or failed attempt (quietly there — no unlock hooks fire from a failed login).
@@ -1321,6 +1455,30 @@ class ArticlesController < ApplicationController
 end
 ```
 
+**Arrays and other Enumerables work too.** Results that never touched the database — an
+external API response, a loaded association, a hand-built list of Structs — get the same
+slicing, headers and `pagination_meta`. Relations still paginate in SQL (`LIMIT`/`OFFSET`);
+an in-memory collection is sliced in Ruby and comes back as an `Array`:
+
+```ruby
+def search
+  render json: paginated(ExternalCatalog.search(params[:q]))   # Array in, current page out
+end
+```
+
+Anything answering `limit`/`offset` is treated as a relation; any other non-`Hash` `Enumerable`
+(`Array`, `Set`, `Range`, `Enumerator` — consumed once) is materialized and sliced. A `Hash`,
+`nil` or a non-collection raises `ArgumentError` (call `.to_a` to paginate a Hash's pairs).
+
+**Already paginated upstream?** When an external API or search service hands you page N and the
+total it counted, pass `total:` — nothing is sliced, limited or counted; the collection comes back
+as-is and `total` drives `X-Total-Count`, `X-Total-Pages` and the `Link` header:
+
+```ruby
+result = Catalog.search(params[:q], page: params[:page], per_page: params[:per_page])
+render_success(data: paginated(result.hits, total: result.total_hits), meta: pagination_meta)
+```
+
 **URL params**
 
 | Param        | Default | Notes                              |
@@ -1328,7 +1486,19 @@ end
 | `?page=`     | `1`     | Page numbers below 1 are clamped to 1 |
 | `?per_page=` | `25`    | Capped at `max_per_page` (default 200) |
 
-**Response headers**: `X-Total-Count`, `X-Page`, `X-Per-Page`, `X-Total-Pages`.
+Rename them, or speak JSON:API — the `Link` header URLs follow whatever you pick:
+
+```ruby
+paginate_by page_param: :p, per_page_param: :limit                 # ?p=2&limit=10
+paginate_by style: :jsonapi                                        # ?page[number]=2&page[size]=10
+paginate_by page_param: %i[paging page], per_page_param: %i[paging per]   # any nested path
+```
+
+**Response headers**: `X-Total-Count`, `X-Page`, `X-Per-Page`, `X-Total-Pages`, and an RFC 8288 `Link`
+header with `first` / `prev` / `next` / `last` URLs rebuilt from the current request (other query params
+preserved; `prev`/`next` only when such a page exists; nothing for an empty collection) — the GitHub
+convention, so clients follow links instead of computing page numbers. Appended to any `Link` header
+already set (Deprecatable, CDN hints). `paginate_by link_header: false` turns it off.
 
 ---
 
@@ -1356,7 +1526,7 @@ end
 | `?per_page=` | `25`    | Capped at `max_per_page` (default 200; `0` disables the cap) |
 | `?order=`    | first preset | With `order_presets:` only — selects a named ordering from the allow-list (unknown names → 400 `invalid_order_preset`) |
 
-**Response headers**: `X-Per-Page`, `X-Count` (rows on **this** page — totals are deliberately not computed), `X-Has-More`, `X-Next-Cursor` (only while more pages exist). With `bidirectional: true`: also `X-Has-Prev`, `X-Prev-Cursor`.
+**Response headers**: `X-Per-Page`, `X-Count` (rows on **this** page — totals are deliberately not computed), `X-Has-More`, `X-Next-Cursor` (only while more pages exist). With `bidirectional: true`: also `X-Has-Prev`, `X-Prev-Cursor`. Plus an RFC 8288 `Link` header: `rel="next"` carries the next-cursor URL, `rel="prev"` the prev-cursor URL (bidirectional), `rel="first"` the current URL with the cursor dropped (once a cursor is in play); `per_page` and the order preset are preserved. `cursor_paginate_by link_header: false` turns it off.
 
 **Notes**
 - The primary key is always appended as a tiebreaker, so duplicate values never skip or repeat rows; ordering columns are chosen **in code** (never from params) and should be `NOT NULL` (a NULL boundary value raises rather than silently dropping rows).
@@ -1952,9 +2122,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,173 examples)
+bundle exec rspec                               # run the test suite (1,303 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.26.0.gem      # install locally
+gem install ./concerns_on_rails-1.28.0.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/controllers/cursor_paginatable.rb

@@ -2,6 +2,7 @@ require "active_support/concern"
 require "concerns_on_rails/support/error_envelope"
 require "concerns_on_rails/support/scalar_param"
 require "json"
+require "concerns_on_rails/support/link_header"
 require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
 
 module ConcernsOnRails
@@ -141,6 +142,7 @@ module ConcernsOnRails
         class_attribute :cursor_paginatable_max_per_page, default: DEFAULT_MAX_PER_PAGE
         class_attribute :cursor_paginatable_bidirectional, default: false
         class_attribute :cursor_paginatable_predicate, default: :auto
+        class_attribute :cursor_paginatable_link_header, default: true
 
         # Real controllers (anything with ActiveSupport::Rescuable) get the 400
         # handlers automatically; bare objects let the errors propagate.
@@ -161,7 +163,7 @@ module ConcernsOnRails
         # max_per_page: 0 (or negative) disables the per_page cap.
         def cursor_paginate_by(order: nil, order_presets: nil, default_preset: nil, order_param: :order,
                                per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE,
-                               bidirectional: false, predicate: :auto)
+                               bidirectional: false, predicate: :auto, link_header: true)
           self.cursor_paginatable_order = order && CursorPaginatable.normalize_order!(order)
           self.cursor_paginatable_order_presets = order_presets && CursorPaginatable.normalize_presets!(order_presets)
           self.cursor_paginatable_default_preset =
@@ -171,6 +173,7 @@ module ConcernsOnRails
           self.cursor_paginatable_max_per_page = max_per_page.to_i
           self.cursor_paginatable_bidirectional = bidirectional ? true : false
           self.cursor_paginatable_predicate = CursorPaginatable.validate_predicate!(predicate)
+          self.cursor_paginatable_link_header = link_header ? true : false
         end
       end
 
@@ -506,11 +509,31 @@ module ConcernsOnRails
         response.set_header("X-Count", meta[:count].to_s)
         response.set_header("X-Has-More", meta[:has_more].to_s)
         response.set_header("X-Next-Cursor", meta[:next_cursor]) if meta[:next_cursor]
+        apply_cursor_pagination_links(meta)
         return unless meta.key?(:has_prev)
 
         response.set_header("X-Has-Prev", meta[:has_prev].to_s)
         response.set_header("X-Prev-Cursor", meta[:prev_cursor]) if meta[:prev_cursor]
       end
+
+      # RFC 8288 Link: rel="next" carries the X-Next-Cursor token, rel="prev"
+      # the X-Prev-Cursor one (bidirectional mode), rel="first" is the current
+      # URL with the cursor dropped — emitted once a cursor is in play. Other
+      # query params (per_page, the order preset) are preserved. Skipped when
+      # disabled or without a real request.
+      def apply_cursor_pagination_links(meta)
+        return unless self.class.cursor_paginatable_link_header
+        return unless ConcernsOnRails::Support::LinkHeader.available?(self)
+
+        cursor_url = ->(token) { ConcernsOnRails::Support::LinkHeader.url_for(request, cursor: token) }
+        raw_cursor = params[:cursor]
+        ConcernsOnRails::Support::LinkHeader.append(
+          response,
+          first: ConcernsOnRails::Support::ScalarParam.scalar?(raw_cursor) && !raw_cursor.to_s.empty? ? cursor_url.call(nil) : nil,
+          prev: meta[:prev_cursor] && cursor_url.call(meta[:prev_cursor]),
+          next: meta[:next_cursor] && cursor_url.call(meta[:next_cursor])
+        )
+      end
     end
   end
 end