@zaisma/game-server 0.0.1 → 1.1.0

package/src/requests.js

@@ -0,0 +1,127 @@
+/**
+ * Requests: plain calls from a game to its game server's onRequest, outside any room, for a
+ * leaderboard, a shop or a daily reward in any game, single-player ones too. Zaisma rooms answer them
+ * at rooms.zaisma.com (apps/rooms/src/game-server.ts) and the Node runner on the developer's own
+ * server (@zaisma/game-server/node), both at POST /v1/requests/<game>, both checked here so a request that works
+ * in one works the same in the other.
+ *
+ * The game sends { pass, request } as text/plain JSON (so the browser needs no preflight): its player
+ * pass, so onRequest knows who's asking, and its request, plain JSON. It gets back { answer }, what
+ * onRequest answered, or { error: { code, message } }.
+ */
+export const REQUEST_LIMITS = {
+    /** A request, as JSON. */
+    maximumRequestSizeBytes: 16 * 1024,
+    /**
+     * The player pass that comes with it, or with a room's hello: the fullest pass Zaisma makes (1,000 owned
+     * items with 40-character names, 200 friends and 100 blocks) is about 70 KB, with room to spare.
+     */
+    maximumPassSizeBytes: 96 * 1024,
+    /** What onRequest answers, as JSON. */
+    maximumAnswerSizeBytes: 1024 * 1024,
+    /** How long onRequest may take, awaiting the database included, before the request fails. */
+    answerTimeoutSec: 10,
+};
+export const REQUEST_ERROR_TEXT = {
+    bad_request: "Requests are JSON with the player's pass and the game's request: { pass, request }.",
+    too_big: `Requests are up to ${REQUEST_LIMITS.maximumRequestSizeBytes / 1024} KB.`,
+    bad_pass: "Your player pass isn't valid for this game.",
+    account_needed: "Playing online needs a Zaisma account. Sign in on the game's page to play.",
+    game_not_open_to_player: "This game isn't open to this account.",
+    game_unavailable: "This game isn't available right now.",
+    no_request_handler: "This game's server doesn't take requests.",
+    game_server_error: "The game's server couldn't answer this request.",
+    hosting_paused: "This game's hosting is paused. It starts again when the month resets or its developer adds credit.",
+    slow_down: "Too many requests. Try again in a minute.",
+    bad_origin: "Not allowed from here.",
+    busy: "Zaisma is busy. Try again soon.",
+};
+/** The HTTP status each request error answers with. */
+export const REQUEST_ERROR_HTTP_STATUS = {
+    bad_request: 400,
+    too_big: 413,
+    bad_pass: 401,
+    account_needed: 403,
+    game_not_open_to_player: 403,
+    game_unavailable: 404,
+    no_request_handler: 404,
+    game_server_error: 500,
+    hosting_paused: 403,
+    slow_down: 429,
+    bad_origin: 403,
+    busy: 503,
+};
+/** The body of an error answer. message replaces the usual text. */
+export function requestError(code, message) {
+    return { error: { code, message: message || REQUEST_ERROR_TEXT[code] } };
+}
+/**
+ * Read what a game sent: its pass and its request, plain JSON within REQUEST_LIMITS.maximumRequestSizeBytes
+ * (nothing is null). The pass's own size doesn't count.
+ */
+export function readRequestBody(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return { code: "bad_request" };
+    }
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return { code: "bad_request" };
+    const { pass, request } = body;
+    if (typeof pass !== "string" || pass.length > REQUEST_LIMITS.maximumPassSizeBytes)
+        return { code: "bad_request" };
+    const requestText = request === undefined ? "null" : JSON.stringify(request);
+    if (new TextEncoder().encode(requestText).length > REQUEST_LIMITS.maximumRequestSizeBytes)
+        return { code: "too_big" };
+    return { pass, request: request === undefined ? null : request };
+}
+/**
+ * What onRequest answered, as the game gets it: plain JSON (nothing is null), within
+ * REQUEST_LIMITS.maximumAnswerSizeBytes, or a mistake for the game server's errors.
+ */
+export function readRequestAnswer(answer) {
+    if (answer === undefined || answer === null)
+        return { answer: null };
+    let text;
+    try {
+        text = JSON.stringify(answer);
+    }
+    catch {
+        text = undefined;
+    }
+    if (text === undefined)
+        return { mistake: "onRequest answered something that isn't plain JSON, like a function or an object that refers to itself. Answer numbers, text, true or false, null, lists and plain objects." };
+    if (new TextEncoder().encode(text).length > REQUEST_LIMITS.maximumAnswerSizeBytes) {
+        return { mistake: `onRequest answered over ${REQUEST_LIMITS.maximumAnswerSizeBytes / 1024 / 1024} MB. Answer less, like one page of a leaderboard at a time.` };
+    }
+    return { answer: JSON.parse(text) };
+}
+/**
+ * Run a game server's onRequest for one request, with a time limit, and say what the game gets. A
+ * game server without onRequest answers no_request_handler. When it throws, answers something that
+ * isn't plain JSON or takes too long, the game gets game_server_error, and failure says why for the
+ * game server's errors.
+ */
+export async function answerRequest(handler, player, request, server) {
+    if (typeof handler.onRequest !== "function")
+        return { code: "no_request_handler" };
+    let timer;
+    try {
+        const answer = await Promise.race([
+            Promise.resolve().then(() => handler.onRequest(player, request, server)),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`onRequest didn't answer within ${REQUEST_LIMITS.answerTimeoutSec} seconds`)), REQUEST_LIMITS.answerTimeoutSec * 1000);
+            }),
+        ]);
+        const read = readRequestAnswer(answer);
+        return "mistake" in read ? { code: "game_server_error", failure: read.mistake } : read;
+    }
+    catch (error) {
+        return { code: "game_server_error", failure: String((error instanceof Error && error.stack) || error) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/src/room-calls.d.ts

@@ -0,0 +1,92 @@
+/** The room limits the checks read; ROOM_LIMITS has all of them. */
+export interface RoomCallLimits {
+    maximumKickMessageCharacterCount: number;
+    maximumLatestKeyCharacterCount: number;
+    maximumSetupDataSizeBytes: number;
+    maximumJoinDataSizeBytes: number;
+    maximumNameCharacterCount: number;
+    maximumLabelNameCharacterCount: number;
+    maximumLabelValueCharacterCount: number;
+    maximumLabelCount: number;
+}
+/** The error a mistake in a room call throws: GameServerError, or the sandbox's copy of it. */
+export type RoomCallErrorClass = new (code: "bad_room_call" | "room_call_unavailable", field: string, message: string, fix: string) => Error;
+/** A send's delivery as the room acts on it: latest-only, with its latestKey, or reliable. */
+export type CheckedDelivery = {
+    isLatestOnly: false;
+} | {
+    isLatestOnly: true;
+    latestKey: string;
+};
+export interface CheckedSend {
+    delivery: CheckedDelivery;
+    fromPlayerId: string | null;
+}
+export interface CheckedBroadcast extends CheckedSend {
+    audience: "everyone" | "players" | "spectators";
+    exceptPlayerId: string | undefined;
+}
+export interface CheckedReserve {
+    playerIds: string[];
+    setupData: unknown;
+    isListed: boolean;
+    friendJoinsEnabled: boolean;
+    isKept: boolean;
+    name: string | null;
+    labels: Record<string, string>;
+}
+export interface CheckedMove {
+    playerIds: string[];
+    joinData: unknown;
+}
+export interface RoomCallChecks {
+    checkBroadcast(message: unknown, broadcastOptions: unknown): CheckedBroadcast;
+    checkSend(playerId: unknown, message: unknown, sendOptions: unknown): CheckedSend & {
+        playerId: string;
+    };
+    checkBroadcastBytes(bytes: unknown, broadcastOptions: unknown): CheckedBroadcast & {
+        bytes: Uint8Array;
+    };
+    checkSendBytes(playerId: unknown, bytes: unknown, sendOptions: unknown): CheckedSend & {
+        playerId: string;
+        bytes: Uint8Array;
+    };
+    checkKick(playerId: unknown, kickOptions: unknown): {
+        playerId: string;
+        message: string;
+        isKeptOut: boolean;
+    };
+    checkReserve(reserveOptions: unknown, playerIdsInRoom: readonly string[]): CheckedReserve;
+    checkMoveTo(toRoomCode: unknown, moveOptions: unknown, playerIdsInRoom: readonly string[]): CheckedMove & {
+        toRoomCode: string;
+    };
+    checkSetInfo(nameAndLabels: unknown): {
+        name?: string | null;
+        labels?: Record<string, string>;
+    };
+    checkEnd(message: unknown): string | undefined;
+    /** Text with hidden characters dropped, spaces collapsed, cut to the length. */
+    tidy(given: unknown, maximumCharacterCount: number): string;
+    /** A name and labels within the limits, with hidden characters dropped. Fields left out stay out. */
+    tidyRoomInfo(nameAndLabels: {
+        name?: unknown;
+        labels?: unknown;
+    }): {
+        name?: string | null;
+        labels?: Record<string, string>;
+    };
+    /** Plain JSON within maximumSizeBytes, copied, or isValid false. Nothing (undefined or null) is null. */
+    checkRoomData(given: unknown, maximumSizeBytes: number): {
+        isValid: true;
+        checkedData: unknown;
+    } | {
+        isValid: false;
+    };
+}
+/** The checks for a runtime: pass its GameServerError class and the room limits. */
+export declare function roomCallChecks(ErrorClass: RoomCallErrorClass, limits: RoomCallLimits): RoomCallChecks;
+/**
+ * The same parts as an ES module's source, for the game server's sandbox: export default is { checksFor }.
+ * A bundler that names functions (esbuild's keepNames) calls __name inside them, so the module gives it.
+ */
+export declare function roomCallChecksModuleSource(): string;

package/src/room-calls.js

@@ -0,0 +1,194 @@
+// What a game's room calls (room.broadcast, room.kick, room.reserve …) are checked for. Zaisma's rooms run a
+// game server in a sandbox, where a call only records what the game asked; the same checks run there, at the
+// call, so a mistake throws in the game's own handler and its developer sees it in the game's logs, exactly
+// as on their own server, where the room checks the call itself.
+/** The parts, as one function with nothing from outside it, so its source runs the same in the sandbox. */
+function roomCallChecksParts() {
+    // Characters that hide text or flip its direction.
+    const HIDDEN = /[\u0000-\u001f\u007f-\u009f­​-‏‪-‮⁠-⁤⁦-⁩]/g;
+    const ROOM_CODE = /^[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{6}$/;
+    const BROADCAST_FIELDS = ["exceptPlayerId", "audience", "delivery", "latestKey", "fromPlayerId"];
+    const SEND_FIELDS = ["delivery", "latestKey", "fromPlayerId"];
+    function checksFor(ErrorClass, limits) {
+        const mistake = (call, message, fix) => new ErrorClass("bad_room_call", call, message, fix);
+        const tidy = (given, maximumCharacterCount) => String(given ?? "")
+            .normalize("NFKC")
+            .replace(HIDDEN, "")
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, maximumCharacterCount)
+            .trim();
+        /** A call's options with only the fields it takes: anything else throws, naming the ones it does. */
+        const closed = (given, fields, call) => {
+            if (given === undefined || given === null)
+                return {};
+            if (typeof given !== "object" || Array.isArray(given))
+                throw mistake(call, `${call}'s options must be an object.`, `Give { ${fields.join(", ")} } or leave them out.`);
+            for (const field of Object.keys(given)) {
+                if (!fields.includes(field))
+                    throw mistake(call, `${call} doesn't take ${field}.`, `It takes: ${fields.join(", ")}.`);
+            }
+            return given;
+        };
+        const readText = (given, name, call) => {
+            if (typeof given !== "string" || !given)
+                throw mistake(call, `${call}'s ${name} must be a player's ID, like player.id.`, `Give the ${name} as text.`);
+            return given;
+        };
+        /** A send's delivery and latestKey. latest_only needs its latestKey. */
+        const readDelivery = (given, call) => {
+            const { delivery, latestKey } = given;
+            if (delivery !== undefined && delivery !== "reliable" && delivery !== "latest_only")
+                throw mistake(call, `${call}'s delivery is ${JSON.stringify(delivery) ?? "not text"}.`, 'Give "reliable" (the default) or "latest_only".');
+            if (latestKey !== undefined && (typeof latestKey !== "string" || latestKey.length > limits.maximumLatestKeyCharacterCount)) {
+                throw mistake(call, `${call}'s latestKey must be text up to ${limits.maximumLatestKeyCharacterCount} characters.`, 'Give a short name for the slot this update replaces, like "positions".');
+            }
+            if (delivery !== "latest_only")
+                return { isLatestOnly: false };
+            if (latestKey === undefined)
+                throw mistake(call, `${call}'s delivery is "latest_only" with no latestKey.`, 'latest_only needs a latestKey: the slot this update replaces, like "position".');
+            return { isLatestOnly: true, latestKey: latestKey };
+        };
+        /** Who a send says it's from (SendOptions.fromPlayerId), or null for the game server. */
+        const readFromPlayerId = (given, call) => {
+            if (given.fromPlayerId === undefined)
+                return null;
+            if (typeof given.fromPlayerId !== "string" || !given.fromPlayerId)
+                throw mistake(call, `${call}'s fromPlayerId must be a player's ID, like player.id.`, "Give the ID of the player the message is from, or leave it out.");
+            return given.fromPlayerId;
+        };
+        const readAudience = (given, call) => {
+            const audience = given.audience;
+            if (audience === undefined || audience === "everyone")
+                return "everyone";
+            if (audience === "players" || audience === "spectators")
+                return audience;
+            throw mistake(call, `${call}'s audience is ${typeof audience === "string" ? JSON.stringify(audience.slice(0, 40)) : typeof audience}.`, 'Give "everyone", "players" or "spectators", or leave it out for everyone.');
+        };
+        const readExcept = (given, call) => {
+            if (given.exceptPlayerId === undefined)
+                return undefined;
+            return readText(given.exceptPlayerId, "exceptPlayerId", call);
+        };
+        /** Bytes a game handed the room, as a Uint8Array: anything else is a mistake in the game's call. */
+        const readBytes = (given, call) => {
+            if (given instanceof Uint8Array)
+                return given;
+            if (given instanceof ArrayBuffer)
+                return new Uint8Array(given);
+            if (ArrayBuffer.isView(given))
+                return new Uint8Array(given.buffer, given.byteOffset, given.byteLength);
+            throw mistake(call, `${call} takes bytes.`, "Give a Uint8Array, another typed array or an ArrayBuffer.");
+        };
+        const checkRoomData = (given, maximumSizeBytes) => {
+            if (given === undefined || given === null)
+                return { isValid: true, checkedData: null };
+            let text;
+            try {
+                text = JSON.stringify(given);
+            }
+            catch {
+                return { isValid: false };
+            }
+            if (text === undefined || new TextEncoder().encode(text).length > maximumSizeBytes)
+                return { isValid: false };
+            return { isValid: true, checkedData: JSON.parse(text) };
+        };
+        const tidyRoomInfo = (nameAndLabels) => {
+            const out = {};
+            if (nameAndLabels.name !== undefined)
+                out.name = nameAndLabels.name === null ? null : tidy(nameAndLabels.name, limits.maximumNameCharacterCount) || null;
+            if (nameAndLabels.labels !== undefined) {
+                const labels = {};
+                if (nameAndLabels.labels && typeof nameAndLabels.labels === "object") {
+                    for (const [labelName, labelValue] of Object.entries(nameAndLabels.labels)) {
+                        const key = tidy(labelName, limits.maximumLabelNameCharacterCount);
+                        const shown = typeof labelValue === "string" || typeof labelValue === "number" ? tidy(labelValue, limits.maximumLabelValueCharacterCount) : "";
+                        if (key && shown && Object.keys(labels).length < limits.maximumLabelCount)
+                            labels[key] = shown;
+                    }
+                }
+                out.labels = labels;
+            }
+            return out;
+        };
+        const checkBroadcast = (message, broadcastOptions) => {
+            const given = closed(broadcastOptions, BROADCAST_FIELDS, "room.broadcast");
+            return { audience: readAudience(given, "room.broadcast"), exceptPlayerId: readExcept(given, "room.broadcast"), delivery: readDelivery(given, "room.broadcast"), fromPlayerId: readFromPlayerId(given, "room.broadcast") };
+        };
+        const checkSend = (playerId, message, sendOptions) => {
+            const given = closed(sendOptions, SEND_FIELDS, "room.send");
+            return { playerId: readText(playerId, "playerId", "room.send"), delivery: readDelivery(given, "room.send"), fromPlayerId: readFromPlayerId(given, "room.send") };
+        };
+        const checkBroadcastBytes = (bytes, broadcastOptions) => {
+            const given = closed(broadcastOptions, BROADCAST_FIELDS, "room.broadcastBytes");
+            return {
+                bytes: readBytes(bytes, "room.broadcastBytes"),
+                audience: readAudience(given, "room.broadcastBytes"),
+                exceptPlayerId: readExcept(given, "room.broadcastBytes"),
+                delivery: readDelivery(given, "room.broadcastBytes"),
+                fromPlayerId: readFromPlayerId(given, "room.broadcastBytes"),
+            };
+        };
+        const checkSendBytes = (playerId, bytes, sendOptions) => {
+            const given = closed(sendOptions, SEND_FIELDS, "room.sendBytes");
+            return { playerId: readText(playerId, "playerId", "room.sendBytes"), bytes: readBytes(bytes, "room.sendBytes"), delivery: readDelivery(given, "room.sendBytes"), fromPlayerId: readFromPlayerId(given, "room.sendBytes") };
+        };
+        const checkKick = (playerId, kickOptions) => {
+            const given = closed(kickOptions, ["message", "keepOut"], "room.kick");
+            return { playerId: readText(playerId, "playerId", "room.kick"), message: tidy(given.message, limits.maximumKickMessageCharacterCount), isKeptOut: given.keepOut === true };
+        };
+        const checkReserve = (reserveOptions, playerIdsInRoom) => {
+            const given = closed(reserveOptions, ["playerIds", "setupData", "isListed", "friendJoinsEnabled", "isKept", "name", "labels"], "room.reserve");
+            const playerIds = [...new Set(Array.isArray(given.playerIds) ? given.playerIds : [])].filter((id) => typeof id === "string" && playerIdsInRoom.includes(id));
+            if (!playerIds.length)
+                throw mistake("room.reserve", "room.reserve needs playerIds of players who are in this room.", "Give playerIds from room.players.");
+            const checked = checkRoomData(given.setupData, limits.maximumSetupDataSizeBytes);
+            if (!checked.isValid)
+                throw mistake("room.reserve", `room.reserve's setupData isn't plain JSON up to ${limits.maximumSetupDataSizeBytes / 1024} KB.`, "Give numbers, text, true or false, null, lists and plain objects, and keep them small.");
+            const nameAndLabels = tidyRoomInfo({ name: given.name ?? null, labels: given.labels ?? {} });
+            return {
+                playerIds,
+                setupData: checked.checkedData,
+                isListed: given.isListed === true,
+                friendJoinsEnabled: given.friendJoinsEnabled !== false,
+                isKept: given.isKept === true,
+                name: nameAndLabels.name ?? null,
+                labels: nameAndLabels.labels ?? {},
+            };
+        };
+        const checkMoveTo = (toRoomCode, moveOptions, playerIdsInRoom) => {
+            if (typeof toRoomCode !== "string" || !ROOM_CODE.test(toRoomCode))
+                throw mistake("room.moveTo", "room.moveTo needs a room code.", "Give the code of a room of this game, like the one room.reserve answered.");
+            const given = closed(moveOptions, ["playerIds", "joinData"], "room.moveTo");
+            const playerIds = [...new Set(Array.isArray(given.playerIds) ? given.playerIds : [])].filter((id) => typeof id === "string" && playerIdsInRoom.includes(id));
+            if (!playerIds.length)
+                throw mistake("room.moveTo", "room.moveTo needs playerIds of players who are in this room.", "Give playerIds from room.players.");
+            const checked = checkRoomData(given.joinData, limits.maximumJoinDataSizeBytes);
+            if (!checked.isValid)
+                throw mistake("room.moveTo", `room.moveTo's joinData isn't plain JSON up to ${limits.maximumJoinDataSizeBytes / 1024} KB.`, "Give numbers, text, true or false, null, lists and plain objects, and keep them small.");
+            return { toRoomCode, playerIds, joinData: checked.checkedData };
+        };
+        const checkSetInfo = (nameAndLabels) => tidyRoomInfo(closed(nameAndLabels, ["name", "labels"], "room.setInfo"));
+        const checkEnd = (message) => {
+            if (message === undefined || message === null)
+                return undefined;
+            if (typeof message !== "string")
+                throw mistake("room.end", "room.end's message must be text.", "Give the text players see, or leave it out.");
+            return message.slice(0, limits.maximumKickMessageCharacterCount);
+        };
+        return { checkBroadcast, checkSend, checkBroadcastBytes, checkSendBytes, checkKick, checkReserve, checkMoveTo, checkSetInfo, checkEnd, tidy, tidyRoomInfo, checkRoomData };
+    }
+    return { checksFor };
+}
+/** The checks for a runtime: pass its GameServerError class and the room limits. */
+export function roomCallChecks(ErrorClass, limits) {
+    return roomCallChecksParts().checksFor(ErrorClass, limits);
+}
+/**
+ * The same parts as an ES module's source, for the game server's sandbox: export default is { checksFor }.
+ * A bundler that names functions (esbuild's keepNames) calls __name inside them, so the module gives it.
+ */
+export function roomCallChecksModuleSource() {
+    return `var __name = (target) => target;\nexport default (${roomCallChecksParts.toString()})();\n`;
+}