concerns_on_rails 1.27.0 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06bf25720ff6c5c3a243efdb7b0d575351d50b8a9f33ae4778c1354816075bb
-  data.tar.gz: 01dc0ff521bee7b5c74c9f30ddee414932441d2ceff84a15af1d9ae8e6d30ccc
+  metadata.gz: 5f9aef0d5f95ffc23ef6213d5d95ea872a6146763d488a287a334db8be68b922
+  data.tar.gz: b364f4276149a31b1ce1f6efaf170435900f34188eb358035c10020567e8b51d
 SHA512:
-  metadata.gz: 37a533852c90cc1876519bd8b52fd07f165bfcfb02efca47bd1ed9d3ff86de94457755d57f9b986d244674a29992cead1b43698de7e3480e92276a0b9c9f1eda
-  data.tar.gz: 3651f6a175bf1a1e203bbe8353a9fc8b7a2c6457dd19f73e89e31fa108a8e238f36a7004aeffface605800b2838f6bb935694ef823a65dc0be943763bfd31293
+  metadata.gz: 025306bb013a418c8051db996ddd0fe6f2bf7ac7f657d22335639b5bcceecff8416e85c66ebde92a357656eeaba90f51a2993fab23232267af105e823cf28934
+  data.tar.gz: b0d98d45a2b189b43985e5d5548c3b905a161f2aa0df9022d251a2788b62524360bc002d2981e7e9801a10e4b0f7aa4a7b1d6b0ee5adb4298edeef89a07a8467

data/CHANGELOG.md

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

data/README.md

@@ -1455,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                              |
@@ -1462,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.
 
 ---
 
@@ -1490,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).
@@ -2086,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,245 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.27.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

data/lib/concerns_on_rails/controllers/paginatable.rb

@@ -1,5 +1,6 @@
 require "active_support/concern"
 require "concerns_on_rails/support/scalar_param"
+require "concerns_on_rails/support/link_header"
 
 module ConcernsOnRails
   module Controllers
@@ -14,61 +15,124 @@ module ConcernsOnRails
     #       render json: paginated(Article.all)
     #     end
     #   end
+    #
+    # `paginated` also takes an in-memory collection — an Array, Set, Range or
+    # any other non-Hash Enumerable — so results assembled outside the
+    # database (an external API, a loaded association, a hand-built list of
+    # Structs) get the same slicing, headers and `pagination_meta`:
+    #
+    #   def search
+    #     render json: paginated(ExternalCatalog.search(params[:q]))
+    #   end
+    #
+    # Every paginated response also carries an RFC 8288 `Link` header with
+    # first/prev/next/last URLs rebuilt from the current request (other query
+    # params preserved) — the GitHub convention, so clients can follow links
+    # instead of computing page numbers. `paginate_by link_header: false` turns
+    # it off.
     module Paginatable
       extend ActiveSupport::Concern
 
+      LABEL = "ConcernsOnRails::Controllers::Paginatable".freeze
       DEFAULT_PER_PAGE = 25
       DEFAULT_MAX_PER_PAGE = 200
 
       included do
         class_attribute :paginatable_per_page, default: DEFAULT_PER_PAGE
         class_attribute :paginatable_max_per_page, default: DEFAULT_MAX_PER_PAGE
+        class_attribute :paginatable_link_header, default: true
+        # Where page / per_page are read from — a path of param names (`["page"]`,
+        # or `["page", "number"]` for JSON:API's page[number]).
+        class_attribute :paginatable_page_param, default: %w[page].freeze
+        class_attribute :paginatable_per_page_param, default: %w[per_page].freeze
       end
 
-      class_methods do
-        # Configure the default page size and the hard cap on per_page.
+      # A real module (not `class_methods do`) so the macro and its private
+      # helpers share one `private` without tripping RuboCop's scope analysis.
+      module ClassMethods
+        # Configure the default page size, the hard cap on per_page, and whether
+        # the RFC 8288 Link header is emitted.
         # Example:
-        #   paginate_by per_page: 50, max_per_page: 500
-        def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE)
+        #   paginate_by per_page: 50, max_per_page: 500, link_header: false
+        def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE, link_header: true,
+                        page_param: nil, per_page_param: nil, style: :flat)
           self.paginatable_per_page = per_page.to_i
           self.paginatable_max_per_page = max_per_page.to_i
