Leaderboard reference

Board config

What each field decides is on boards and windows; what the rank field costs is on what it costs.

FieldDefault
key—A URL path segment, and the entry key
stored1d1 only, today
direction—desc (highest wins) or asc (lap times). Immutable
aggregation—best · latest · sum. Immutable
window—CRON, UTC. Omit for all-time. Immutable
retainkeep allClosed windows to keep
retainDayskeep allDelete older than N days. Set one, not both
min, max—Server-side bounds
trackActivityfalseThe cost lever. True writes on every submission
tiers—Classified on read
serverAuthoritativetrue

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

KeyDefault
rank"live"Or { materialize: "<cron>" }
adminScopeThe hide and remove routes
submitScopeRequired when server-authoritative
basePath/leaderboard

Routes

RouteVerified by
GET /leaderboarduser
POST /leaderboard/:boarduser + submit scope when server-authoritative
GET /leaderboard/:board/topuser
GET /leaderboard/:board/meuser
GET /leaderboard/:board/arounduser
POST /leaderboard/:board/segmentuser
PUT /leaderboard/:board/me/visibilityuser
PUT /leaderboard/:board/entries/:userId/hiddenuser + admin scope
DELETE /leaderboard/:board/entries/:userIduser + 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.

RouteScope
GET /leaderboard/admin/boardsleaderboard:entries:readEvery board, its rank mode, and the window open now
GET /leaderboard/admin/boards/:board/entriesleaderboard:entries:readOne 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/locksleaderboard:entries:readThe rank-refresh lock, its holder and when it was taken
POST /leaderboard/admin/boards/:board/entries/:userId/hideleaderboard:entries:moderateHide an entry from every read. The score is kept
POST /leaderboard/admin/boards/:board/entries/:userId/unhideleaderboard:entries:moderatePut a hidden entry back
POST /leaderboard/admin/boards/:board/entries/:userId/correctleaderboard:entries:moderateSet an entry’s score, held to the board’s min and max
POST /leaderboard/admin/locks/:name/clearleaderboard:entries:moderateRelease 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 query80 — D1’s 100-parameter cap, less 10 the my-rank path spends
Rank refresh chunkPaces the walk, not a row count for one statement
Stale lock reclaim1 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_immutableOne of the four fixed fields changed
leaderboard/invalid_scheduleThe CRON did not parse
leaderboard/score_rejectedOutside min/max
leaderboard/submit_forbiddenServer-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.

ESC