cmind/common/v1/paging.proto

Package: cmind.common.v1

Enums

PageDirection

PageDirection selects a window relative to the cursor; it does not reorder the result. Items always come back in the endpoint's canonical sort order, so paging BACKWARD from a cursor returns the page preceding it, still in reading order. To reverse the order itself, use the endpoint's order_by field.

Value	Number	Description
PAGE_DIRECTION_UNSPECIFIED	0
PAGE_DIRECTION_FORWARD	1
PAGE_DIRECTION_BACKWARD	2

Messages

PageRequest

PageRequest is embedded in a ListXxxRequest as the page field. PageInfo is embedded in the matching ListXxxResponse. Together they are the platform's one paging shape: every paged endpoint speaks it, whatever the endpoint's backing store is. Cursors are opaque on purpose. A cursor is a keyset position for a SQL-backed list, an in-memory sort position for a list served from the Kubernetes informer cache, and a plain offset for a store that only does offsets (e.g. Keycloak). Callers cannot tell the difference, so a list can change strategy later without a wire change.

Field	Type	Number	Description
pageSize	int32	1	Maximum items to return. 0 means the server default. The server clamps to its own maximum, so a page may be smaller than requested.
cursor	string	2	Position to page from, taken from a previous response's start_cursor or end_cursor. Empty means the start of the collection when paging FORWARD, and the end of it when paging BACKWARD. A cursor is only valid against the sort order it was issued for. Replaying one after order_by changed is rejected with INVALID_ARGUMENT rather than silently returning a wrong window. Bounded well above any cursor a server issues, so that a hostile value is rejected at the edge rather than base64-decoded and JSON-parsed first.
direction	PageDirection	3	Which side of the cursor to read. UNSPECIFIED is treated as FORWARD.

PageInfo

Field	Type	Number	Description
startCursor	string	1	Cursor for the first item of this page. Empty when the page is empty.
endCursor	string	2	Cursor for the last item of this page. Empty when the page is empty.
hasNextPage	bool	3	Whether items exist after end_cursor. Exact when paging FORWARD — traversal terminates on it, so it is always computed from a real over-fetch rather than inferred. When paging BACKWARD it is advisory: the server errs towards true when it cannot answer cheaply, since a page fetch that comes back empty is a far better failure than a collection that silently ends early.
hasPreviousPage	bool	4	Whether items exist before start_cursor. Exact when paging BACKWARD, advisory when paging FORWARD, on the same reasoning as has_next_page.