@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/leaderboards/RedisLeaderboardRankStore.d.ts

@@ -0,0 +1,282 @@
+import type { Redis } from "ioredis";
+import type { LeaderboardSortOrder } from "../admin/AdminApiTypes.js";
+import type { LeaderboardDurability, LeaderboardPlayerRecord, LeaderboardRankKey, LeaderboardRankStore, LeaderboardWriteRequest, LeaderboardWriteResult, RankedLeaderboardEntry, RemovedLeaderboardEntry } from "./LeaderboardRankStore.js";
+/** Rankings in Redis (D1, DR §7). */
+export declare class RedisLeaderboardRankStore implements LeaderboardRankStore {
+    /** Always "redis". */
+    readonly kind: "redis";
+    /** The shared client (RedisPresence quits it). */
+    private readonly redis;
+    /** A connection of its own for WATCH/MULTI work, quit by close(). */
+    private readonly transactions;
+    /** The pending transaction, so this process runs one WATCH at a time on `transactions`. */
+    private transactionQueue;
+    /**
+     * Wraps the shared client and opens the transaction connection.
+     * @param redis The ioredis client the admin store also uses.
+     */
+    constructor(redis: Redis);
+    /**
+     * Writes one score through SUBMIT_SCRIPT.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    write(request: LeaderboardWriteRequest): Promise<LeaderboardWriteResult>;
+    /**
+     * 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.
+     */
+    readRange(key: LeaderboardRankKey, offset: number, limit: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Counts the live entries (ZCARD).
+     * @param key The ranking.
+     * @returns The count.
+     */
+    count(key: LeaderboardRankKey): Promise<number>;
+    /**
+     * Reads one player's live entry and its rank.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @returns The entry, or null.
+     */
+    readEntry(key: LeaderboardRankKey, playerId: string): Promise<RankedLeaderboardEntry | 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.
+     */
+    readAround(key: LeaderboardRankKey, playerId: string, window: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * 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.
+     */
+    searchEntries(key: LeaderboardRankKey, text: string, limit: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Reads the removed entries, newest removal first.
+     * @param key The ranking.
+     * @returns The removed entries.
+     */
+    readRemoved(key: LeaderboardRankKey): Promise<RemovedLeaderboardEntry[]>;
+    /**
+     * 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.
+     */
+    removeEntry(key: LeaderboardRankKey, playerId: string, reason: string, removedBy: string, removedAt: string): Promise<boolean>;
+    /**
+     * 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".
+     */
+    restoreEntry(key: LeaderboardRankKey, playerId: string, sortOrder: LeaderboardSortOrder): Promise<"restored" | "missing" | "liveEntryExists">;
+    /**
+     * Lists the variant keys written in a season (SMEMBERS), sorted.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The variant keys.
+     */
+    listVariantKeys(boardId: string, seasonId: number): Promise<string[]>;
+    /**
+     * Reads a board's last accepted write time.
+     * @param boardId The board.
+     * @returns ISO time, or null.
+     */
+    readLastSubmissionAt(boardId: string): Promise<string | null>;
+    /**
+     * 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.
+     */
+    deleteSeason(boardId: string, seasonId: number): Promise<number>;
+    /**
+     * Deletes every ranking of a board and its last-activity key.
+     * @param boardId The board.
+     * @param seasonIds Its seasons.
+     */
+    deleteBoard(boardId: string, seasonIds: number[]): Promise<void>;
+    /**
+     * Lists the rankings a player has an entry in.
+     * @param playerId The player.
+     * @returns The rank keys, sorted by their text.
+     */
+    listPlayerRankKeys(playerId: string): Promise<LeaderboardRankKey[]>;
+    /**
+     * Renames every entry of a player, live and removed.
+     * @param playerId The player.
+     * @param displayName The new name.
+     * @returns How many entries changed.
+     */
+    renamePlayerEntries(playerId: string, displayName: string): Promise<number>;
+    /**
+     * 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.
+     */
+    deletePlayerEntries(playerId: string): Promise<number>;
+    /**
+     * Reads a player.
+     * @param playerId The player.
+     * @returns The record, or null.
+     */
+    getPlayer(playerId: string): Promise<LeaderboardPlayerRecord | null>;
+    /**
+     * Writes a player.
+     * @param record The record.
+     */
+    putPlayer(record: LeaderboardPlayerRecord): Promise<void>;
+    /**
+     * Deletes a player record.
+     * @param playerId The player.
+     * @returns True when it existed.
+     */
+    deletePlayer(playerId: string): Promise<boolean>;
+    /**
+     * Finds players by display name or id (HSCAN, case-insensitive).
+     * @param text The text ("" matches any).
+     * @param limit Most players.
+     * @returns The players.
+     */
+    searchPlayers(text: string, limit: number): Promise<LeaderboardPlayerRecord[]>;
+    /**
+     * Counts every player (HLEN).
+     * @returns The count.
+     */
+    countPlayers(): Promise<number>;
+    /**
+     * 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.
+     */
+    consumeRate(bucket: string, limit: number, windowMs: number, nowMs: number): Promise<boolean>;
+    /**
+     * 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.
+     */
+    recordSessionPresence(sessionName: string, subjects: string[], joinedAtMs: number, ttlMs: number): Promise<void>;
+    /**
+     * 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.
+     */
+    readSessionPresence(sessionName: string, subject: string, nowMs: number): Promise<number | null>;
+    /**
+     * Measures durability from INFO persistence and CONFIG GET save (D20).
+     * @returns The durability and advice.
+     */
+    measureDurability(): Promise<LeaderboardDurability>;
+    /** Quits the transaction connection (the shared client is left to RedisPresence). */
+    close(): Promise<void>;
+    /**
+     * 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.
+     */
+    private deleteRanking;
+    /**
+     * 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.
+     */
+    private runTransaction;
+    /**
+     * Runs a task after the pending one on the transaction connection.
+     * @param task The task.
+     * @returns The task's result.
+     */
+    private queued;
+    /**
+     * 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.
+     */
+    private scanHash;
+    /**
+     * The sorted set of a ranking.
+     * @param key The ranking.
+     * @returns The Redis key.
+     */
+    private rankKey;
+    /**
+     * The entry hash of a ranking.
+     * @param key The ranking.
+     * @returns The Redis key.
+     */
+    private entryKey;
+    /**
+     * The removed-entry hash of a ranking.
+     * @param key The ranking.
+     * @returns The Redis key.
+     */
+    private removedKey;
+    /**
+     * The set of variant keys of a season.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The Redis key.
+     */
+    private variantsKey;
+    /**
+     * The last-activity key of a board.
+     * @param boardId The board.
+     * @returns The Redis key.
+     */
+    private lastKey;
+    /**
+     * The players hash.
+     * @returns The Redis key.
+     */
+    private playersKey;
+    /**
+     * The set of a player's rank keys.
+     * @param playerId The player.
+     * @returns The Redis key.
+     */
+    private playerKeysKey;
+    /**
+     * The cached result of one submission.
+     * @param dedupeId `<submissionId>|<boardId>|<variantKey>`.
+     * @returns The Redis key.
+     */
+    private dedupeKey;
+    /**
+     * The counter of one rate window.
+     * @param bucket What is limited.
+     * @param windowStartMs The window's start.
+     * @returns The Redis key.
+     */
+    private rateKey;
+    /**
+     * The presence record of a subject in a session.
+     * @param sessionName The session.
+     * @param subject The subject.
+     * @returns The Redis key.
+     */
+    private presenceKey;
+}