@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/leaderboards/RedisLeaderboardRankStore.js

@@ -0,0 +1,691 @@
+// The Redis rank store of the leaderboard service (game-server-leaderboards D1, DR §7), shared by every process of a
+// fleet. Rankings are sorted sets beside entry hashes; one Lua script does a whole submit atomically. Multi-key admin
+// operations run WATCH/MULTI on a connection of their own, never on the shared client.
+import { LEADERBOARD_DEDUPE_TTL_MS, LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE, LEADERBOARD_REDIS_PREFIX } from "./LeaderboardConstants.js";
+import { durabilityAdvice, parseRankKeyText, rankKeyText, sortValueOf } from "./LeaderboardRules.js";
+/**
+ * Atomic submit (D13–D15): dedupe, keep policy, ranking member, indexes and rank, in one round trip.
+ * KEYS: 1 rank zset, 2 entry hash, 3 player-keys set, 4 variants set, 5 dedupe key, 6 last-activity key.
+ * ARGV: 1 playerId, 2 keepPolicy, 3 sortOrder, 4 incoming entry JSON, 5 rankKeyText, 6 variantKey,
+ *       7 dedupe TTL ms ("" = no dedupe), 8 maximum absolute score.
+ * Returns {status, resultJson}.
+ */
+const SUBMIT_SCRIPT = `
+if ARGV[7] ~= '' then
+  local cached = redis.call('GET', KEYS[5])
+  if cached then return {'duplicate', cached} end
+end
+local incoming = cjson.decode(ARGV[4])
+local currentText = redis.call('HGET', KEYS[2], ARGV[1])
+local current = nil
+if currentText then current = cjson.decode(currentText) end
+local outcome = 'created'
+local stored = incoming
+local previousScore = cjson.null
+if current then
+  previousScore = current.score
+  if ARGV[2] == 'sum' then
+    stored.score = current.score + incoming.score
+    stored.submissionCount = current.submissionCount + 1
+    outcome = 'added'
+  elseif ARGV[2] == 'latest' then
+    stored.submissionCount = current.submissionCount + 1
+    outcome = 'replaced'
+  else
+    local isBetter = false
+    if ARGV[3] == 'lowerIsBetter' then isBetter = incoming.score < current.score else isBetter = incoming.score > current.score end
+    if isBetter then
+      stored.submissionCount = current.submissionCount + 1
+      outcome = 'improved'
+    else
+      outcome = 'kept'
+    end
+  end
+end
+if math.abs(stored.score) > tonumber(ARGV[8]) then
+  return {'overflow', cjson.encode({status = 'overflow', outcome = cjson.null, entry = cjson.null, previousScore = previousScore, rank = cjson.null, total = redis.call('ZCARD', KEYS[1])})}
+end
+local status = 'written'
+if outcome == 'kept' then
+  status = 'kept'
+  stored = current
+else
+  if current then redis.call('ZREM', KEYS[1], current.member) end
+  local sortValue = stored.score
+  if ARGV[3] == 'higherIsBetter' then sortValue = -stored.score end
+  stored.member = string.format('%013d', stored.achievedAtMs) .. '|' .. ARGV[1]
+  redis.call('ZADD', KEYS[1], sortValue, stored.member)
+  redis.call('HSET', KEYS[2], ARGV[1], cjson.encode(stored))
+  redis.call('SADD', KEYS[3], ARGV[5])
+  redis.call('SADD', KEYS[4], ARGV[6])
+  redis.call('SET', KEYS[6], stored.submittedAt)
+end
+local rank = redis.call('ZRANK', KEYS[1], stored.member) + 1
+local result = cjson.encode({status = status, outcome = outcome, entry = stored, previousScore = previousScore, rank = rank, total = redis.call('ZCARD', KEYS[1])})
+if ARGV[7] ~= '' then redis.call('SET', KEYS[5], result, 'PX', tonumber(ARGV[7])) end
+return {status, result}
+`;
+/** Number of keys SUBMIT_SCRIPT takes. */
+const SUBMIT_SCRIPT_KEY_COUNT = 6;
+/** Digits of the zero-padded achievedAtMs in a ranking member (D13). */
+const MEMBER_TIME_DIGITS = 13;
+/** Separator between the time and the player id in a ranking member. */
+const MEMBER_SEPARATOR = "|";
+/** HSCAN batch size of searches. */
+const SCAN_BATCH_SIZE = 500;
+/** Most hash fields one search scans. */
+const MAXIMUM_SEARCH_SCAN = 100000;
+/** Attempts of a watched transaction before it gives up. */
+const TRANSACTION_ATTEMPTS = 10;
+/** The cursor that starts and ends an HSCAN. */
+const SCAN_START_CURSOR = "0";
+/** The INFO line that says the append-only file is on. */
+const AOF_ENABLED_PATTERN = /^aof_enabled:1\s*$/m;
+/** The INFO line of the last RDB save time. */
+const RDB_LAST_SAVE_PATTERN = /^rdb_last_save_time:(\d+)\s*$/m;
+/** Rankings in Redis (D1, DR §7). */
+export class RedisLeaderboardRankStore {
+    /** Always "redis". */
+    kind = "redis";
+    /** The shared client (RedisPresence quits it). */
+    redis;
+    /** A connection of its own for WATCH/MULTI work, quit by close(). */
+    transactions;
+    /** The pending transaction, so this process runs one WATCH at a time on `transactions`. */
+    transactionQueue = Promise.resolve();
+    /**
+     * Wraps the shared client and opens the transaction connection.
+     * @param redis The ioredis client the admin store also uses.
+     */
+    constructor(redis) {
+        this.redis = redis;
+        this.transactions = redis.duplicate();
+    }
+    /**
+     * Writes one score through SUBMIT_SCRIPT.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    async write(request) {
+        const keyText = rankKeyText(request.key);
+        const playerId = request.entry.playerId;
+        const dedupeTtl = (request.dedupeId != null) ? String(LEADERBOARD_DEDUPE_TTL_MS) : "";
+        const incoming = toRedisEntry(request.entry, "");
+        const answer = await this.redis.eval(SUBMIT_SCRIPT, SUBMIT_SCRIPT_KEY_COUNT, this.rankKey(request.key), this.entryKey(request.key), this.playerKeysKey(playerId), this.variantsKey(request.key.boardId, request.key.seasonId), this.dedupeKey(request.dedupeId ?? ""), this.lastKey(request.key.boardId), playerId, request.keepPolicy, request.sortOrder, JSON.stringify(incoming), keyText, request.key.variantKey, dedupeTtl, String(LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE));
+        const [scriptStatus, resultJson] = answer;
+        const raw = JSON.parse(resultJson);
+        const status = (scriptStatus === "duplicate") ? "duplicate" : raw.status;
+        return {
+            status: status,
+            outcome: raw.outcome ?? null,
+            entry: (raw.entry != null) ? fromRedisEntry(raw.entry) : null,
+            previousScore: raw.previousScore ?? null,
+            rank: raw.rank ?? null,
+            total: raw.total
+        };
+    }
+    /**
+     * Reads a page of a ranking (ZRANGE then HMGET).
+     * @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) {
+        if (limit <= 0)
+            return [];
+        const members = await this.redis.zrange(this.rankKey(key), offset, offset + limit - 1);
+        if (members.length === 0)
+            return [];
+        const playerIds = members.map(playerIdOfMember);
+        const texts = await this.redis.hmget(this.entryKey(key), ...playerIds);
+        const ranked = [];
+        texts.forEach((text, index) => {
+            if (text != null)
+                ranked.push({ ...fromRedisEntry(JSON.parse(text)), rank: offset + index + 1 });
+        });
+        return ranked;
+    }
+    /**
+     * Counts the live entries (ZCARD).
+     * @param key The ranking.
+     * @returns The count.
+     */
+    async count(key) {
+        return await this.redis.zcard(this.rankKey(key));
+    }
+    /**
+     * Reads one player's live entry and its rank.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @returns The entry, or null.
+     */
+    async readEntry(key, playerId) {
+        const text = await this.redis.hget(this.entryKey(key), playerId);
+        if (text == null)
+            return null;
+        const stored = JSON.parse(text);
+        const index = await this.redis.zrank(this.rankKey(key), stored.member);
+        if (index == null)
+            return null;
+        return { ...fromRedisEntry(stored), rank: index + 1 };
+    }
+    /**
+     * 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 entry = await this.readEntry(key, playerId);
+        if (entry == null)
+            return [];
+        const total = await this.count(key);
+        const firstIndex = Math.max(0, entry.rank - 1 - window);
+        const lastIndex = Math.min(total - 1, entry.rank - 1 + window);
+        return await this.readRange(key, firstIndex, lastIndex - firstIndex + 1);
+    }
+    /**
+     * Finds entries by display name or player id (HSCAN, case-insensitive), sorted by rank.
+     * @param key The ranking.
+     * @param text The text.
+     * @param limit Most entries.
+     * @returns The matches.
+     */
+    async searchEntries(key, text, limit) {
+        const needle = text.toLowerCase();
+        const matches = await this.scanHash(this.entryKey(key), limit, (stored) => matchesText(stored.displayName, stored.playerId, needle));
+        const ranked = [];
+        for (const stored of matches) {
+            const index = await this.redis.zrank(this.rankKey(key), stored.member);
+            if (index != null)
+                ranked.push({ ...fromRedisEntry(stored), rank: index + 1 });
+        }
+        return ranked.sort((first, second) => first.rank - second.rank);
+    }
+    /**
+     * Reads the removed entries, newest removal first.
+     * @param key The ranking.
+     * @returns The removed entries.
+     */
+    async readRemoved(key) {
+        const texts = await this.redis.hvals(this.removedKey(key));
+        const removed = texts.map((text) => JSON.parse(text));
+        return removed.sort((first, second) => second.removedAt.localeCompare(first.removedAt));
+    }
+    /**
+     * Moves a live entry to the removed hash (watched MULTI).
+     * @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) {
+        return await this.runTransaction([this.entryKey(key)], async (client) => {
+            const text = await client.hget(this.entryKey(key), playerId);
+            if (text == null)
+                return { commands: null, result: false };
+            const stored = JSON.parse(text);
+            const removed = { entry: fromRedisEntry(stored), reason: reason, removedBy: removedBy, removedAt: removedAt };
+            const commands = client.multi()
+                .zrem(this.rankKey(key), stored.member)
+                .hdel(this.entryKey(key), playerId)
+                .hset(this.removedKey(key), playerId, JSON.stringify(removed));
+            return { commands: commands, result: true };
+        });
+    }
+    /**
+     * Moves a removed entry back into the ranking (watched MULTI).
+     * @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) {
+        return await this.runTransaction([this.entryKey(key), this.removedKey(key)], async (client) => {
+            const removedText = await client.hget(this.removedKey(key), playerId);
+            if (removedText == null)
+                return { commands: null, result: "missing" };
+            if ((await client.hexists(this.entryKey(key), playerId)) === 1)
+                return { commands: null, result: "liveEntryExists" };
+            const removed = JSON.parse(removedText);
+            const member = memberOf(removed.entry);
+            const commands = client.multi()
+                .hdel(this.removedKey(key), playerId)
+                .hset(this.entryKey(key), playerId, JSON.stringify(toRedisEntry(removed.entry, member)))
+                .zadd(this.rankKey(key), sortValueOf(sortOrder, removed.entry.score), member)
+                .sadd(this.playerKeysKey(playerId), rankKeyText(key))
+                .sadd(this.variantsKey(key.boardId, key.seasonId), key.variantKey);
+            return { commands: commands, result: "restored" };
+        });
+    }
+    /**
+     * Lists the variant keys written in a season (SMEMBERS), sorted.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The variant keys.
+     */
+    async listVariantKeys(boardId, seasonId) {
+        const variantKeys = await this.redis.smembers(this.variantsKey(boardId, seasonId));
+        return variantKeys.sort();
+    }
+    /**
+     * Reads a board's last accepted write time.
+     * @param boardId The board.
+     * @returns ISO time, or null.
+     */
+    async readLastSubmissionAt(boardId) {
+        return await this.redis.get(this.lastKey(boardId));
+    }
+    /**
+     * Deletes every ranking of a season 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 variantKeys = await this.redis.smembers(this.variantsKey(boardId, seasonId));
+        let deletedCount = 0;
+        for (const variantKey of variantKeys) {
+            deletedCount += await this.deleteRanking({ boardId: boardId, seasonId: seasonId, variantKey: variantKey });
+        }
+        await this.redis.del(this.variantsKey(boardId, seasonId));
+        return deletedCount;
+    }
+    /**
+     * Deletes every ranking of a board and its last-activity key.
+     * @param boardId The board.
+     * @param seasonIds Its seasons.
+     */
+    async deleteBoard(boardId, seasonIds) {
+        for (const seasonId of seasonIds)
+            await this.deleteSeason(boardId, seasonId);
+        await this.redis.del(this.lastKey(boardId));
+    }
+    /**
+     * 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 = await this.redis.smembers(this.playerKeysKey(playerId));
+        return 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)) {
+            renamedCount += await this.runTransaction([this.entryKey(key), this.removedKey(key)], async (client) => {
+                const entryText = await client.hget(this.entryKey(key), playerId);
+                const removedText = await client.hget(this.removedKey(key), playerId);
+                if (entryText == null && removedText == null)
+                    return { commands: null, result: 0 };
+                const commands = client.multi();
+                if (entryText != null) {
+                    const stored = JSON.parse(entryText);
+                    commands.hset(this.entryKey(key), playerId, JSON.stringify({ ...stored, displayName: displayName }));
+                }
+                if (removedText != null) {
+                    const removed = JSON.parse(removedText);
+                    commands.hset(this.removedKey(key), playerId, JSON.stringify({ ...removed, entry: { ...removed.entry, displayName: displayName } }));
+                }
+                const changedCount = ((entryText != null) ? 1 : 0) + ((removedText != null) ? 1 : 0);
+                return { commands: commands, result: changedCount };
+            });
+        }
+        return renamedCount;
+    }
+    /**
+     * Deletes every entry of a player, live and removed, and the player's ranking index.
+     * @param playerId The player.
+     * @returns How many entries were deleted.
+     */
+    async deletePlayerEntries(playerId) {
+        let deletedCount = 0;
+        for (const key of await this.listPlayerRankKeys(playerId)) {
+            deletedCount += await this.runTransaction([this.entryKey(key), this.removedKey(key)], async (client) => {
+                const entryText = await client.hget(this.entryKey(key), playerId);
+                const hasRemoved = (await client.hexists(this.removedKey(key), playerId)) === 1;
+                const commands = client.multi().hdel(this.entryKey(key), playerId).hdel(this.removedKey(key), playerId);
+                if (entryText != null)
+                    commands.zrem(this.rankKey(key), JSON.parse(entryText).member);
+                const removedCount = ((entryText != null) ? 1 : 0) + (hasRemoved ? 1 : 0);
+                return { commands: commands, result: removedCount };
+            });
+        }
+        await this.redis.del(this.playerKeysKey(playerId));
+        return deletedCount;
+    }
+    /**
+     * Reads a player.
+     * @param playerId The player.
+     * @returns The record, or null.
+     */
+    async getPlayer(playerId) {
+        const text = await this.redis.hget(this.playersKey(), playerId);
+        return (text != null) ? JSON.parse(text) : null;
+    }
+    /**
+     * Writes a player.
+     * @param record The record.
+     */
+    async putPlayer(record) {
+        await this.redis.hset(this.playersKey(), record.playerId, JSON.stringify(record));
+    }
+    /**
+     * Deletes a player record.
+     * @param playerId The player.
+     * @returns True when it existed.
+     */
+    async deletePlayer(playerId) {
+        return (await this.redis.hdel(this.playersKey(), playerId)) > 0;
+    }
+    /**
+     * Finds players by display name or id (HSCAN, case-insensitive).
+     * @param text The text ("" matches any).
+     * @param limit Most players.
+     * @returns The players.
+     */
+    async searchPlayers(text, limit) {
+        const needle = text.toLowerCase();
+        return await this.scanHash(this.playersKey(), limit, (record) => matchesText(record.displayName, record.playerId, needle));
+    }
+    /**
+     * Counts every player (HLEN).
+     * @returns The count.
+     */
+    async countPlayers() {
+        return await this.redis.hlen(this.playersKey());
+    }
+    /**
+     * Counts one use in a fixed window (INCR, PEXPIRE on the first use).
+     * @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) {
+        const windowStartMs = Math.floor(nowMs / windowMs) * windowMs;
+        const key = this.rateKey(bucket, windowStartMs);
+        const usedCount = await this.redis.incr(key);
+        if (usedCount === 1)
+            await this.redis.pexpire(key, windowMs);
+        return usedCount <= limit;
+    }
+    /**
+     * Records a session join per subject (SET NX PX: the earliest join 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) {
+        const record = { joinedAtMs: joinedAtMs, expiresAtMs: joinedAtMs + ttlMs };
+        for (const subject of subjects) {
+            await this.redis.set(this.presenceKey(sessionName, subject), JSON.stringify(record), "PX", ttlMs, "NX");
+        }
+    }
+    /**
+     * Reads a subject's join time, if it still counts at the caller's time.
+     * @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 text = await this.redis.get(this.presenceKey(sessionName, subject));
+        if (text == null)
+            return null;
+        const record = JSON.parse(text);
+        return (record.expiresAtMs > nowMs) ? record.joinedAtMs : null;
+    }
+    /**
+     * Measures durability from INFO persistence and CONFIG GET save (D20).
+     * @returns The durability and advice.
+     */
+    async measureDurability() {
+        try {
+            const info = await this.redis.info("persistence");
+            const saveAnswer = await this.redis.config("GET", "save");
+            const saveRule = (Array.isArray(saveAnswer) && typeof saveAnswer[1] === "string") ? saveAnswer[1] : "";
+            const lastSaveMatch = info.match(RDB_LAST_SAVE_PATTERN);
+            const lastSaveTime = (lastSaveMatch != null) ? Number(lastSaveMatch[1]) : 0;
+            const isDurable = AOF_ENABLED_PATTERN.test(info) || (lastSaveTime > 0 && saveRule.trim() !== "");
+            const durability = isDurable ? "durable" : "notDurable";
+            return { durability: durability, advice: durabilityAdvice(durability, "redis") };
+        }
+        catch {
+            return { durability: "unknown", advice: durabilityAdvice("unknown", "redis") };
+        }
+    }
+    /** Quits the transaction connection (the shared client is left to RedisPresence). */
+    async close() {
+        await this.transactionQueue;
+        try {
+            await this.transactions.quit();
+        }
+        catch {
+            this.transactions.disconnect();
+        }
+    }
+    /**
+     * Deletes one ranking (its zset, entries and removed entries) and unlinks it from its players.
+     * @param key The ranking.
+     * @returns How many entries were deleted.
+     */
+    async deleteRanking(key) {
+        const keyText = rankKeyText(key);
+        const livePlayers = await this.redis.hkeys(this.entryKey(key));
+        const removedPlayers = await this.redis.hkeys(this.removedKey(key));
+        const commands = this.transactions.multi();
+        for (const playerId of new Set([...livePlayers, ...removedPlayers]))
+            commands.srem(this.playerKeysKey(playerId), keyText);
+        commands.del(this.rankKey(key), this.entryKey(key), this.removedKey(key));
+        await this.queued(async () => await commands.exec());
+        return livePlayers.length + removedPlayers.length;
+    }
+    /**
+     * Runs a watched read-then-MULTI on the transaction connection, retried while another writer changes a watched key.
+     * @param watchKeys The keys to WATCH.
+     * @param plan Reads (through the given client) and returns the MULTI to commit, or null for none.
+     * @returns The plan's result.
+     * @throws Error when another writer changed a watched key on every attempt.
+     */
+    runTransaction(watchKeys, plan) {
+        return this.queued(async () => {
+            for (let attempt = 0; attempt < TRANSACTION_ATTEMPTS; attempt++) {
+                await this.transactions.watch(...watchKeys);
+                const decided = await plan(this.transactions);
+                if (decided.commands == null) {
+                    await this.transactions.unwatch();
+                    return decided.result;
+                }
+                const committed = await decided.commands.exec();
+                if (committed != null)
+                    return decided.result;
+            }
+            throw new Error("leaderboard transaction on " + watchKeys.join(", ") + " kept conflicting after " + TRANSACTION_ATTEMPTS + " attempts");
+        });
+    }
+    /**
+     * Runs a task after the pending one on the transaction connection.
+     * @param task The task.
+     * @returns The task's result.
+     */
+    queued(task) {
+        const next = this.transactionQueue.then(task, task);
+        this.transactionQueue = next.catch(() => undefined);
+        return next;
+    }
+    /**
+     * Scans a hash of JSON values with HSCAN, keeping the matches.
+     * @param hashKey The hash.
+     * @param limit Most matches.
+     * @param accept Whether a value matches.
+     * @returns The matching values.
+     */
+    async scanHash(hashKey, limit, accept) {
+        const matches = [];
+        let cursor = SCAN_START_CURSOR;
+        let scannedCount = 0;
+        do {
+            const [nextCursor, fields] = await this.redis.hscan(hashKey, cursor, "COUNT", SCAN_BATCH_SIZE);
+            for (let i = 1; i < fields.length && matches.length < limit; i += 2) {
+                const value = JSON.parse(fields[i]);
+                if (accept(value))
+                    matches.push(value);
+            }
+            scannedCount += fields.length / 2;
+            cursor = nextCursor;
+        } while (cursor !== SCAN_START_CURSOR && matches.length < limit && scannedCount < MAXIMUM_SEARCH_SCAN);
+        return matches;
+    }
+    /**
+     * The sorted set of a ranking.
+     * @param key The ranking.
+     * @returns The Redis key.
+     */
+    rankKey(key) {
+        return LEADERBOARD_REDIS_PREFIX + "rank:" + rankKeyText(key);
+    }
+    /**
+     * The entry hash of a ranking.
+     * @param key The ranking.
+     * @returns The Redis key.
+     */
+    entryKey(key) {
+        return LEADERBOARD_REDIS_PREFIX + "entry:" + rankKeyText(key);
+    }
+    /**
+     * The removed-entry hash of a ranking.
+     * @param key The ranking.
+     * @returns The Redis key.
+     */
+    removedKey(key) {
+        return LEADERBOARD_REDIS_PREFIX + "removed:" + rankKeyText(key);
+    }
+    /**
+     * The set of variant keys of a season.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The Redis key.
+     */
+    variantsKey(boardId, seasonId) {
+        return LEADERBOARD_REDIS_PREFIX + "variants:" + boardId + ":" + seasonId;
+    }
+    /**
+     * The last-activity key of a board.
+     * @param boardId The board.
+     * @returns The Redis key.
+     */
+    lastKey(boardId) {
+        return LEADERBOARD_REDIS_PREFIX + "last:" + boardId;
+    }
+    /**
+     * The players hash.
+     * @returns The Redis key.
+     */
+    playersKey() {
+        return LEADERBOARD_REDIS_PREFIX + "players";
+    }
+    /**
+     * The set of a player's rank keys.
+     * @param playerId The player.
+     * @returns The Redis key.
+     */
+    playerKeysKey(playerId) {
+        return LEADERBOARD_REDIS_PREFIX + "player-keys:" + playerId;
+    }
+    /**
+     * The cached result of one submission.
+     * @param dedupeId `<submissionId>|<boardId>|<variantKey>`.
+     * @returns The Redis key.
+     */
+    dedupeKey(dedupeId) {
+        return LEADERBOARD_REDIS_PREFIX + "dedupe:" + dedupeId;
+    }
+    /**
+     * The counter of one rate window.
+     * @param bucket What is limited.
+     * @param windowStartMs The window's start.
+     * @returns The Redis key.
+     */
+    rateKey(bucket, windowStartMs) {
+        return LEADERBOARD_REDIS_PREFIX + "rate:" + bucket + ":" + windowStartMs;
+    }
+    /**
+     * The presence record of a subject in a session.
+     * @param sessionName The session.
+     * @param subject The subject.
+     * @returns The Redis key.
+     */
+    presenceKey(sessionName, subject) {
+        return LEADERBOARD_REDIS_PREFIX + "presence:" + sessionName + ":" + subject;
+    }
+}
+/**
+ * An entry in its Redis form: metadata as text, plus its ranking member.
+ * @param entry The entry.
+ * @param member The ranking member ("" for an incoming entry; the script sets it).
+ * @returns The Redis form.
+ */
+function toRedisEntry(entry, member) {
+    const { metadata, ...rest } = entry;
+    return { ...rest, metadataText: (metadata != null) ? JSON.stringify(metadata) : null, member: member };
+}
+/**
+ * An entry from its Redis form, without the member.
+ * @param record The Redis form.
+ * @returns The entry.
+ */
+function fromRedisEntry(record) {
+    return {
+        playerId: record.playerId,
+        displayName: record.displayName,
+        score: record.score,
+        metadata: (record.metadataText != null) ? JSON.parse(record.metadataText) : null,
+        trustLevel: record.trustLevel,
+        sessionName: record.sessionName,
+        gameMode: record.gameMode,
+        buildVersion: record.buildVersion,
+        submittedAt: record.submittedAt,
+        achievedAt: record.achievedAt,
+        achievedAtMs: record.achievedAtMs,
+        submissionCount: record.submissionCount
+    };
+}
+/**
+ * The ranking member of an entry: zero-padded achievedAtMs, `|`, playerId (D13).
+ * @param entry The entry.
+ * @returns The member.
+ */
+function memberOf(entry) {
+    return String(entry.achievedAtMs).padStart(MEMBER_TIME_DIGITS, "0") + MEMBER_SEPARATOR + entry.playerId;
+}
+/**
+ * The player id of a ranking member (everything after the first `|`).
+ * @param member The member.
+ * @returns The player id.
+ */
+function playerIdOfMember(member) {
+    return member.slice(member.indexOf(MEMBER_SEPARATOR) + 1);
+}
+/**
+ * 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);
+}