@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/leaderboards/LeaderboardConstants.d.ts

@@ -0,0 +1,63 @@
+import type { LeaderboardRules } from "../admin/AdminApiTypes.js";
+/** Path prefix of the public leaderboard API (D5). */
+export declare const LEADERBOARD_API_PREFIX: string;
+/** Largest public request body, in bytes. */
+export declare const LEADERBOARD_MAX_BODY_BYTES: number;
+/** Largest absolute score: 13 digits stay exact through Redis's Lua cjson (D12). */
+export declare const LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE: number;
+/** Slack a time score may exceed the run's duration by, and session presence's slack, in milliseconds (D10, D12). */
+export declare const LEADERBOARD_DURATION_TOLERANCE_MS: number;
+/** How long a session join counts for session-level trust, in milliseconds (6 h, D10). */
+export declare const LEADERBOARD_SESSION_WINDOW_MS: number;
+/** How long a submission id is remembered for exactly-once delivery, in milliseconds (7 days, D15). */
+export declare const LEADERBOARD_DEDUPE_TTL_MS: number;
+/** Variant key of a board without dimensions (D16). */
+export declare const LEADERBOARD_ALL_VARIANT_KEY: string;
+/** Most dimensions one board may declare. */
+export declare const LEADERBOARD_MAXIMUM_DIMENSIONS: number;
+/** Most values one dimension may allow. */
+export declare const LEADERBOARD_MAXIMUM_DIMENSION_VALUES: number;
+/** Longest dimension value. */
+export declare const LEADERBOARD_MAXIMUM_VALUE_LENGTH: number;
+/** Longest display name. */
+export declare const LEADERBOARD_MAXIMUM_NAME_LENGTH: number;
+/** Most entries one public read returns. */
+export declare const LEADERBOARD_MAXIMUM_PAGE_SIZE: number;
+/** Default entries of a public read. */
+export declare const LEADERBOARD_DEFAULT_PAGE_SIZE: number;
+/** Most entries above and below a player in an around-me read. */
+export declare const LEADERBOARD_MAXIMUM_AROUND_WINDOW: number;
+/** Most targets in one my-entries read. */
+export declare const LEADERBOARD_MAXIMUM_TARGETS: number;
+/** Per-process cache life of top-N reads, in milliseconds (D19). */
+export declare const LEADERBOARD_READ_CACHE_MS: number;
+/** Per-process cache life of board definitions and rules, in milliseconds (D19). */
+export declare const LEADERBOARD_DEFINITION_CACHE_MS: number;
+/** Lease name of the scheduler (D17). */
+export declare const LEADERBOARD_SCHEDULER_LEASE: string;
+/** Lease life of the scheduler, in milliseconds. */
+export declare const LEADERBOARD_SCHEDULER_LEASE_TTL_MS: number;
+/** Milliseconds between scheduler ticks. */
+export declare const LEADERBOARD_SCHEDULER_TICK_MS: number;
+/** Activity records kept (D21). */
+export declare const LEADERBOARD_ACTIVITY_KEEP: number;
+/** Redis key prefix of the rank store. */
+export declare const LEADERBOARD_REDIS_PREFIX: string;
+/** Folder of the file rank store below admin.dataDir. */
+export declare const LEADERBOARD_DATA_FOLDER: string;
+/** Milliseconds the file rank store waits before writing a changed file. */
+export declare const LEADERBOARD_FILE_FLUSH_DELAY_MS: number;
+/** Admin store document id of the rules (collection "leaderboardSettings"). */
+export declare const LEADERBOARD_RULES_DOCUMENT_ID: string;
+/** Rules used until an admin saves others (D19). */
+export declare const DEFAULT_LEADERBOARD_RULES: LeaderboardRules;
+/** Milliseconds in one minute. */
+export declare const MILLISECONDS_PER_MINUTE: number;
+/** Milliseconds in one hour. */
+export declare const MILLISECONDS_PER_HOUR: number;
+/** Board id pattern. */
+export declare const BOARD_ID_PATTERN: RegExp;
+/** Dimension name pattern. */
+export declare const DIMENSION_NAME_PATTERN: RegExp;
+/** Submission id pattern. */
+export declare const SUBMISSION_ID_PATTERN: RegExp;