+          self.paginatable_link_header = link_header ? true : false
+          defaults = paginatable_style_params!(style)
+          self.paginatable_page_param = paginatable_param_path!(:page_param, page_param || defaults[0])
+          self.paginatable_per_page_param = paginatable_param_path!(:per_page_param, per_page_param || defaults[1])
+        end
+
+        private
+
+        # :flat → page / per_page; :jsonapi → page[number] / page[size].
+        def paginatable_style_params!(style)
+          case style.to_sym
+          when :flat then [%w[page], %w[per_page]]
+          when :jsonapi then [%w[page number], %w[page size]]
+          else raise ArgumentError, "#{LABEL}: style: must be :flat or :jsonapi (got #{style.inspect})"
+          end
+        end
+
+        # A name or a non-empty path of names, normalized to Strings.
+        def paginatable_param_path!(option, value)
+          path = Array(value)
+          valid = path.any? && path.all? { |segment| (segment.is_a?(Symbol) || segment.is_a?(String)) && !segment.to_s.empty? }
+          raise ArgumentError, "#{LABEL}: #{option}: must be a param name or a path of names (got #{value.inspect})" unless valid
+
+          path.map(&:to_s).freeze
         end
       end
 
-      # Apply pagination to a relation and set the standard response headers.
-      # Returns the paginated relation; the metadata is memoized so a follow-up
-      # `pagination_meta` (no argument) reuses it. Safe on empty relations.
-      def paginated(relation)
+      # Apply pagination to a relation or an in-memory collection and set the
+      # standard response headers. A relation comes back as a relation with
+      # LIMIT/OFFSET applied (still lazy); an Enumerable comes back as the
+      # current page's Array slice (`[]` past the last page). The metadata is
+      # memoized so a follow-up `pagination_meta` (no argument) reuses it.
+      # Safe on empty collections.
+      #
+      # `total:` says the collection IS the current page already — an external
+      # API or search service returned page N of a result set it counted for
+      # you. Nothing is sliced, limited or counted: the records come back
+      # untouched and `total` drives X-Total-Count, X-Total-Pages and the Link
+      # header. Ask the upstream for the same page/per_page you read here.
+      def paginated(collection, total: nil)
         @paginatable_meta = nil
+        source = paginatable_source(collection)
+        pre_paginated = !total.nil?
         page = pagination_page
         per_page = pagination_per_page
         offset = (page - 1) * per_page
 
-        total = paginatable_total(relation)
+        total = pre_paginated ? paginatable_validate_total!(total) : paginatable_total(source)
         total_pages = per_page.positive? ? (total.to_f / per_page).ceil : 0
 
-        records = relation.limit(per_page).offset(offset)
+        records =
+          if pre_paginated
+            source # the caller already fetched exactly this page: an Array stays an Array, a relation is not limited
+          elsif source.is_a?(Array)
+            source[offset, per_page] || []
+          else
+            source.limit(per_page).offset(offset)
+          end
 
         @paginatable_meta = { total: total, page: page, per_page: per_page, total_pages: total_pages }
         set_pagination_headers(**@paginatable_meta)
+        set_pagination_links(page: page, total_pages: total_pages)
         records
       end
 
-      # Pagination metadata WITHOUT applying limit/offset — handy for
-      # body-based pagination (compose with Respondable's `meta:`). Call with
-      # no argument after `paginated` to reuse its memoized meta — the
+      # Pagination metadata WITHOUT applying limit/offset (or slicing) — handy
+      # for body-based pagination (compose with Respondable's `meta:`). Call
+      # with no argument after `paginated` to reuse its memoized meta — the
       # documented records+meta composition used to run the identical COUNT
-      # twice per request. Pass a relation to compute fresh.
-      def pagination_meta(relation = nil)
-        return @paginatable_meta if relation.nil? && @paginatable_meta
-
-        if relation.nil?
-          raise ArgumentError,
-                "ConcernsOnRails::Controllers::Paginatable: pagination_meta needs a relation " \
-                "(no prior paginated call in this request to reuse)"
-        end
+      # twice per request. Pass a relation or collection to compute fresh.
+      # With `total:` the COUNT is skipped (and the collection may be omitted).
+      def pagination_meta(collection = nil, total: nil)
+        return @paginatable_meta if collection.nil? && total.nil? && @paginatable_meta
 
