How can a server keep the Relay connection shape while paging by offset underneath?

## Why anyone would do this Two forces pull in opposite directions. On the client side, the connection shape is what the ecosystem expects: normalized caches know how to merge `edges` across pages, list and infinite-scroll components are generated against it, and a reviewer will ask why your new field is shaped differently from every other paged field in the schema. On the server side, the thing behind the field sometimes cannot do keyset paging at all — a reporting view, a search index that takes a page number, a stored procedure, or an upstream API whose only paging control is `page=3`. Packing the offset inside the cursor lets you satisfy both. The schema publishes a normal connection; the resolver pages by position underneath. ## What "opaque" licenses The cursor connections convention requires the `cursor` field to serialize as a `String` and instructs clients to treat it as an opaque token: pass it back unchanged, never parse it, never construct one. It says nothing about what is inside. Base64 is a convention adopted precisely to make the contents look unreadable and discourage clients from poking at them — it is encoding, not signing, and it protects nothing. So a positional payload is as legal as a sort key. `base64("offset:42")` is a valid cursor. ## The mechanics The whole implementation is a decode, a slice and an encode: ``` resolve herd.animals(first, after): start = (after == null) ? 0 : decodeOffset(after) + 1 pageSize = clamp(first ?? 25, 1, 100) rows = store.list(order = [birthDate ASC, id ASC], skip = start, take = pageSize + 1) // one extra hasNext = rows.size > pageSize page = rows.take(pageSize) edges = page.mapIndexed { i, row -> Edge(cursor = encodeOffset(start + i), node = row) } return Connection(edges, PageInfo( hasNextPage = hasNext, hasPreviousPage = start > 0, startCursor = edges.firstOrNull()?.cursor, endCursor = edges.lastOrNull()?.cursor)) ``` Two details are worth calling out. Fetching `pageSize + 1` rows and discarding the extra gives you `hasNextPage` without a second, full-predicate count — on a pedigree browser holding a 340 ms p99 budget for the field, that one trick is often the difference between meeting the budget and not. And `hasPreviousPage` is genuinely cheap here, because position zero is knowable: `start > 0` is the honest answer, which is more than a keyset implementation can usually say without extra work. ## What you keep The valuable thing you keep is **the freedom to change your mind**. Because the cursor is opaque, its contents are not part of your published contract. You can migrate this field from offsets to a real keyset cursor later with no SDL change, no client change and no breaking-change entry in a registry — only a decoder that recognises both payload shapes for as long as old cursors might still be in flight. Shipping an opaque cursor over an offset is often exactly that: a bridge, taken deliberately. ## What you give up You give up anchor semantics, and you should say so out loud rather than let a client discover it. A keyset cursor means "resume after the animal whose birth date is X and whose id is Y". An offset cursor means "resume at position 42 of whatever this ordering produces right now". Everything that is true of offset paging is therefore true of this connection, dressed in connection clothes: an insert before the window shifts every later position, so a row can appear on two consecutive pages or fall between them. A cursor stored on the client and replayed an hour later points somewhere arbitrary. And if the ordering is not total, position 42 need not even be the same animal across two identical requests. ## Guardrails * **Clamp the page size** in the resolver. `first` is just an `Int`; nothing else will bound it. * **Reject a cursor you cannot decode** as an error rather than silently falling back to offset zero — a silent fallback shows up as a user mysteriously restarting at the top of the list. * **Never document the encoding.** The moment one client base64-decodes your cursor and does arithmetic on it, the payload has become a contract and the migration path above is gone. * **Be explicit in the field's description** about the stability you actually offer, so that "duplicate rows while paging" arrives as a documented property rather than a bug report. ## When it is the right call Small or slow-changing collections, admin and back-office tables, a source that literally only offers page numbers, and any field you intend to migrate to keyset paging once the store can support it. It is the wrong call for a high-write feed with long-lived cursors, where the drift is constant and visible.