package/lib/leaderboards/LeaderboardConstants.js

@@ -0,0 +1,70 @@
+/** Path prefix of the public leaderboard API (D5). */
+export const LEADERBOARD_API_PREFIX = "/game-server/leaderboards/";
+/** Largest public request body, in bytes. */
+export const LEADERBOARD_MAX_BODY_BYTES = 65536;
+/** Largest absolute score: 13 digits stay exact through Redis's Lua cjson (D12). */
+export const LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE = 9999999999999;
+/** Slack a time score may exceed the run's duration by, and session presence's slack, in milliseconds (D10, D12). */
+export const LEADERBOARD_DURATION_TOLERANCE_MS = 5000;
+/** How long a session join counts for session-level trust, in milliseconds (6 h, D10). */
+export const LEADERBOARD_SESSION_WINDOW_MS = 21600000;
+/** How long a submission id is remembered for exactly-once delivery, in milliseconds (7 days, D15). */
+export const LEADERBOARD_DEDUPE_TTL_MS = 604800000;
+/** Variant key of a board without dimensions (D16). */
+export const LEADERBOARD_ALL_VARIANT_KEY = "all";
+/** Most dimensions one board may declare. */
+export const LEADERBOARD_MAXIMUM_DIMENSIONS = 4;
+/** Most values one dimension may allow. */
+export const LEADERBOARD_MAXIMUM_DIMENSION_VALUES = 100;
+/** Longest dimension value. */
+export const LEADERBOARD_MAXIMUM_VALUE_LENGTH = 64;
+/** Longest display name. */
+export const LEADERBOARD_MAXIMUM_NAME_LENGTH = 24;
+/** Most entries one public read returns. */
+export const LEADERBOARD_MAXIMUM_PAGE_SIZE = 100;
+/** Default entries of a public read. */
+export const LEADERBOARD_DEFAULT_PAGE_SIZE = 10;
+/** Most entries above and below a player in an around-me read. */
+export const LEADERBOARD_MAXIMUM_AROUND_WINDOW = 10;
+/** Most targets in one my-entries read. */
+export const LEADERBOARD_MAXIMUM_TARGETS = 20;
+/** Per-process cache life of top-N reads, in milliseconds (D19). */
+export const LEADERBOARD_READ_CACHE_MS = 2000;
+/** Per-process cache life of board definitions and rules, in milliseconds (D19). */
+export const LEADERBOARD_DEFINITION_CACHE_MS = 2000;
+/** Lease name of the scheduler (D17). */
+export const LEADERBOARD_SCHEDULER_LEASE = "leaderboard-scheduler";
+/** Lease life of the scheduler, in milliseconds. */
+export const LEADERBOARD_SCHEDULER_LEASE_TTL_MS = 90000;
+/** Milliseconds between scheduler ticks. */
+export const LEADERBOARD_SCHEDULER_TICK_MS = 60000;
+/** Activity records kept (D21). */
+export const LEADERBOARD_ACTIVITY_KEEP = 5000;
+/** Redis key prefix of the rank store. */
+export const LEADERBOARD_REDIS_PREFIX = "bgs:lb:";
+/** Folder of the file rank store below admin.dataDir. */
+export const LEADERBOARD_DATA_FOLDER = "leaderboards";
+/** Milliseconds the file rank store waits before writing a changed file. */
+export const LEADERBOARD_FILE_FLUSH_DELAY_MS = 500;
+/** Admin store document id of the rules (collection "leaderboardSettings"). */
+export const LEADERBOARD_RULES_DOCUMENT_ID = "rules";
+/** Rules used until an admin saves others (D19). */
+export const DEFAULT_LEADERBOARD_RULES = {
+    submissionsPerMinutePerPlayer: 30,
+    submissionsPerMinutePerAddress: 60,
+    readsPerMinutePerAddress: 240,
+    identitiesPerHourPerAddress: 20,
+    maximumScoresPerSubmission: 10,
+    metadataMaximumBytes: 1024,
+    blockedWords: []
+};
+/** Milliseconds in one minute. */
+export const MILLISECONDS_PER_MINUTE = 60000;
+/** Milliseconds in one hour. */
+export const MILLISECONDS_PER_HOUR = 3600000;
+/** Board id pattern. */
+export const BOARD_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Dimension name pattern. */
+export const DIMENSION_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,31}$/;
+/** Submission id pattern. */
+export const SUBMISSION_ID_PATTERN = /^[A-Za-z0-9-]{8,64}$/;

