supabase / auth / 29920946770

72%

Build Type

push

github

Committed by web-flow

Commit Message

feat: add cursor-based pagination for admin users list (#2633)

## What

Adds cursor-based (keyset) pagination to `GET /admin/users`, behind a
new
experimental feature flag. Offset pagination's `COUNT(*)` + `OFFSET`
deep-scan
is the primary cause of request timeouts on large user tables; keyset
paging
removes both, making page fetches constant-time regardless of how deep
you page.

  ## Feature flag

  `GOTRUE_EXPERIMENTAL_CURSOR_PAGINATION_ENABLED` (default `false`) →
  `Experimental.CursorPaginationEnabled`.

**Nothing changes unless you opt in.** With the flag off, the endpoint
behaves
  exactly as today. Mode selection:

  ## API (cursor mode)

  Request: `GET /admin/users?limit=50&cursor=<opaque>`
  - `limit`: default 50, capped at 1000, `0`/invalid → 400
- `cursor`: opaque base64url token; absent = first page; malformed → 400

  Response adds a `pagination` block and a `Link: rel="next"` header:
  ```json
  { "users": [ ... ], "aud": "authenticated",
    "pagination": { "next_cursor": "eyJ...", "has_more": true } }
```
`next_cursor`/`Link` are omitted on the last page. No X-Total-Count in cursor
mode: `has_more` signals whether more pages exist. Forward-only for now.

##   Notes

  - Orders by (created_at, id); the id tiebreaker is required because creaxed_at isn't unique (batch/seeded/migrated users share timestamps).
  - No migration: reuses the existing idx_users_created_at_desc
  - Cursors are opaque but unsigned; aud/instance_id filters still apply, so tampering only yields a different valid start point or a 400, never unauthorized data.
  - Scoped to `adminUsers` now ; the cursor helper is built to be reused for OAuth clients and audit logs in a follow-up.

Coverage Stats

134 of 142 new or added lines in 3 files covered. (94.37%)

3 existing lines in 1 file now uncovered.

18223 of 25356 relevant lines covered (71.87%)

663.22 hits per line