Skip to content

Pagination

rn_forge.web.pagination

Opaque cursor pagination and orderBy using Google AIP-158 and AIP-132.

Page sizes are clamped to the configured cap. Responses use items, nextPageToken, and the optional totalSize field.

No pagination library is adopted: fastapi-pagination 0.16.0 (checked 2026-09-23) cannot produce {items, nextPageToken} without total from its stock cursor page, and its CursorParams reject an oversized page size with a 422 where AIP-158 clamps.

DEFAULT_PAGE_SIZE_PARAM = 'pageSize' module-attribute

The query parameter carrying the requested page size.

DEFAULT_PAGE_TOKEN_PARAM = 'pageToken' module-attribute

The query parameter carrying the continuation token.

ORDER_BY_PARAM = 'orderBy' module-attribute

The query parameter carrying the sort order.

SortValue = str | int | float | bool | None module-attribute

One sort value in a page token, as its JSON type; dates are ISO 8601 strings.

Cursor(sort_keys, entity_id, order_by='') dataclass

The decoded contents of a page token.

sort_keys holds the last row's value for each orderBy term, in term order; entity_id is the tiebreaker that makes the ordering total. Together they are the keyset the next page resumes from. order_by is the canonical orderBy the token was issued for, empty for the endpoint's default order, whose sort_keys is empty.

OrderField(field, descending=False) dataclass

One orderBy term: a field name as it appears on the wire and a direction.

Page

Bases: WireModel

One page of results, in the AIP-158 envelope.

nextPageToken is always present and null on the last page; totalSize is omitted from the body when absent.

as_body()

Return the wire body, camelCase, omitting an absent totalSize.

check_cursor_order(cursor, terms)

Reject a page token issued for a different ordering than terms.

Raises:

Type Description
InvalidCursor

The token's order differs from the request's, or it holds a different number of sort values than there are terms.

clamp_page_size(requested, *, default, cap)

Return a usable page size, clamping rather than rejecting.

Per AIP-158, an over-large pageSize is coerced to the maximum.

Parameters:

Name Type Description Default
requested int | None

What the client asked for. None or a non-positive value means "unspecified" and yields default.

required
default int

The size used when the client asks for none.

required
cap int

The largest size this endpoint will serve.

required

Returns:

Type Description
int

A size in 1..cap.

decode_cursor(raw)

Decode a page token.

Every malformed input class is caught — not base64, base64 of non-JSON, JSON of a non-object, JSON missing a key, a sort-value list that is not a list of scalars. Missing one of them turns a tampered token into a 500.

Raises:

Type Description
InvalidCursor

raw is not a well-formed page token.

encode_cursor(sort_keys, entity_id, order_by='')

Encode a keyset position as an opaque page token.

URL-safe base64 over compact JSON — small, and safe in a query string without further escaping. sort_keys holds one value per orderBy term and keeps each value's JSON type. order_by is the canonical ordering from :func:format_order_by; it is omitted from the token when empty.

format_order_by(terms)

Return the canonical orderBy string for terms (desc explicit, asc omitted).

Build an RFC 8288 Link: <...>; rel="next" header value.

Additive, never a replacement: nextPageToken in the body is the contract, and this header is a convenience for clients that were not generated from the schema. A client relying only on the header will break on an endpoint that cannot build an absolute URL.

Parameters:

Name Type Description Default
base_url str

The collection URL, with or without an existing query string.

required
token str

The continuation token to embed.

required
param str

The query parameter name.

DEFAULT_PAGE_TOKEN_PARAM

Returns:

Type Description
str

A value suitable for the Link response header.

parse_order_by(raw, *, allowed)

Parse an AIP-132 orderBy value such as displayName desc.

A term is a field name optionally followed by asc or desc (default asc). Terms are comma-separated, whitespace around a term is ignored, and a field may appear only once.

Parameters:

Name Type Description Default
raw str | None

The query parameter value. None or blank yields no terms.

required
allowed Collection[str]

The field names the endpoint can sort by, as they appear on the wire.

required

Returns:

Type Description
tuple[OrderField, ...]

The terms in order, or an empty tuple when raw is blank.

Raises:

Type Description
InvalidOrderBy

A term is malformed (including an empty one), names a field outside allowed, or repeats an earlier term's field.