package/lib/leaderboards/LeaderboardError.d.ts

@@ -0,0 +1,15 @@
+import type { LeaderboardRefusalReason } from "../admin/AdminApiTypes.js";
+/** A refused leaderboard request: the HTTP status, the machine reason and a sentence for people. */
+export declare class LeaderboardError extends Error {
+    /** HTTP status to answer with. */
+    readonly status: number;
+    /** The machine-readable reason. */
+    readonly reason: LeaderboardRefusalReason;
+    /**
+     * Creates the error.
+     * @param status HTTP status (400, 401, 403, 404, 409 or 429).
+     * @param reason The machine-readable reason.
+     * @param message A sentence for people.
+     */
+    constructor(status: number, reason: LeaderboardRefusalReason, message: string);
+}

package/lib/leaderboards/LeaderboardError.js

@@ -0,0 +1,20 @@
+// A refused leaderboard request (game-server-leaderboards DR §5): the HTTP status, the machine reason and a sentence.
+/** A refused leaderboard request: the HTTP status, the machine reason and a sentence for people. */
+export class LeaderboardError extends Error {
+    /** HTTP status to answer with. */
+    status;
+    /** The machine-readable reason. */
+    reason;
+    /**
+     * Creates the error.
+     * @param status HTTP status (400, 401, 403, 404, 409 or 429).
+     * @param reason The machine-readable reason.
+     * @param message A sentence for people.
+     */
+    constructor(status, reason, message) {
+        super(message);
+        this.name = "LeaderboardError";
+        this.status = status;
+        this.reason = reason;
+    }
+}

package/lib/leaderboards/LeaderboardIdentity.d.ts

@@ -0,0 +1,44 @@
+import type { LeaderboardPlayerRecord } from "./LeaderboardRankStore.js";
+/** Prefix of an anonymous player id. */
+export declare const ANONYMOUS_PLAYER_PREFIX: string;
+/** The prefix of an auth user's player id (D8). */
+export declare const USER_PLAYER_PREFIX: string;
+/** Prefix of a console-added player id (D8). */
+export declare const MANUAL_PLAYER_PREFIX: string;
+/**
+ * Creates an anonymous identity: a new player id, its one-time key and the hash the server keeps.
+ * @returns The player id, the key to hand out once, and the sha256 hex of its secret.
+ */
+export declare function createAnonymousKey(): {
+    playerId: string;
+    playerKey: string;
+    keyHash: string;
+};
+/**
+ * Splits a player key on its last ".".
+ * @param playerKey The key a client sent.
+ * @returns The player id and secret, or null when the key has no "." or an empty part.
+ */
+export declare function parsePlayerKey(playerKey: string): {
+    playerId: string;
+    secret: string;
+} | null;
+/**
+ * Whether a secret matches a player's stored hash (constant-time comparison).
+ * @param record The player.
+ * @param secret The secret from the key.
+ * @returns True when the player has a key hash and the secret hashes to it.
+ */
+export declare function isPlayerKeyValid(record: LeaderboardPlayerRecord, secret: string): boolean;
+/**
+ * The player id of an auth user.
+ * @param userId The auth user id.
+ * @returns `user:<userId>`.
+ */
+export declare function userPlayerId(userId: string): string;
+/**
+ * The name a player gets until they choose one.
+ * @param playerId The player id.
+ * @returns "Player " and the id's last four characters in upper case.
+ */
+export declare function defaultDisplayName(playerId: string): string;

package/lib/leaderboards/LeaderboardIdentity.js

