@zaisma/game-server 0.0.1 → 1.0.0

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`;
+}