@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/leaderboards/FileLeaderboardRankStore.js

@@ -0,0 +1,808 @@
+// The file rank store of the leaderboard service (game-server-leaderboards D1, DR §8): one JSON file per board season
+// plus players, player keys and dedupe files under <admin.dataDir>/leaderboards. It serves one process by definition, so
+// rate counters and session presence stay in memory. Writes go through the same keep-policy rule as the Redis script.
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { LEADERBOARD_DEDUPE_TTL_MS, LEADERBOARD_FILE_FLUSH_DELAY_MS, LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE } from "./LeaderboardConstants.js";
+import { applyKeepPolicy, compareRankedEntries, durabilityAdvice, parseRankKeyText, rankKeyText } from "./LeaderboardRules.js";
+/** Folder of the board season files. */
+const BOARDS_FOLDER = "boards";
+/** File of the player records. */
+const PLAYERS_FILE = "players.json";
+/** File of each player's rank keys. */
+const PLAYER_KEYS_FILE = "player-keys.json";
+/** File of the remembered submission results. */
+const DEDUPE_FILE = "dedupe.json";
+/** Prefix of a season file name. */
+const SEASON_FILE_PREFIX = "season-";
+/** Extension of every file. */
+const JSON_EXTENSION = ".json";
+/** Node's error code of a missing file. */
+const FILE_MISSING_CODE = "ENOENT";
+/** Rate and presence records kept in memory before expired ones are pruned. */
+const MEMORY_PRUNE_THRESHOLD = 10000;
+/** Rankings in files (D1, DR §8). */
+export class FileLeaderboardRankStore {
+    /** Always "file". */
+    kind = "file";
+    /** The store's folder (<admin.dataDir>/leaderboards). */
+    folder;
+    /** Whether the folder survives a redeploy (D20). */
+    isFolderPersistent;
+    /** Loaded season files by file key (`<boardId>/<seasonId>`). */
+    seasons = new Map();
+    /** Season loads in flight, so two callers share one read. */
+    seasonLoads = new Map();
+    /** Player records. */
+    players = new Map();
+    /** Player id → rank key texts. */
+    playerKeys = new Map();
+    /** Dedupe id → remembered result. */
+    dedupe = new Map();
+    /** Rate bucket → counter (memory only). */
+    rates = new Map();
+    /** `<sessionName>\n<subject>` → presence (memory only). */
+    presence = new Map();
+    /** File keys changed since the last flush. */
+    dirtyFiles = new Set();
+    /** The pending flush timer, or null. */
+    flushTimer = null;
+    /** Pending writes per file key, so a file's writes never interleave. */
+    writeChains = new Map();
+    /** The latest caller time seen (prunes expired dedupe records on flush). */
+    latestNowMs = 0;
+    /**
+     * Creates the store; open() loads the shared files.
+     * @param folder The store's folder.
+     * @param isFolderPersistent Whether the folder survives a redeploy.
+     */
+    constructor(folder, isFolderPersistent) {
+        this.folder = folder;
+        this.isFolderPersistent = isFolderPersistent;
+    }
+    /**
+     * Opens the store, loading players, player keys and dedupe records (season files load on first use).
+     * @param folder The store's folder (created on the first write).
+     * @param isFolderPersistent Whether the folder survives a redeploy (the admin store's isPersistent).
+     * @returns The store.
+     */
+    static async open(folder, isFolderPersistent) {
+        const store = new FileLeaderboardRankStore(folder, isFolderPersistent);
+        await store.loadSharedFiles();
+        return store;
+    }
+    /**
+     * Writes one score: dedupe, keep policy (applyKeepPolicy, the Lua's semantics), overflow, ranking and indexes.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    async write(request) {
+        const season = await this.loadSeason(request.key.boardId, request.key.seasonId);
+        this.latestNowMs = Math.max(this.latestNowMs, request.nowMs);
+        const remembered = (request.dedupeId != null) ? this.dedupe.get(request.dedupeId) : undefined;
+        if (remembered != null && remembered.expiresAtMs > request.nowMs)
+            return { ...remembered.result, status: "duplicate" };
+        const result = this.applyWrite(season, request);
+        if (request.dedupeId != null && result.status !== "overflow") {
+            this.dedupe.set(request.dedupeId, { expiresAtMs: request.nowMs + LEADERBOARD_DEDUPE_TTL_MS, result: result });
+            this.markDirty(DEDUPE_FILE);
+        }
+        return result;
+    }
+    /**
+     * Reads a page of a ranking.
+     * @param key The ranking.
+     * @param offset Zero-based index of the first entry.
+     * @param limit Most entries.
+     * @returns The ranked entries.
+     */
+    async readRange(key, offset, limit) {
+        const ranking = await this.findRanking(key);
+        if (ranking == null || limit <= 0)
+            return [];
+        return ranking.entries.slice(offset, offset + limit).map((entry, index) => ({ ...entry, rank: offset + index + 1 }));
+    }
+    /**
+     * Counts the live entries.
+     * @param key The ranking.
+     * @returns The count.
+     */
+    async count(key) {
+        const ranking = await this.findRanking(key);
+        return (ranking != null) ? ranking.entries.length : 0;
+    }
+    /**
+     * Reads one player's live entry and rank.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @returns The entry, or null.
+     */
+    async readEntry(key, playerId) {
+        const ranking = await this.findRanking(key);
+        if (ranking == null)
+            return null;
+        const index = indexOfPlayer(ranking, playerId);
+        return (index != null) ? { ...ranking.entries[index], rank: index + 1 } : null;
+    }
+    /**
+     * Reads the window around a player's entry, clamped to the ranking.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param window Entries above and below.
+     * @returns The entries, or [] when the player has none.
+     */
+    async readAround(key, playerId, window) {
+        const ranking = await this.findRanking(key);
+        const index = (ranking != null) ? indexOfPlayer(ranking, playerId) : undefined;
+        if (ranking == null || index == null)
+            return [];
+        const firstIndex = Math.max(0, index - window);
+        const lastIndex = Math.min(ranking.entries.length - 1, index + window);
+        return await this.readRange(key, firstIndex, lastIndex - firstIndex + 1);
+    }
+    /**
+     * Finds entries by display name or player id (case-insensitive), in rank order.
+     * @param key The ranking.
+     * @param text The text.
+     * @param limit Most entries.
+     * @returns The matches.
+     */
+    async searchEntries(key, text, limit) {
+        const ranking = await this.findRanking(key);
+        if (ranking == null)
+            return [];
+        const needle = text.toLowerCase();
+        const matches = [];
+        for (let i = 0; i < ranking.entries.length && matches.length < limit; i++) {
+            const entry = ranking.entries[i];
+            if (matchesText(entry.displayName, entry.playerId, needle))
+                matches.push({ ...entry, rank: i + 1 });
+        }
+        return matches;
+    }
+    /**
+     * Reads the removed entries, newest removal first.
+     * @param key The ranking.
+     * @returns The removed entries.
+     */
+    async readRemoved(key) {
+        const ranking = await this.findRanking(key);
+        if (ranking == null)
+            return [];
+        return Array.from(ranking.removed.values()).sort((first, second) => second.removedAt.localeCompare(first.removedAt));
+    }
+    /**
+     * Moves a live entry to the removed set.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param reason Why.
+     * @param removedBy Who.
+     * @param removedAt ISO time.
+     * @returns True when there was a live entry.
+     */
+    async removeEntry(key, playerId, reason, removedBy, removedAt) {
+        const ranking = await this.findRanking(key);
+        const entry = (ranking != null) ? takeEntry(ranking, playerId) : null;
+        if (ranking == null || entry == null)
+            return false;
+        ranking.removed.set(playerId, { entry: entry, reason: reason, removedBy: removedBy, removedAt: removedAt });
+        this.markDirty(seasonFileKey(key.boardId, key.seasonId));
+        return true;
+    }
+    /**
+     * Moves a removed entry back into the ranking.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param sortOrder The board's sort order.
+     * @returns "restored", "missing" or "liveEntryExists".
+     */
+    async restoreEntry(key, playerId, sortOrder) {
+        const ranking = await this.findRanking(key);
+        const removed = ranking?.removed.get(playerId);
+        if (ranking == null || removed == null)
+            return "missing";
+        if (ranking.entryByPlayer.has(playerId))
+            return "liveEntryExists";
+        ranking.removed.delete(playerId);
+        insertEntry(ranking, removed.entry, sortOrder);
+        this.addPlayerKey(playerId, rankKeyText(key));
+        this.markDirty(seasonFileKey(key.boardId, key.seasonId));
+        return "restored";
+    }
+    /**
+     * Lists the variant keys of a season, sorted.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The variant keys.
+     */
+    async listVariantKeys(boardId, seasonId) {
+        const season = await this.loadSeason(boardId, seasonId);
+        return Array.from(season.variants.keys()).sort();
+    }
+    /**
+     * Reads a board's last accepted write time across its season files.
+     * @param boardId The board.
+     * @returns ISO time, or null.
+     */
+    async readLastSubmissionAt(boardId) {
+        let latest = null;
+        for (const seasonId of await this.listSeasonIds(boardId)) {
+            const season = await this.loadSeason(boardId, seasonId);
+            if (season.lastSubmissionAt != null && (latest == null || season.lastSubmissionAt > latest))
+                latest = season.lastSubmissionAt;
+        }
+        return latest;
+    }
+    /**
+     * Empties a season (its file keeps only the last submission time) and unlinks it from its players.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns How many entries were deleted.
+     */
+    async deleteSeason(boardId, seasonId) {
+        const season = await this.loadSeason(boardId, seasonId);
+        let deletedCount = 0;
+        for (const [variantKey, ranking] of season.variants) {
+            const keyText = rankKeyText({ boardId: boardId, seasonId: seasonId, variantKey: variantKey });
+            const playerIds = new Set([...ranking.entryByPlayer.keys(), ...ranking.removed.keys()]);
+            for (const playerId of playerIds)
+                this.removePlayerKey(playerId, keyText);
+            deletedCount += ranking.entries.length + ranking.removed.size;
+        }
+        season.variants.clear();
+        this.markDirty(seasonFileKey(boardId, seasonId));
+        return deletedCount;
+    }
+    /**
+     * Deletes a board's folder after emptying its seasons.
+     * @param boardId The board.
+     * @param seasonIds Its seasons.
+     */
+    async deleteBoard(boardId, seasonIds) {
+        const knownSeasonIds = new Set([...seasonIds, ...await this.listSeasonIds(boardId)]);
+        for (const seasonId of knownSeasonIds) {
+            await this.deleteSeason(boardId, seasonId);
+            const fileKey = seasonFileKey(boardId, seasonId);
+            this.dirtyFiles.delete(fileKey);
+            await this.writeChains.get(fileKey);
+            this.seasons.delete(fileKey);
+            this.seasonLoads.delete(fileKey);
+        }
+        await rm(path.join(this.folder, BOARDS_FOLDER, boardId), { recursive: true, force: true });
+    }
+    /**
+     * Lists the rankings a player has an entry in.
+     * @param playerId The player.
+     * @returns The rank keys, sorted by their text.
+     */
+    async listPlayerRankKeys(playerId) {
+        const texts = this.playerKeys.get(playerId) ?? new Set();
+        return Array.from(texts).sort().map(parseRankKeyText);
+    }
+    /**
+     * Renames every entry of a player, live and removed.
+     * @param playerId The player.
+     * @param displayName The new name.
+     * @returns How many entries changed.
+     */
+    async renamePlayerEntries(playerId, displayName) {
+        let renamedCount = 0;
+        for (const key of await this.listPlayerRankKeys(playerId)) {
+            const ranking = await this.findRanking(key);
+            if (ranking == null)
+                continue;
+            const live = ranking.entryByPlayer.get(playerId);
+            if (live != null) {
+                live.displayName = displayName;
+                renamedCount++;
+            }
+            const removed = ranking.removed.get(playerId);
+            if (removed != null) {
+                removed.entry.displayName = displayName;
+                renamedCount++;
+            }
+            this.markDirty(seasonFileKey(key.boardId, key.seasonId));
+        }
+        return renamedCount;
+    }
+    /**
+     * Deletes every entry of a player, live and removed, and the player's rank keys.
+     * @param playerId The player.
+     * @returns How many entries were deleted.
+     */
+    async deletePlayerEntries(playerId) {
+        let deletedCount = 0;
+        for (const key of await this.listPlayerRankKeys(playerId)) {
+            const ranking = await this.findRanking(key);
+            if (ranking == null)
+                continue;
+            if (takeEntry(ranking, playerId) != null)
+                deletedCount++;
+            if (ranking.removed.delete(playerId))
+                deletedCount++;
+            this.markDirty(seasonFileKey(key.boardId, key.seasonId));
+        }
+        if (this.playerKeys.delete(playerId))
+            this.markDirty(PLAYER_KEYS_FILE);
+        return deletedCount;
+    }
+    /**
+     * Reads a player.
+     * @param playerId The player.
+     * @returns A copy of the record, or null.
+     */
+    async getPlayer(playerId) {
+        const record = this.players.get(playerId);
+        return (record != null) ? { ...record } : null;
+    }
+    /**
+     * Writes a player.
+     * @param record The record.
+     */
+    async putPlayer(record) {
+        this.players.set(record.playerId, { ...record });
+        this.markDirty(PLAYERS_FILE);
+    }
+    /**
+     * Deletes a player record.
+     * @param playerId The player.
+     * @returns True when it existed.
+     */
+    async deletePlayer(playerId) {
+        const existed = this.players.delete(playerId);
+        if (existed)
+            this.markDirty(PLAYERS_FILE);
+        return existed;
+    }
+    /**
+     * Finds players by display name or id (case-insensitive).
+     * @param text The text ("" matches any).
+     * @param limit Most players.
+     * @returns Copies of the matching records.
+     */
+    async searchPlayers(text, limit) {
+        const needle = text.toLowerCase();
+        const matches = [];
+        for (const record of this.players.values()) {
+            if (matches.length >= limit)
+                break;
+            if (matchesText(record.displayName, record.playerId, needle))
+                matches.push({ ...record });
+        }
+        return matches;
+    }
+    /**
+     * Counts every player.
+     * @returns The count.
+     */
+    async countPlayers() {
+        return this.players.size;
+    }
+    /**
+     * Counts one use in a fixed window, in memory.
+     * @param bucket What is limited.
+     * @param limit Most uses per window.
+     * @param windowMs The window, in milliseconds.
+     * @param nowMs The caller's clock.
+     * @returns True while within the limit.
+     */
+    async consumeRate(bucket, limit, windowMs, nowMs) {
+        if (this.rates.size >= MEMORY_PRUNE_THRESHOLD)
+            pruneExpired(this.rates, nowMs);
+        const windowStartMs = Math.floor(nowMs / windowMs) * windowMs;
+        const existing = this.rates.get(bucket);
+        const counter = (existing != null && existing.windowStartMs === windowStartMs)
+            ? existing
+            : { windowStartMs: windowStartMs, expiresAtMs: windowStartMs + windowMs, usedCount: 0 };
+        counter.usedCount++;
+        this.rates.set(bucket, counter);
+        return counter.usedCount <= limit;
+    }
+    /**
+     * Records a session join per subject, in memory; an earlier join that still counts wins.
+     * @param sessionName The session.
+     * @param subjects The subjects.
+     * @param joinedAtMs The join time.
+     * @param ttlMs How long it counts.
+     */
+    async recordSessionPresence(sessionName, subjects, joinedAtMs, ttlMs) {
+        if (this.presence.size >= MEMORY_PRUNE_THRESHOLD)
+            pruneExpired(this.presence, joinedAtMs);
+        for (const subject of subjects) {
+            const presenceKey = sessionName + "\n" + subject;
+            const existing = this.presence.get(presenceKey);
+            if (existing != null && existing.expiresAtMs > joinedAtMs)
+                continue;
+            this.presence.set(presenceKey, { joinedAtMs: joinedAtMs, expiresAtMs: joinedAtMs + ttlMs });
+        }
+    }
+    /**
+     * Reads a subject's join time, if it still counts.
+     * @param sessionName The session.
+     * @param subject The subject.
+     * @param nowMs The caller's clock.
+     * @returns The join time, or null.
+     */
+    async readSessionPresence(sessionName, subject, nowMs) {
+        const record = this.presence.get(sessionName + "\n" + subject);
+        return (record != null && record.expiresAtMs > nowMs) ? record.joinedAtMs : null;
+    }
+    /**
+     * Durability of the folder (D20): durable when the admin store says it persists.
+     * @returns The durability and advice.
+     */
+    async measureDurability() {
+        const durability = this.isFolderPersistent ? "durable" : "notDurable";
+        return { durability: durability, advice: durabilityAdvice(durability, "file") };
+    }
+    /** Writes every changed file and waits for the writes. */
+    async close() {
+        if (this.flushTimer != null)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = null;
+        await this.flush();
+        await Promise.all(Array.from(this.writeChains.values()));
+    }
+    /**
+     * Applies one write to a loaded season (no dedupe).
+     * @param season The season.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    applyWrite(season, request) {
+        const playerId = request.entry.playerId;
+        const existingRanking = season.variants.get(request.key.variantKey);
+        const current = existingRanking?.entryByPlayer.get(playerId) ?? null;
+        const total = (existingRanking != null) ? existingRanking.entries.length : 0;
+        const previousScore = (current != null) ? current.score : null;
+        const { outcome, stored } = applyKeepPolicy(request.keepPolicy, request.sortOrder, current, { ...request.entry });
+        if (Math.abs(stored.score) > LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE) {
+            return { status: "overflow", outcome: null, entry: null, previousScore: previousScore, rank: null, total: total };
+        }
+        if (outcome === "kept" && existingRanking != null) {
+            const keptIndex = indexOfPlayer(existingRanking, playerId) ?? 0;
+            return { status: "kept", outcome: outcome, entry: { ...stored }, previousScore: previousScore, rank: keptIndex + 1, total: total };
+        }
+        const ranking = existingRanking ?? createRanking();
+        season.variants.set(request.key.variantKey, ranking);
+        takeEntry(ranking, playerId, request.sortOrder);
+        const index = insertEntry(ranking, stored, request.sortOrder);
+        season.lastSubmissionAt = stored.submittedAt;
+        this.addPlayerKey(playerId, rankKeyText(request.key));
+        this.markDirty(seasonFileKey(request.key.boardId, request.key.seasonId));
+        return { status: "written", outcome: outcome, entry: { ...stored }, previousScore: previousScore, rank: index + 1, total: ranking.entries.length };
+    }
+    /**
+     * Finds a loaded ranking without creating it.
+     * @param key The ranking.
+     * @returns The ranking, or null.
+     */
+    async findRanking(key) {
+        const season = await this.loadSeason(key.boardId, key.seasonId);
+        return season.variants.get(key.variantKey) ?? null;
+    }
+    /**
+     * Loads a season file once (an empty season when it does not exist).
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The season held in memory.
+     */
+    loadSeason(boardId, seasonId) {
+        const fileKey = seasonFileKey(boardId, seasonId);
+        const loaded = this.seasons.get(fileKey);
+        if (loaded != null)
+            return Promise.resolve(loaded);
+        const pending = this.seasonLoads.get(fileKey);
+        if (pending != null)
+            return pending;
+        const load = this.readSeasonFile(fileKey).then((season) => {
+            this.seasons.set(fileKey, season);
+            this.seasonLoads.delete(fileKey);
+            return season;
+        });
+        this.seasonLoads.set(fileKey, load);
+        return load;
+    }
+    /**
+     * Reads a season file into memory form.
+     * @param fileKey The season's file key.
+     * @returns The season.
+     */
+    async readSeasonFile(fileKey) {
+        const file = await readJsonIfPresent(this.filePath(fileKey));
+        const season = { variants: new Map(), lastSubmissionAt: (file != null) ? file.lastSubmissionAt : null };
+        if (file == null)
+            return season;
+        for (const [variantKey, variant] of Object.entries(file.variants)) {
+            const ranking = createRanking();
+            ranking.entries = variant.entries;
+            for (const entry of variant.entries)
+                ranking.entryByPlayer.set(entry.playerId, entry);
+            for (const removed of variant.removed)
+                ranking.removed.set(removed.entry.playerId, removed);
+            season.variants.set(variantKey, ranking);
+        }
+        return season;
+    }
+    /**
+     * Lists the season ids that have a file for a board.
+     * @param boardId The board.
+     * @returns The season ids, plus those loaded in memory.
+     */
+    async listSeasonIds(boardId) {
+        const seasonIds = new Set();
+        const boardPrefix = boardId + "/";
+        for (const fileKey of this.seasons.keys()) {
+            if (fileKey.startsWith(boardPrefix))
+                seasonIds.add(Number(fileKey.slice(boardPrefix.length)));
+        }
+        let fileNames = [];
+        try {
+            fileNames = await readdir(path.join(this.folder, BOARDS_FOLDER, boardId));
+        }
+        catch (error) {
+            if (error.code !== FILE_MISSING_CODE)
+                throw error;
+        }
+        for (const fileName of fileNames) {
+            if (fileName.startsWith(SEASON_FILE_PREFIX) && fileName.endsWith(JSON_EXTENSION)) {
+                seasonIds.add(Number(fileName.slice(SEASON_FILE_PREFIX.length, -JSON_EXTENSION.length)));
+            }
+        }
+        return Array.from(seasonIds).filter((seasonId) => Number.isSafeInteger(seasonId)).sort((first, second) => first - second);
+    }
+    /** Loads the players, player keys and dedupe files. */
+    async loadSharedFiles() {
+        const players = await readJsonIfPresent(this.filePath(PLAYERS_FILE));
+        const playerKeys = await readJsonIfPresent(this.filePath(PLAYER_KEYS_FILE));
+        const dedupe = await readJsonIfPresent(this.filePath(DEDUPE_FILE));
+        this.players = new Map(Object.entries(players ?? {}));
+        this.playerKeys = new Map(Object.entries(playerKeys ?? {}).map(([playerId, texts]) => [playerId, new Set(texts)]));
+        this.dedupe = new Map(Object.entries(dedupe ?? {}));
+    }
+    /**
+     * Adds a rank key to a player's index.
+     * @param playerId The player.
+     * @param keyText The rank key text.
+     */
+    addPlayerKey(playerId, keyText) {
+        const texts = this.playerKeys.get(playerId) ?? new Set();
+        if (texts.has(keyText))
+            return;
+        texts.add(keyText);
+        this.playerKeys.set(playerId, texts);
+        this.markDirty(PLAYER_KEYS_FILE);
+    }
+    /**
+     * Removes a rank key from a player's index.
+     * @param playerId The player.
+     * @param keyText The rank key text.
+     */
+    removePlayerKey(playerId, keyText) {
+        const texts = this.playerKeys.get(playerId);
+        if (texts == null || !texts.delete(keyText))
+            return;
+        if (texts.size === 0)
+            this.playerKeys.delete(playerId);
+        this.markDirty(PLAYER_KEYS_FILE);
+    }
+    /**
+     * Marks a file changed and schedules a flush after LEADERBOARD_FILE_FLUSH_DELAY_MS.
+     * @param fileKey The file key (a season key or a shared file name).
+     */
+    markDirty(fileKey) {
+        this.dirtyFiles.add(fileKey);
+        if (this.flushTimer != null)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, LEADERBOARD_FILE_FLUSH_DELAY_MS);
+        this.flushTimer.unref();
+    }
+    /**
+     * Writes every changed file, each after its own pending write.
+     * @returns Resolves once the writes are queued and done.
+     */
+    async flush() {
+        const fileKeys = Array.from(this.dirtyFiles);
+        this.dirtyFiles.clear();
+        await Promise.all(fileKeys.map((fileKey) => this.serialize(fileKey, async () => await this.writeFileOf(fileKey))));
+    }
+    /**
+     * Writes one file from memory (an empty, never-submitted season file is deleted instead).
+     * @param fileKey The file key.
+     */
+    async writeFileOf(fileKey) {
+        const filePath = this.filePath(fileKey);
+        if (fileKey === PLAYERS_FILE)
+            return await writeFileAtomically(filePath, JSON.stringify(Object.fromEntries(this.players)));
+        if (fileKey === PLAYER_KEYS_FILE)
+            return await writeFileAtomically(filePath, JSON.stringify(Object.fromEntries(Array.from(this.playerKeys, ([playerId, texts]) => [playerId, Array.from(texts)]))));
+        if (fileKey === DEDUPE_FILE) {
+            pruneExpired(this.dedupe, this.latestNowMs);
+            return await writeFileAtomically(filePath, JSON.stringify(Object.fromEntries(this.dedupe)));
+        }
+        const season = this.seasons.get(fileKey);
+        if (season == null)
+            return;
+        if (season.variants.size === 0 && season.lastSubmissionAt == null)
+            return await deleteFileIfPresent(filePath);
+        await writeFileAtomically(filePath, JSON.stringify(toSeasonFile(season)));
+    }
+    /**
+     * Runs a task after the pending writes of one file.
+     * @param fileKey The file.
+     * @param task The task.
+     * @returns The task's result.
+     */
+    serialize(fileKey, task) {
+        const previous = this.writeChains.get(fileKey) ?? Promise.resolve();
+        const next = previous.then(task, task);
+        this.writeChains.set(fileKey, next.catch(() => undefined));
+        return next;
+    }
+    /**
+     * The path of a file key.
+     * @param fileKey A season key (`<boardId>/<seasonId>`) or a shared file name.
+     * @returns The absolute path.
+     */
+    filePath(fileKey) {
+        if (fileKey === PLAYERS_FILE || fileKey === PLAYER_KEYS_FILE || fileKey === DEDUPE_FILE)
+            return path.join(this.folder, fileKey);
+        const [boardId, seasonId] = fileKey.split("/");
+        return path.join(this.folder, BOARDS_FOLDER, boardId, SEASON_FILE_PREFIX + seasonId + JSON_EXTENSION);
+    }
+}
+/**
+ * The file key of a season.
+ * @param boardId The board.
+ * @param seasonId The season.
+ * @returns `<boardId>/<seasonId>`.
+ */
+function seasonFileKey(boardId, seasonId) {
+    return boardId + "/" + seasonId;
+}
+/**
+ * An empty ranking.
+ * @returns The ranking.
+ */
+function createRanking() {
+    return { entries: [], entryByPlayer: new Map(), indexByPlayer: null, removed: new Map() };
+}
+/**
+ * A player's index in a ranking (the index map is rebuilt once after changes).
+ * @param ranking The ranking.
+ * @param playerId The player.
+ * @returns The index, or undefined.
+ */
+function indexOfPlayer(ranking, playerId) {
+    if (ranking.indexByPlayer == null) {
+        ranking.indexByPlayer = new Map(ranking.entries.map((entry, index) => [entry.playerId, index]));
+    }
+    return ranking.indexByPlayer.get(playerId);
+}
+/**
+ * Removes a player's live entry from a ranking.
+ * @param ranking The ranking.
+ * @param playerId The player.
+ * @param sortOrder The board's sort order, which finds the entry by binary search; without it the index map is used.
+ * @returns The removed entry, or null.
+ */
+function takeEntry(ranking, playerId, sortOrder = null) {
+    const entry = ranking.entryByPlayer.get(playerId);
+    if (entry == null)
+        return null;
+    const searchedIndex = (sortOrder != null) ? sortedPositionOf(ranking, entry, sortOrder) : -1;
+    const index = (ranking.entries[searchedIndex] === entry) ? searchedIndex : indexOfPlayer(ranking, playerId);
+    if (index != null)
+        ranking.entries.splice(index, 1);
+    ranking.entryByPlayer.delete(playerId);
+    ranking.indexByPlayer = null;
+    return entry;
+}
+/**
+ * The first index whose entry does not rank above the given one (binary search with compareRankedEntries).
+ * @param ranking The ranking.
+ * @param entry The entry.
+ * @param sortOrder The board's sort order.
+ * @returns The index (entries.length when it ranks below every entry).
+ */
+function sortedPositionOf(ranking, entry, sortOrder) {
+    let low = 0;
+    let high = ranking.entries.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (compareRankedEntries(sortOrder, ranking.entries[middle], entry) < 0)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+/**
+ * Inserts an entry at its sorted position (binary search with compareRankedEntries).
+ * @param ranking The ranking.
+ * @param entry The entry.
+ * @param sortOrder The board's sort order.
+ * @returns The entry's index.
+ */
+function insertEntry(ranking, entry, sortOrder) {
+    const index = sortedPositionOf(ranking, entry, sortOrder);
+    ranking.entries.splice(index, 0, entry);
+    ranking.entryByPlayer.set(entry.playerId, entry);
+    ranking.indexByPlayer = null;
+    return index;
+}
+/**
+ * A season in its file form.
+ * @param season The season.
+ * @returns The file.
+ */
+function toSeasonFile(season) {
+    const variants = {};
+    for (const [variantKey, ranking] of season.variants) {
+        variants[variantKey] = { entries: ranking.entries, removed: Array.from(ranking.removed.values()) };
+    }
+    return { variants: variants, lastSubmissionAt: season.lastSubmissionAt };
+}
+/**
+ * Deletes map records whose expiresAtMs has passed.
+ * @param records The records.
+ * @param nowMs The time to compare with.
+ */
+function pruneExpired(records, nowMs) {
+    for (const [recordKey, record] of records) {
+        if (record.expiresAtMs <= nowMs)
+            records.delete(recordKey);
+    }
+}
+/**
+ * Whether a name or id contains a lower-case needle.
+ * @param displayName The name.
+ * @param playerId The id.
+ * @param needle The lower-case text ("" matches any).
+ * @returns True on a match.
+ */
+function matchesText(displayName, playerId, needle) {
+    return displayName.toLowerCase().includes(needle) || playerId.toLowerCase().includes(needle);
+}
+/**
+ * Reads a JSON file, or null when it does not exist.
+ * @param filePath The file.
+ * @returns The parsed value, or null.
+ */
+async function readJsonIfPresent(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === FILE_MISSING_CODE)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Deletes a file that may not exist.
+ * @param filePath The file.
+ */
+async function deleteFileIfPresent(filePath) {
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        if (error.code !== FILE_MISSING_CODE)
+            throw error;
+    }
+}
+/**
+ * Writes a file through a temporary file and a rename, so a crash never leaves half a file.
+ * @param filePath The file.
+ * @param text Its new text.
+ */
+async function writeFileAtomically(filePath, text) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const temporaryPath = filePath + ".tmp-" + process.pid;
+    await writeFile(temporaryPath, text, "utf8");
+    await rename(temporaryPath, filePath);
+}