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. |
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 |
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).
next_link_header(base_url, token, *, param=DEFAULT_PAGE_TOKEN_PARAM)
¶
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 |
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. |
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. |