module Paginatable
extend ActiveSupport::Concern
Page = Struct.new(:records, :next_cursor, keyword_init: true)
DEFAULT_LIMIT = 25
MAX_LIMIT = 100
def cursor_paginate(scope, limit: nil)
limit = clamp_limit(limit)
relation = scope.order(created_at: :asc, id: :asc)
relation = relation.where("id > ?", decode_cursor) if params[:cursor].present?
rows = relation.limit(limit + 1).to_a
has_more = rows.size > limit
rows = rows.first(limit)
Page.new(
records: rows,
next_cursor: has_more ? encode_cursor(rows.last.id) : nil
)
end
private
def clamp_limit(limit)
requested = (limit || params[:limit] || DEFAULT_LIMIT).to_i
requested.clamp(1, MAX_LIMIT)
end
def decode_cursor
Base64.urlsafe_decode64(params[:cursor]).to_i
rescue ArgumentError
0
end
def encode_cursor(id)
Base64.urlsafe_encode64(id.to_s)
end
end
module Api
class ArticlesController < Api::BaseController
include Paginatable
def index
scope = current_user.readable_articles.published
page = cursor_paginate(scope)
count, latest = page_stats(page.records)
etag = collection_etag(count, latest, page.next_cursor)
if stale?(etag: etag, last_modified: latest, public: false)
render json: {
data: page.records.map { |a| ArticleSerializer.new(a).as_json },
next_cursor: page.next_cursor
}
end
end
private
def page_stats(records)
return [0, Time.at(0)] if records.empty?
latest = records.map(&:updated_at).max
[records.size, latest]
end
def collection_etag(count, latest, cursor)
Digest::SHA1.hexdigest(
["articles", count, latest.to_i, cursor, current_user.id].join("/")
)
end
end
end
class ArticleSerializer
def initialize(article)
@article = article
end
def as_json(*)
{
id: @article.id,
title: @article.title,
slug: @article.slug,
excerpt: @article.excerpt,
author: {
id: @article.author_id,
name: @article.author_name
},
published_at: @article.published_at&.iso8601,
updated_at: @article.updated_at.iso8601
}
end
end
This snippet shows how a Rails API endpoint can return a cursor-paginated collection while participating correctly in HTTP conditional GET, so that unchanged pages cost almost nothing on the wire. The core idea is that a representation of a page of records has a stable, content-derived fingerprint; if the client already holds that fingerprint, the server can answer 304 Not Modified with an empty body instead of re-serializing and re-sending the whole payload.
The Paginatable concern mixes a cursor_paginate helper into controllers. It decodes a base64 cursor into a record id, applies a stable ordering on (created_at, id), and fetches one extra row so it can tell whether a next_cursor exists without a second count query. Keyset pagination is used deliberately instead of OFFSET, because offset pagination degrades on deep pages and can skip or duplicate rows when the underlying data shifts between requests. The returned Page struct carries the records plus the encoded cursor.
The Api::ArticlesController ties it together. In index it calls cursor_paginate on a scoped relation, then builds a weak validator with collection_etag. That etag is derived from the number of records, the maximum updated_at, and the cursor — a cheap composite that changes whenever the page's contents or position change. Crucially the max(updated_at) and count are computed with a single pluck, avoiding an extra round trip.
The conditional GET itself is handled by Rails' stale? method. When stale? returns false, Rails has already matched the incoming If-None-Match header against the etag and rendered 304, so the block that serializes JSON is skipped entirely. public: false keeps the response private to the authenticated user, and last_modified gives HTTP-date based validation as a fallback for clients that send If-Modified-Since.
The articles serializer produces deterministic JSON; determinism matters because the etag is only meaningful if identical data always yields an identical body. A subtle pitfall is that any nondeterministic field (a timestamp of 'now', random ordering) would break caching by changing the etag every request. This pattern suits read-heavy list endpoints where clients poll frequently, trading a little server CPU on the validator for large savings in bandwidth and serialization work.
Related snips
class CommentsController < ApplicationController
before_action :set_post
def create
@comment = @post.comments.build(comment_params)System test: asserting Turbo Stream responses
class Post < ApplicationRecord
belongs_to :author, class_name: 'User'
has_many :comments, dependent: :destroy
scope :published, -> { where.not(published_at: nil).where('published_at <= ?', Time.current) }
scope :draft, -> { where(published_at: nil) }ActiveRecord scopes for reusable query logic
payload = {
sub: user.id,
iss: 'https://auth.example.com',
aud: 'codesnips-api',
exp: 15.minutes.from_now.to_i,
iat: Time.now.to_i,JWT issuance and verification without common footguns
module Api
module V1
class UsersController < BaseController
def show
user = User.includes(:profile).find(params[:id])ETags for conditional requests and caching
class PostsController < ApplicationController
def index
@posts = Post.includes(:author)
.order(created_at: :desc)
.page(params[:page])
.per(10)Turbo Frames: infinite scroll with lazy-loading frame
require "csv"
class PeopleCsvStream
include Enumerable
HEADERS = %w[id full_name email signed_up_at plan].freezeResilient CSV Export as a Streamed Response
Share this code
Here's the card — post it anywhere.