-        total = paginatable_total(relation)
+        total = paginatable_meta_total(collection, total)
         per_page = pagination_per_page
         {
           total: total,
@@ -80,29 +144,90 @@ module ConcernsOnRails
 
       private
 
-      # COUNT with the clauses that break or skew it stripped: order/limit/
-      # offset are irrelevant, a custom SELECT list would turn into the invalid
-      # COUNT(a, b), and count(:all) keeps DISTINCT semantics. A grouped
-      # relation counts as a Hash (group => count); the meaningful total is the
-      # number of groups.
-      def paginatable_total(relation)
-        counted = relation.except(:order, :limit, :offset, :select).count(:all)
+      # Relations — anything answering `limit` and `offset`: an
+      # ActiveRecord::Relation, an association CollectionProxy, a model class —
+      # pass through untouched so they keep paginating in SQL. Any other
+      # non-Hash Enumerable is materialized ONCE into an Array, so an
+      # Enumerator is not consumed twice (once to count, once to slice). A Hash
+      # is rejected rather than silently paginated as [key, value] pairs.
+      def paginatable_source(collection)
+        return collection if collection.respond_to?(:limit) && collection.respond_to?(:offset)
+        return collection.to_a if collection.is_a?(Enumerable) && !collection.is_a?(Hash)
+
+        hint = collection.is_a?(Hash) ? " — call .to_a to paginate a Hash as [key, value] pairs" : ""
+        raise ArgumentError,
+              "#{LABEL}: expected an ActiveRecord relation or an Enumerable (Array, Set, Range, ...), " \
+              "got #{collection.class}#{hint}"
+      end
+
+      # `total:` wins (validated); otherwise COUNT the collection; neither
+      # given and nothing memoized is a caller error.
+      def paginatable_meta_total(collection, total)
+        return paginatable_validate_total!(total) unless total.nil?
+        return paginatable_total(paginatable_source(collection)) unless collection.nil?
+
+        raise ArgumentError,
+              "#{LABEL}: pagination_meta needs a relation or collection " \
+              "(no prior paginated call in this request to reuse)"
+      end
+
+      def paginatable_validate_total!(total)
+        return total if total.is_a?(Integer) && total >= 0
+
+        raise ArgumentError, "#{LABEL}: total: must be a non-negative Integer (got #{total.inspect})"
+      end
+
+      # Arrays already know their size. Relations COUNT with the clauses that
+      # break or skew it stripped: order/limit/offset are irrelevant, a custom
+      # SELECT list would turn into the invalid COUNT(a, b), and count(:all)
+      # keeps DISTINCT semantics. A grouped relation counts as a Hash
+      # (group => count); the meaningful total is the number of groups.
+      def paginatable_total(source)
+        return source.size if source.is_a?(Array)
+
+        counted = source.except(:order, :limit, :offset, :select).count(:all)
         counted.is_a?(Hash) ? counted.length : counted
       end
 
       # Both readers route through ScalarParam: `?page[]=1` / `?page[x]=1`
       # arrive as Array/Parameters, and calling .to_i on those was a 500.
       def pagination_page
-        [ConcernsOnRails::Support::ScalarParam.to_i(params[:page], default: 0), 1].max
+        [ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_page_param), default: 0), 1].max
       end
 
       def pagination_per_page
-        requested = ConcernsOnRails::Support::ScalarParam.to_i(params[:per_page], default: 0)
+        requested = ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_per_page_param), default: 0)
         requested = self.class.paginatable_per_page if requested < 1
         cap = self.class.paginatable_max_per_page
         cap.positive? ? [requested, cap].min : requested
       end
 
+      # Dig the configured path out of params: `["page"]` → params[:page];
+      # `["page", "number"]` → params[:page][:number]. A scalar where a Hash
+      # is expected yields nil (→ the default), like any other garbage.
+      def pagination_param(path)
+        path.reduce(params) do |node, key|
+          break nil unless node.respond_to?(:[]) && !node.is_a?(String) && !node.is_a?(Array)
+
+          node[key]
+        end
+      end
+
+      # The `overrides` for LinkHeader.url_for that set the page number under the
+      # configured name — replacing the whole nested Hash for a path so the
+      # other keys in it (page[size]) survive.
+      def pagination_page_override(number)
+        path = self.class.paginatable_page_param
+        return { path.first.to_sym => number } if path.size == 1
+
+        nested = request.query_parameters.to_h.transform_keys(&:to_s)[path.first]
+        nested = nested.is_a?(Hash) ? nested.deep_dup : {}
+        node = nested
+        path[1...-1].each { |key| node = (node[key] = node[key].is_a?(Hash) ? node[key] : {}) }
+        node[path.last] = number
+        { path.first.to_sym => nested }
+      end
+
       def set_pagination_headers(total:, page:, per_page:, total_pages:)
         return unless respond_to?(:response) && response
 
@@ -111,6 +236,30 @@ module ConcernsOnRails
         response.set_header("X-Per-Page", per_page.to_s)
         response.set_header("X-Total-Pages", total_pages.to_s)
       end