@@ -0,0 +1,72 @@
+// Leaderboard player identity (game-server-leaderboards D8): anonymous keys `<playerId>.<secret>` whose secret is kept
+// only as a sha256 hash, auth-user ids, manual ids and default names. General purpose (D2).
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+/** Prefix of an anonymous player id. */
+export const ANONYMOUS_PLAYER_PREFIX = "anon-";
+/** The prefix of an auth user's player id (D8). */
+export const USER_PLAYER_PREFIX = "user:";
+/** Random bytes in an anonymous key's secret. */
+const SECRET_BYTE_LENGTH = 32;
+/** Separator between the player id and the secret in a key. */
+const KEY_SEPARATOR = ".";
+/** Characters of the player id shown in a default name. */
+const DEFAULT_NAME_SUFFIX_LENGTH = 4;
+/** Prefix of a console-added player id (D8). */
+export const MANUAL_PLAYER_PREFIX = "manual-";
+/**
+ * Creates an anonymous identity: a new player id, its one-time key and the hash the server keeps.
+ * @returns The player id, the key to hand out once, and the sha256 hex of its secret.
+ */
+export function createAnonymousKey() {
+    const playerId = ANONYMOUS_PLAYER_PREFIX + randomUUID();
+    const secret = randomBytes(SECRET_BYTE_LENGTH).toString("base64url");
+    return { playerId: playerId, playerKey: playerId + KEY_SEPARATOR + secret, keyHash: hashSecret(secret) };
+}
+/**
+ * Splits a player key on its last ".".
+ * @param playerKey The key a client sent.
+ * @returns The player id and secret, or null when the key has no "." or an empty part.
+ */
+export function parsePlayerKey(playerKey) {
+    const separatorIndex = playerKey.lastIndexOf(KEY_SEPARATOR);
+    if (separatorIndex <= 0 || separatorIndex === playerKey.length - 1)
+        return null;
+    return { playerId: playerKey.slice(0, separatorIndex), secret: playerKey.slice(separatorIndex + 1) };
+}
+/**
+ * Whether a secret matches a player's stored hash (constant-time comparison).
+ * @param record The player.
+ * @param secret The secret from the key.
+ * @returns True when the player has a key hash and the secret hashes to it.
+ */
+export function isPlayerKeyValid(record, secret) {
+    if (record.keyHash == null)
+        return false;
+    const expected = Buffer.from(record.keyHash, "hex");
+    const actual = Buffer.from(hashSecret(secret), "hex");
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+/**
+ * The player id of an auth user.
+ * @param userId The auth user id.
+ * @returns `user:<userId>`.
+ */
+export function userPlayerId(userId) {
+    return USER_PLAYER_PREFIX + userId;
+}
+/**
+ * The name a player gets until they choose one.
+ * @param playerId The player id.
+ * @returns "Player " and the id's last four characters in upper case.
+ */
+export function defaultDisplayName(playerId) {
+    return "Player " + playerId.slice(-DEFAULT_NAME_SUFFIX_LENGTH).toUpperCase();
+}
+/**
+ * The sha256 hex of a key secret.
+ * @param secret The secret.
+ * @returns The hash.
+ */
+function hashSecret(secret) {
+    return createHash("sha256").update(secret).digest("hex");
+}

package/lib/leaderboards/LeaderboardPublicApi.d.ts

@@ -0,0 +1,17 @@
+import { type Endpoint } from "colyseus";
+import type { GameServerStateValues } from "../GameServerState.js";
+import type { LeaderboardService } from "./LeaderboardService.js";
+/**
+ * The public leaderboard endpoint for createRouter.
+ * @param service The leaderboard service.
+ * @param state The server state (config, verifier, bans, metrics).
+ * @returns The endpoint, keyed by name.
+ */
+export declare function createLeaderboardRoutes(service: LeaderboardService, state: GameServerStateValues): Record<string, Endpoint>;
+/**
+ * Reads a POST body as a JSON object, at most LEADERBOARD_MAX_BODY_BYTES.
+ * @param request The Fetch request.
+ * @returns The object ({} for an empty body).
+ * @throws LeaderboardError 400 invalidRequest when too large, not JSON or not an object.
+ */
+export declare function readJsonBody(request: Request): Promise<Record<string, unknown>>;