@zaisma/game-server 1.22.0 → 1.24.0

package/src/doors.js

@@ -0,0 +1,281 @@
+/**
+ * Door contracts (docs/DOORS.md). Every way into Zaisma, of every kind, states who may call it, what it may
+ * reach and what it trusts from other doors, and goes through checkDoor before its own code runs. Here, in the
+ * game server package's internal part, so a room on a developer's own server goes through the same check;
+ * never in the package's published index.
+ */
+const shapeOf = (schema) => schema;
+export const text = (maximumCharacterCount, pattern) => shapeOf({ type: "string", maxLength: maximumCharacterCount, ...(pattern ? { pattern } : {}) });
+export const oneOfWords = (...words) => shapeOf({ type: "string", maxLength: Math.max(...words.map((word) => word.length)), enum: words });
+export const integer = (minimumNumber = 0, maximumNumber = Number.MAX_SAFE_INTEGER) => shapeOf({ type: "integer", minimum: minimumNumber, maximum: maximumNumber });
+export const realNumber = (minimumNumber, maximumNumber) => shapeOf({ type: "number", minimum: minimumNumber, maximum: maximumNumber });
+export const yesOrNo = shapeOf({ type: "boolean" });
+export const anyOf = (...shapes) => shapeOf({ anyOf: shapes });
+export const orNothing = (shape) => anyOf(shape, shapeOf({ type: "null" }));
+export const listOf = (items, maximumItemCount, minimumItemCount = 0) => shapeOf({ type: "array", items, maxItems: maximumItemCount, ...(minimumItemCount ? { minItems: minimumItemCount } : {}) });
+/** A closed object: these fields and no others, the required ones named. */
+export const fieldsOf = (properties, required = []) => shapeOf({ type: "object", properties, required, additionalProperties: false });
+/** A game's own data, of any shape: its size only, in characters of its JSON. */
+export const gameData = (maximumSizeBytes) => shapeOf({ isGameData: true, maximumSizeBytes });
+/** Nothing: a door with no query it reads and no body. */
+export const TAKES_NOTHING = { query: {}, body: null };
+export const ANSWERS_PAGE = { kind: "page" };
+export const ANSWERS_EMPTY = { kind: "empty" };
+export const ANSWERS_REDIRECT = { kind: "redirect" };
+export const ANSWERS_FILE = { kind: "file" };
+export const ANSWERS_BYTES = { kind: "bytes" };
+export const answersJson = (schema) => ({ kind: "json", schema });
+/** A door's limit in calls a minute, from this short list. Each is a rate limit binding in the Workers that use it: LIMIT_<LEVEL>. */
+export const DOOR_LIMIT_LEVELS = { very_rare: 2, guess: 5, rare: 10, steady: 30, busy: 120, building: 1000 };
+/** Why a door has no limit of its own: from this list only, and the daily review reads every door that gives one. */
+export const DOOR_NO_LIMIT_REASONS = {
+    answers_from_memory: "It answers fixed bytes from memory and reads nothing.",
+    cached_file: "It serves a file Cloudflare caches, with no database behind it and no egress fee.",
+    admin_only: "Cloudflare Access stands in front of it, and only Zaisma's own people get through.",
+    signed_by_sender: "It reads nothing until the sender's signature on the body checks out.",
+    counted_by_its_call: "All it does is make calls that have their own limit.",
+    room_token_bucket: "A room's message bucket takes a token for each message, per player, before any door runs.",
+};
+/** Whether a call goes past a level's limit: door's own counter, for one subject. Keys never leave Cloudflare's counter. */
+export async function isPastLevel(env, level, counterName, subject) {
+    const binding = env[`LIMIT_${level.toUpperCase()}`];
+    if (!binding)
+        return false;
+    const answer = await binding.limit({ key: `${counterName}:${subject}` });
+    return !("success" in answer && answer.success === true);
+}
+/** Whether a call goes past a door's limit. doorName names its counter unless its limit shares a group. */
+export async function isPastDoorLimit(env, limit, doorName, subject) {
+    return "whyNoLimit" in limit ? false : isPastLevel(env, limit.level, limit.group ?? doorName, subject);
+}
+/** A pattern once compiled: shapes check on every call. */
+const compiledPatterns = new Map();
+function compiled(pattern) {
+    let found = compiledPatterns.get(pattern);
+    if (!found)
+        compiledPatterns.set(pattern, (found = new RegExp(pattern)));
+    return found;
+}
+const typesOf = (schema) => {
+    const { type } = schema;
+    if (Array.isArray(type))
+        return type;
+    if (typeof type === "string")
+        return [type];
+    if (Array.isArray(schema.enum))
+        return [...new Set(schema.enum.map((allowed) => (allowed === null ? "null" : typeof allowed)))];
+    return [];
+};
+/** Where a value doesn't match its shape or schema, as "path: problem" lines; [] when it fits. Answers and inputs both come here. */
+export function schemaProblems(schema, given, path = "answer") {
+    // anyOf: it fits when one of them fits; otherwise say how it misses the nearest.
+    if (Array.isArray(schema.anyOf)) {
+        const misses = schema.anyOf.map((option) => schemaProblems(option, given, path));
+        return misses.some((problems) => problems.length === 0) ? [] : misses.sort((first, second) => first.length - second.length)[0];
+    }
+    if (schema.isGameData === true) {
+        const sizeBytes = JSON.stringify(given)?.length ?? 0;
+        return sizeBytes > schema.maximumSizeBytes ? [`${path}: over ${schema.maximumSizeBytes} bytes`] : [];
+    }
+    const out = [];
+    const types = typesOf(schema);
+    const actual = given === null ? "null" : Array.isArray(given) ? "array" : Number.isInteger(given) ? "integer" : typeof given;
+    const fits = types.length === 0 || types.includes(actual) || (actual === "integer" && types.includes("number"));
+    if (!fits)
+        return [`${path}: is ${actual}, expected ${types.join(" or ")}`];
+    if (Array.isArray(schema.enum) && !schema.enum.includes(given))
+        out.push(`${path}: ${JSON.stringify(given)} isn't one of ${JSON.stringify(schema.enum)}`);
+    if (typeof given === "string") {
+        if (typeof schema.maxLength === "number" && given.length > schema.maxLength)
+            out.push(`${path}: over ${schema.maxLength} characters`);
+        if (schema.format === "date-time" && !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(given))
+            out.push(`${path}: ${given} isn't an ISO time in UTC`);
+        if (schema.format === "date" && !/^\d{4}-\d{2}-\d{2}$/.test(given))
+            out.push(`${path}: ${given} isn't YYYY-MM-DD`);
+        if (schema.format === "uri" && !/^https?:\/\//.test(given))
+            out.push(`${path}: ${given} isn't a link`);
+        if (typeof schema.pattern === "string" && !compiled(schema.pattern).test(given))
+            out.push(`${path}: ${given} doesn't match ${schema.pattern}`);
+    }
+    if (typeof given === "number") {
+        if (typeof schema.minimum === "number" && given < schema.minimum)
+            out.push(`${path}: below ${schema.minimum}`);
+        if (typeof schema.maximum === "number" && given > schema.maximum)
+            out.push(`${path}: above ${schema.maximum}`);
+    }
+    if (Array.isArray(given)) {
+        if (typeof schema.maxItems === "number" && given.length > schema.maxItems)
+            return [...out, `${path}: over ${schema.maxItems} items`];
+        if (typeof schema.minItems === "number" && given.length < schema.minItems)
+            out.push(`${path}: under ${schema.minItems} items`);
+        if (schema.items)
+            given.forEach((entry, index) => out.push(...schemaProblems(schema.items, entry, `${path}[${index}]`)));
+    }
+    if (actual === "object" && schema.properties) {
+        const properties = schema.properties;
+        const fields = given;
+        for (const name of schema.required ?? [])
+            if (!(name in fields))
+                out.push(`${path}.${name}: missing`);
+        if (schema.additionalProperties === false)
+            for (const name of Object.keys(fields))
+                if (!(name in properties))
+                    out.push(`${path}.${name}: not in the schema`);
+        for (const [name, property] of Object.entries(properties))
+            if (name in fields)
+                out.push(...schemaProblems(property, fields[name], `${path}.${name}`));
+    }
+    return out;
+}
+/** Where a value's types don't match a schema; null reads as left out, and what a call behind it allows, names included, stays the call's to say, with its own fix. */
+export function typeProblems(schema, given, path = "answer") {
+    if (given === null)
+        return [];
+    if (Array.isArray(schema.anyOf)) {
+        const misses = schema.anyOf.map((option) => typeProblems(option, given, path));
+        return misses.some((problems) => problems.length === 0) ? [] : misses.sort((first, second) => first.length - second.length)[0];
+    }
+    const types = typesOf(schema);
+    const actual = Array.isArray(given) ? "array" : Number.isInteger(given) ? "integer" : typeof given;
+    if (types.length && !types.includes(actual) && !(actual === "integer" && types.includes("number")))
+        return [`${path}: is ${actual}, expected ${types.join(" or ")}`];
+    if (actual !== "object" || !schema.properties)
+        return [];
+    const properties = schema.properties;
+    return Object.entries(given).flatMap(([name, fieldValue]) => (properties[name] ? typeProblems(properties[name], fieldValue, `${path}.${name}`) : []));
+}
+/**
+ * An answer with every field its schema didn't declare taken out, and the paths it took (a list's index as []): the
+ * caller still gets the answer. Nothing else changes, and an answer with nothing to cut comes back as the same value.
+ * Only closed objects cut, so a game's own rows and arguments pass as they are.
+ */
+export function cutUndeclared(schema, given, path = "answer") {
+    if (Array.isArray(schema.anyOf)) {
+        const options = schema.anyOf;
+        // The option that fits as it is. Or else: an option of the answer's type, one that fits once cut, then the one that takes least,
+        // so an answer short of one field isn't emptied to look like a shorter option.
+        if (options.some((option) => schemaProblems(option, given, path).length === 0))
+            return { kept: given, cutPaths: [] };
+        const tried = options.map((option) => {
+            const cut = cutUndeclared(option, given, path);
+            return { cut, isOtherType: schemaProblems({ type: typesOf(option) }, given, path).length > 0, problemCount: schemaProblems(option, cut.kept, path).length };
+        });
+        tried.sort((first, second) => Number(first.isOtherType) - Number(second.isOtherType) || Number(first.problemCount > 0) - Number(second.problemCount > 0) || first.cut.cutPaths.length - second.cut.cutPaths.length || first.problemCount - second.problemCount);
+        return tried[0]?.cut ?? { kept: given, cutPaths: [] };
+    }
+    if (Array.isArray(given)) {
+        if (!schema.items)
+            return { kept: given, cutPaths: [] };
+        const cutPaths = [];
+        let changed = null;
+        given.forEach((entry, index) => {
+            const cut = cutUndeclared(schema.items, entry, `${path}[]`);
+            if (!cut.cutPaths.length)
+                return;
+            cutPaths.push(...cut.cutPaths);
+            (changed ??= [...given])[index] = cut.kept;
+        });
+        return { kept: changed ?? given, cutPaths: [...new Set(cutPaths)] };
+    }
+    if (given === null || typeof given !== "object" || !schema.properties)
+        return { kept: given, cutPaths: [] };
+    const properties = schema.properties;
+    const kept = {};
+    const cutPaths = [];
+    for (const [name, fieldValue] of Object.entries(given)) {
+        const property = properties[name];
+        if (!property) {
+            if (schema.additionalProperties === false)
+                cutPaths.push(`${path}.${name}`);
+            else
+                kept[name] = fieldValue;
+            continue;
+        }
+        const cut = cutUndeclared(property, fieldValue, `${path}.${name}`);
+        kept[name] = cut.kept;
+        cutPaths.push(...cut.cutPaths);
+    }
+    return cutPaths.length ? { kept, cutPaths } : { kept: given, cutPaths: [] };
+}
+/** A query value read as its shape says: a number or a yes or no comes as text. Text that can't be one stays text, so the shape refuses it. */
+function queryValueOf(shape, given) {
+    if (Array.isArray(shape.anyOf)) {
+        for (const option of shape.anyOf) {
+            const read = queryValueOf(option, given);
+            if (schemaProblems(option, read).length === 0)
+                return read;
+        }
+        return given;
+    }
+    if ((shape.type === "integer" || shape.type === "number") && given.trim() !== "" && Number.isFinite(Number(given)))
+        return Number(given);
+    if (shape.type === "boolean" && (given === "true" || given === "false"))
+        return given === "true";
+    return given;
+}
+/** The first problem with a query, as [name, what's wrong], or null. isOpenToOtherNames: a page ignores names it doesn't read, since share links pick some up. */
+export function queryProblem(fields, query, isOpenToOtherNames = false) {
+    for (const [name, given] of query) {
+        const shape = fields[name];
+        if (!shape) {
+            if (isOpenToOtherNames)
+                continue;
+            return { field: name, problem: `${name} isn't one of the query's names` };
+        }
+        const [problem] = schemaProblems(shape, queryValueOf(shape, given), name);
+        if (problem)
+            return { field: name, problem };
+    }
+    return null;
+}
+/** The first problem with a JSON body's fields: closed, each field its shape, the required ones there. */
+export function bodyProblem(fields, required, body) {
+    for (const name of required)
+        if (!(name in body))
+            return { field: name, problem: `${name} is missing` };
+    for (const [name, given] of Object.entries(body)) {
+        const shape = fields[name];
+        if (!shape)
+            return { field: name, problem: `${name} isn't one of this door's fields` };
+        const [problem] = schemaProblems(shape, given, name);
+        if (problem)
+            return { field: name, problem };
+    }
+    return null;
+}
+/** The first problem with a form's fields: its names closed, each value text, or a list where it may repeat. A form's text boxes send what they send, so its numbers are the door's to read. */
+export function formProblem(fields, fileNames, form) {
+    for (const name of new Set(form.keys())) {
+        if (fileNames.includes(name))
+            continue;
+        const shape = fields[name];
+        if (!shape)
+            return { field: name, problem: `${name} isn't one of this form's fields` };
+        const sent = form.getAll(name);
+        if (sent.some((fieldValue) => typeof fieldValue !== "string"))
+            return { field: name, problem: `${name} is a file, not text` };
+        const read = shape.type === "array" || sent.length !== 1 ? sent : sent[0];
+        const [problem] = schemaProblems(shape, typeof read === "string" ? queryValueOf(shape, read) : read, name);
+        if (problem)
+            return { field: name, problem };
+    }
+    return null;
+}
+/**
+ * The one check every door goes through. `proven` is who the door's guard found the caller to be; a caller a
+ * named function proves passes here, and that function refuses them, before anything else of the door runs.
+ */
+export function checkDoor(contract, proven) {
+    return contract.whoMayCall === "anyone" || "provenBy" in contract || proven.includes(contract.whoMayCall);
+}
+/** Where a door's path parts come from: `:name` parts, each a [^/]+ unless named here, and a final `*` for the rest. */
+export function doorPathPattern(path, partPatterns = {}) {
+    const parts = path.split("/").map((part) => {
+        if (part === "*")
+            return ".*";
+        if (part.startsWith(":"))
+            return `(?<${part.slice(1)}>${partPatterns[part.slice(1)] ?? "[^/]+"})`;
+        return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    });
+    return new RegExp(`^${parts.join("/")}$`);
+}

package/src/internal.d.ts

@@ -12,3 +12,4 @@ export * from "./pass.ts";
 export * from "./names.ts";
 export * from "./chat.ts";
 export * from "./relay.ts";
+export * from "./doors.ts";

package/src/internal.js

@@ -14,3 +14,4 @@ export * from "./pass.js";
 export * from "./names.js";
 export * from "./chat.js";
 export * from "./relay.js";
+export * from "./doors.js";

package/src/requests.d.ts

@@ -67,7 +67,7 @@ export declare const REQUEST_LIMITS: {
     /** How long onRequest may take, awaiting the database included, before the request fails. */
     readonly answerTimeoutSec: 10;
 };
-export type RequestErrorCode = "bad_request" | "too_big" | "bad_pass" | "bad_player_token" | "account_needed" | "game_not_open_to_player" | "game_unavailable" | "no_request_handler" | "game_server_error" | "hosting_paused" | "slow_down" | "bad_origin" | "busy";
+export type RequestErrorCode = "bad_request" | "too_big" | "bad_pass" | "bad_player_token" | "account_needed" | "game_not_open_to_player" | "game_unavailable" | "no_request_handler" | "game_server_error" | "hosting_paused" | "rented_share_used" | "slow_down" | "bad_origin" | "busy";
 export declare const REQUEST_ERROR_TEXT: Record<RequestErrorCode, string>;
 /** The HTTP status each request error answers with. */
 export declare const REQUEST_ERROR_HTTP_STATUS: Record<RequestErrorCode, number>;

package/src/requests.js

@@ -35,6 +35,7 @@ export const REQUEST_ERROR_TEXT = {
     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.",
+    rented_share_used: "This network looks like a server. Turn off your VPN or sign in with an account that has played before.",
     slow_down: "Too many requests. Try again in a minute.",
     bad_origin: "Not allowed from here.",
     busy: "Zaisma is busy. Try again soon.",
@@ -51,6 +52,7 @@ export const REQUEST_ERROR_HTTP_STATUS = {
     no_request_handler: 404,
     game_server_error: 500,
     hosting_paused: 403,
+    rented_share_used: 403,
     slow_down: 429,
     bad_origin: 403,
     busy: 503,

package/src/room.d.ts

@@ -7,6 +7,7 @@
  * running one copy of the game server. Names follow docs/NAMING.md.
  */
 import { type GameDatabase } from "./database.ts";
+import { type DoorContract, type DoorShape } from "./doors.ts";
 import type { PassClaims, PlayerKind, ReceiptClaims } from "./pass.ts";
 import type { Server } from "./requests.ts";
 import { type Schedule, type ScheduledRun } from "./schedules.ts";
@@ -1117,7 +1118,7 @@ export type ClientMessage = {
  * the game became unavailable, its kept room was deleted, or no players were left for its spectators.
  */
 export type EndReason = "game" | "hosting_paused" | "game_server_stopped" | "game_unavailable" | "kept_room_deleted" | "no_players";
-export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "bad_player_token" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full" | "chat_not_here" | "chat_not_allowed" | "chat_empty" | "chat_too_long" | "chat_too_fast";
+export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "bad_player_token" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "rented_share_used" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full" | "chat_not_here" | "chat_not_allowed" | "chat_empty" | "chat_too_long" | "chat_too_fast";
 export declare const ERROR_TEXT: Record<RoomErrorCode, string>;
 /** What players are told when Zaisma ends a match at room.endsAt. */
 export declare const HOSTING_PAUSED_END_MESSAGE = "This game's hosting is paused, so this match has ended. New rooms open again when the month resets or its developer adds credit.";
@@ -1334,6 +1335,105 @@ export interface StateSyncHooks {
 export declare const NO_MESSAGE_TYPE = "(none)";
 export declare const BYTES_MESSAGE_TYPE = "(bytes)";
 export declare const ZAISMA_MESSAGE_TYPE = "(zaisma)";
+export declare const ROOM_FRAME: Readonly<Record<string, unknown>>;
+/**
+ * Every message a room takes (docs/DOORS.md). receive's switch is over these names, so a new one without a row
+ * doesn't build. A spectator may send only what's for room members. hello comes first and proves the pass; chat is the host's to take before receive (readChatMessage);
+ * bytes is every binary message (receiveBytes). A type with no row, maybe from a newer SDK, is counted and ignored.
+ */
+export declare const ROOM_MESSAGE_DOORS: {
+    readonly hello: {
+        readonly whoMayCall: "pass_holder";
+        readonly reaches: "room";
+        readonly trusts: readonly ["player_pass"];
+        readonly provenBy: {
+            readonly source_path: "packages/game-server/src/pass.ts";
+            readonly symbol_name: "verifyPass";
+        };
+        readonly takes: {
+            readonly query: {};
+            readonly body: {
+                readonly kind: "json";
+                readonly fields: {
+                    readonly idleTimeoutSec: DoorShape;
+                    readonly idleCheckEnabled: DoorShape;
+                    readonly type: DoorShape;
+                    readonly protocolVersionNumber: DoorShape;
+                    readonly pass: DoorShape;
+                    readonly playerToken: DoorShape;
+                    readonly joinData: DoorShape;
+                    readonly room: DoorShape;
+                    readonly isSpectator: DoorShape;
+                    readonly isQuickJoin: DoorShape;
+                    readonly avoidBlockedPlayers: DoorShape;
+                    readonly versionId: DoorShape;
+                    readonly playShare: DoorShape;
+                    readonly hasGraphicsChip: DoorShape;
+                    readonly isInputSeen: DoorShape;
+                };
+                readonly required: readonly ["type"];
+                readonly maximumSizeBytes: number;
+            };
+        };
+        readonly answers: import("./doors.ts").DoorAnswer;
+        readonly limit: {
+            readonly level: "steady";
+            readonly counts: "player";
+        };
+    };
+    readonly probe_answer: DoorContract;
+    readonly room: DoorContract;
+    readonly kick: DoorContract;
+    readonly here: DoorContract;
+    readonly idle: DoorContract;
+    readonly hidden: DoorContract;
+    readonly shown: DoorContract;
+    readonly back: DoorContract;
+    readonly message: DoorContract;
+    readonly bytes: {
+        readonly whoMayCall: "room_player";
+        readonly reaches: "room";
+        readonly trusts: readonly ["player_pass"];
+        readonly takes: {
+            readonly query: {};
+            readonly body: {
+                readonly kind: "bytes";
+                readonly maximumSizeBytes: number;
+            };
+        };
+        readonly answers: import("./doors.ts").DoorAnswer;
+        readonly limit: {
+            readonly whyNoLimit: "room_token_bucket";
+        };
+    };
+    readonly chat: DoorContract;
+    readonly block: DoorContract;
+    readonly unblock: DoorContract;
+    readonly friend_request: DoorContract;
+    readonly "zaisma:purchase": {
+        readonly reaches: "purchase";
+        readonly trusts: readonly ["player_pass", "purchase_receipt"];
+        readonly takes: import("./doors.ts").DoorTakes;
+        readonly answers: import("./doors.ts").DoorAnswer;
+        readonly limit: import("./doors.ts").DoorLimit;
+        readonly whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    } | {
+        readonly reaches: "purchase";
+        readonly trusts: readonly ["player_pass", "purchase_receipt"];
+        readonly takes: import("./doors.ts").DoorTakes;
+        readonly answers: import("./doors.ts").DoorAnswer;
+        readonly limit: import("./doors.ts").DoorLimit;
+        readonly whoMayCall: import("./doors.ts").DoorCallerProvenByFunction;
+        readonly provenBy: import("./doors.ts").DoorProof;
+    };
+};
+/**
+ * Whether a message breaks its door's shape: a field of the wrong type or past its bound, or one it needs missing. A
+ * name the door doesn't know is left alone and never read, unlike at other doors: a game's SDK comes from Zaisma and
+ * its server may be the developer's own, older one, so a newer SDK's field has to keep working there.
+ */
+export declare function roomMessageProblem(type: Exclude<RoomMessageType, "bytes">, message: Record<string, unknown>): string | null;
+export type RoomMessageType = keyof typeof ROOM_MESSAGE_DOORS;
 export declare const OTHER_MESSAGE_TYPE = "(other)";
 /** State sync's updates (stateSyncEnabled). */
 export declare const STATE_MESSAGE_TYPE = "(state)";