Board config
What each field decides is on boards and windows; what the rank field costs is on what it costs.
| Field | Default | |
|---|---|---|
key | — | A URL path segment, and the entry key |
store | d1 | d1 only, today |
direction | — | desc (highest wins) or asc (lap times). Immutable |
aggregation | — | best · latest · sum. Immutable |
window | — | CRON, UTC. Omit for all-time. Immutable |
retain | keep all | Closed windows to keep |
retainDays | keep all | Delete older than N days. Set one, not both |
min, max | — | Server-side bounds |
trackActivity | false | The cost lever. True writes on every submission |
tiers | — | Classified on read |
serverAuthoritative | true |
store, direction, aggregation and window are immutable once a board has an entry. Changing one raises leaderboard/board_immutable on the next submission. A new definition means a new key.
Top-level config
| Key | Default | |
|---|---|---|
rank | "live" | Or { materialize: "<cron>" } |
adminScope | The hide and remove routes | |
submitScope | Required when server-authoritative | |
basePath | /leaderboard |
Routes
| Route | Verified by |
|---|---|
GET /leaderboard | user |
POST /leaderboard/:board | user + submit scope when server-authoritative |
GET /leaderboard/:board/top | user |
GET /leaderboard/:board/me | user |
GET /leaderboard/:board/around | user |
POST /leaderboard/:board/segment | user |
PUT /leaderboard/:board/me/visibility | user |
PUT /leaderboard/:board/entries/:userId/hidden | user + admin scope |
DELETE /leaderboard/:board/entries/:userId | user + admin scope |
Any read takes ?window=<key> to read a closed window.
There is no public surface. Without auth composed, every route denies. Using Leaderboard has the calls.
Management
With the control plane composed, a management client reads a board and moderates it with its own credential. Every path sits under admin/, so none can collide with a player route, and each is built from the mounted basePath.
| Route | Scope | |
|---|---|---|
GET /leaderboard/admin/boards | leaderboard:entries:read | Every board, its rank mode, and the window open now |
GET /leaderboard/admin/boards/:board/entries | leaderboard:entries:read | One window in the board’s own order, keyset-paged. Hidden and opted-out entries are in place, with no rank, each with the result that wrote it. Takes window, cursor, limit, userId and hidden |
GET /leaderboard/admin/locks | leaderboard:entries:read | The rank-refresh lock, its holder and when it was taken |
POST /leaderboard/admin/boards/:board/entries/:userId/hide | leaderboard:entries:moderate | Hide an entry from every read. The score is kept |
POST /leaderboard/admin/boards/:board/entries/:userId/unhide | leaderboard:entries:moderate | Put a hidden entry back |
POST /leaderboard/admin/boards/:board/entries/:userId/correct | leaderboard:entries:moderate | Set an entry’s score, held to the board’s min and max |
POST /leaderboard/admin/locks/:name/clear | leaderboard:entries:moderate | Release a stale lock, naming the holder the read showed |
Each act takes an idempotencyKey and a required reason. A replayed key answers what the first request did, writes nothing and emits nothing; the same key on another act is core/conflict. An act that names no window acts on the one open now, and its retry answers the window the first request acted on, even after a rollover. A blank reason is refused before anything is written.
The change and its row in pithy_leaderboard_moderations are one batch — the act, what it found, what it left, the reason, the connection and the operator — so a correction keeps the original score in the entry’s history as well as on its audit event. A correction takes the entry over: it keeps no result’s contributions, so a later void of the session it replaced leaves the operator’s number alone.
A clear names the holder the operator saw. A lock that has changed hands since is core/conflict, so a running refresh is never released. The lock is not per board — one rank-refresh row serializes the refresh across every board — which is why its routes are not under a board.
Each act that changed something writes one audit event, leaderboard/entry_hidden, leaderboard/entry_unhidden, leaderboard/entry_corrected or leaderboard/lock_cleared, severity warning. An act that found the entry already where it asked writes none. Ranks recompute by the board’s own mode: a live board on its next read, a materialized one on its next refresh pass, which also renumbers a closed window the act moved.
The read is all GETs, so pithy dashboard connect grants it by default; the acts are POSTs and never are. Neither is the adminScope above, which your own backend holds: a management client can never satisfy it, so these replace it on the management routes rather than stacking with it.
Limits
| Segment members per query | 80 — D1’s 100-parameter cap, less 10 the my-rank path spends |
| Rank refresh chunk | Paces the walk, not a row count for one statement |
| Stale lock reclaim | 1 hour, via LEADERBOARD_LOCK_STALE_MS |
| Storage | ~3 GB at 10M players, against a 10 GB cap |
Tie-breaking
Score, then earliest achievedAt, then user id.
Total ordering — no two entries tie, so dense-versus-competition ranking never arises and neither is implemented.
Resubmitting the same score does not reset achievedAt.
Error codes
Each is domain/reason, like every error code in the kit.
| Code | |
|---|---|
leaderboard/board_not_found | |
leaderboard/entry_not_found | |
leaderboard/board_immutable | One of the four fixed fields changed |
leaderboard/invalid_schedule | The CRON did not parse |
leaderboard/score_rejected | Outside min/max |
leaderboard/submit_forbidden | Server-authoritative, and no submit scope |
The worker
A cron-triggered Workflow doing the retention sweep and, if materialized, the rank refresh.
Needed when rank is materialized, or any board configures retention. A live board set keeping everything needs no worker.
It need not be separate — a Workflow class, a scheduled handler and one cron trigger fold into your app Worker. A cron trigger is the only hard requirement.
A D1 advisory lock keeps one refresh running at a time; a second instance skips rather than interleaving.
A lock that outlives a crashed instance ages out after the stale-reclaim time above, or a management client clears it by naming its holder.
What is not implemented
Dense ranking and competition ranking, because the ordering is total and neither can arise.
Any store but D1, today.
Creating or editing a board at runtime — boards are config. The management routes read and moderate a board; none defines one.