+
+      # Link: <…?page=1>; rel="first", <…?page=1>; rel="prev", <…?page=3>;
+      # rel="next", <…?page=5>; rel="last". prev/next only when such a page
+      # exists; past the end, prev points at the last page. Nothing is emitted
+      # for an empty collection, when disabled, or without a real request.
+      def set_pagination_links(page:, total_pages:)
+        return unless pagination_links_applicable?(total_pages)
+
+        page_url = ->(number) { ConcernsOnRails::Support::LinkHeader.url_for(request, **pagination_page_override(number)) }
+        ConcernsOnRails::Support::LinkHeader.append(
+          response,
+          first: page_url.call(1),
+          prev: page > 1 ? page_url.call([page - 1, total_pages].min) : nil,
+          next: page < total_pages ? page_url.call(page + 1) : nil,
+          last: page_url.call(total_pages)
+        )
+      end
+
+      def pagination_links_applicable?(total_pages)
+        return false unless self.class.paginatable_link_header && total_pages.positive?
+        return false unless respond_to?(:response) && response
+
+        ConcernsOnRails::Support::LinkHeader.available?(self)
+      end
     end
   end
 end

data/lib/concerns_on_rails/support/link_header.rb

@@ -0,0 +1,54 @@
+require "rack/utils"
+
+module ConcernsOnRails
+  module Support
+    # RFC 8288 `Link` response header for the paginators: rebuilds the current
+    # request URL with a few query params changed (`page=3`, `cursor=…`) and
+    # appends `<url>; rel="next"` entries to the response — never clobbering a
+    # Link header something else already set (Deprecatable's rel="deprecation",
+    # CDN preload hints). Shared by Paginatable and CursorPaginatable.
+    module LinkHeader
+      module_function
+
+      # True when the controller has a request the URLs can be rebuilt from.
+      # The dependency-free FakeController has none, so emission is skipped.
+      def available?(controller)
+        return false unless controller.respond_to?(:request)
+
+        request = controller.request
+        %i[base_url path query_parameters].all? { |reader| request.respond_to?(reader) }
+      end
+
+      # The request's URL with `overrides` merged into its query string (a nil
+      # value or a key in `drop:` removes that param; a Hash value replaces a
+      # nested param wholesale — `page: { "number" => 3, "size" => 10 }`).
+      # Existing params keep their order; nested params survive via Rack's
+      # nested-query encoding.
+      def url_for(request, drop: [], **overrides)
+        query = request.query_parameters.to_h.transform_keys(&:to_s)
+        overrides.each { |key, value| value.nil? ? query.delete(key.to_s) : query[key.to_s] = stringify_deep(value) }
+        Array(drop).each { |key| query.delete(key.to_s) }
+
+        base = "#{request.base_url}#{request.path}"
+        query.empty? ? base : "#{base}?#{Rack::Utils.build_nested_query(query)}"
+      end
+
+      # build_nested_query wants String keys and String leaves.
+      def stringify_deep(value)
+        return value.to_h { |k, v| [k.to_s, stringify_deep(v)] } if value.is_a?(Hash)
+
+        value.to_s
+      end
+
+      # `links` is { rel => url }; nil urls are skipped and nothing is set when
+      # none remain. Appends to an existing Link header, comma-separated.
+      def append(response, links)
+        entries = links.filter_map { |rel, url| %(<#{url}>; rel="#{rel}") if url }
+        return if entries.empty?
+
+        existing = response.headers["Link"]
+        response.set_header("Link", [existing, entries.join(", ")].reject { |part| part.nil? || part.empty? }.join(", "))
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.27.0".freeze
+  VERSION = "1.28.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -80,6 +80,7 @@ module ConcernsOnRails
     autoload :Encryptor,               "concerns_on_rails/support/encryptor"
     autoload :Affix,                   "concerns_on_rails/support/affix"
     autoload :BatchOps,                "concerns_on_rails/support/batch_ops"
+    autoload :LinkHeader,              "concerns_on_rails/support/link_header"
   end
 
   # Encryption config + error types (Support::Encryptor requires it itself)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.27.0
+  version: 1.28.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -186,6 +186,7 @@ files:
 - lib/concerns_on_rails/support/error_envelope.rb
 - lib/concerns_on_rails/support/filter_parameter_registry.rb
 - lib/concerns_on_rails/support/html_sanitizers.rb
+- lib/concerns_on_rails/support/link_header.rb
 - lib/concerns_on_rails/support/masker.rb
 - lib/concerns_on_rails/support/money.rb
 - lib/concerns_on_rails/support/random_value.rb