@zaisma/game-server 0.0.1 → 1.1.0

package/src/dump.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The game database in and out as SQLite's own SQL dump (docs/DECISIONS.md, "Import, export and undo"):
+ * the CREATE TABLEs and INSERTs that `sqlite3 game.sqlite .dump` writes, so a dump from Zaisma loads into
+ * any SQLite (`sqlite3 game.sqlite < dump.sql`, the Node runner's file) and a dump from there loads into
+ * Zaisma. Zaisma's database is a Durable Object (apps/rooms/src/database.ts); the upload command keeps a
+ * copy of the same reading for .sqlite files (packages/cli/zaisma.mjs), held to this by test/node/dump.test.ts.
+ */
+import { type DatabaseRow, type DatabaseValue } from "./database.ts";
+/** Runs one SELECT for the dump: its rows, and the rows SQLite read for it (they count towards the month's reads). */
+export type DumpRead = (sql: string, values: DatabaseValue[]) => {
+    rows: DatabaseRow[];
+    readRowCount: number;
+};
+/** One part of a dump, and where the next one starts. */
+export interface DumpPart {
+    dumpSql: string;
+    /** null on the last part. */
+    nextCursor: string | null;
+    readRowCount: number;
+}
+export declare const DUMP_LIMITS: {
+    /** The most SQL one part of an export holds, unless a single row is bigger on its own. */
+    readonly exportPartSizeBytes: number;
+    /** The most one part of an import may hold: a little over an export's part, so every export part fits. */
+    readonly maximumImportPartSizeBytes: number;
+};
+/** A cursor that isn't an earlier part's next_cursor, or whose table is gone. */
+export declare class DumpCursorError extends Error {
+}
+/** A name in double quotes, as SQLite takes any table or column name. */
+export declare function quoteName(name: string): string;
+/**
+ * One part of the database's dump, up to partSizeBytes of SQL (more only when one row is bigger on its own),
+ * starting where cursor says, or at the start for null. The parts, put together in order, are one whole dump. It reads
+ * table by table, so a game writing while it runs can land between parts: it isn't a snapshot.
+ */
+export declare function dumpPart(read: DumpRead, cursor: string | null, partSizeBytes?: number): DumpPart;
+/** How many bytes text takes as UTF-8, without making the bytes. */
+export declare function utf8SizeBytes(text: string): number;
+/** A statement of a dump, ready to run: its SQL, the values for its ?s, and which statement of the part it came from (from 1). */
+export interface ImportStatement {
+    sql: string;
+    values: DatabaseValue[];
+    statementNumber: number;
+}
+/** What a part of a dump runs: its statements, and how many it left out (the transaction and settings sqlite3 writes around them). */
+export interface ImportPlan {
+    statements: ImportStatement[];
+    statementCount: number;
+    skippedStatementCount: number;
+}
+/**
+ * Reads a part of a dump into the statements to run. Import only adds: it takes CREATE and INSERT
+ * statements, and leaves out what sqlite3 writes around them (the transaction, PRAGMAs, ANALYZE and its
+ * sqlite_stat1 rows). The values in an INSERT become values for ?s, since Zaisma's database takes
+ * statements up to 100 KB and a row of a dump can be bigger; unistr('…'), which sqlite3 writes for text with
+ * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up.
+ */
+export declare function importStatements(dumpSql: string): ImportPlan;
+/** The start of a statement, for an error. */
+export declare function preview(text: string): string;

package/src/dump.js

@@ -0,0 +1,282 @@
+/**
+ * The game database in and out as SQLite's own SQL dump (docs/DECISIONS.md, "Import, export and undo"):
+ * the CREATE TABLEs and INSERTs that `sqlite3 game.sqlite .dump` writes, so a dump from Zaisma loads into
+ * any SQLite (`sqlite3 game.sqlite < dump.sql`, the Node runner's file) and a dump from there loads into
+ * Zaisma. Zaisma's database is a Durable Object (apps/rooms/src/database.ts); the upload command keeps a
+ * copy of the same reading for .sqlite files (packages/cli/zaisma.mjs), held to this by test/node/dump.test.ts.
+ */
+import { DATABASE_LIMITS, DatabaseError, scanStatements } from "./database.js";
+export const DUMP_LIMITS = {
+    /** The most SQL one part of an export holds, unless a single row is bigger on its own. */
+    exportPartSizeBytes: 4 * 1024 * 1024,
+    /** The most one part of an import may hold: a little over an export's part, so every export part fits. */
+    maximumImportPartSizeBytes: 5 * 1024 * 1024,
+};
+/** A cursor that isn't an earlier part's next_cursor, or whose table is gone. */
+export class DumpCursorError extends Error {
+}
+/** Rows read per SELECT while dumping a table. */
+const PAGE_ROW_COUNT = 500;
+/** A dump starts and ends the way sqlite3's does, so it loads in one transaction anywhere. */
+const DUMP_START = "PRAGMA foreign_keys=OFF;\nBEGIN TRANSACTION;\n";
+const DUMP_END = "COMMIT;\n";
+// What's in the database, in the order it was made: tables, views, indexes and triggers, with what kind
+// of table each is (a normal one, a virtual one, or a virtual table's own "shadow" table) and whether it has
+// rowids. Cloudflare's own tables (_cf_…) are never the developer's.
+const SCHEMA_SQL = "SELECT entry.type AS type, entry.name AS name, entry.tbl_name AS table_name, entry.sql AS sql, listed.type AS table_kind, listed.wr AS is_without_rowid " +
+    "FROM sqlite_schema AS entry LEFT JOIN pragma_table_list AS listed ON listed.schema = 'main' AND listed.name = entry.name " +
+    "WHERE entry.sql IS NOT NULL AND substr(entry.tbl_name, 1, 4) <> '_cf_' ORDER BY entry.rowid";
+/** A name in double quotes, as SQLite takes any table or column name. */
+export function quoteName(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/**
+ * One part of the database's dump, up to partSizeBytes of SQL (more only when one row is bigger on its own),
+ * starting where cursor says, or at the start for null. The parts, put together in order, are one whole dump. It reads
+ * table by table, so a game writing while it runs can land between parts: it isn't a snapshot.
+ */
+export function dumpPart(read, cursor, partSizeBytes = DUMP_LIMITS.exportPartSizeBytes) {
+    let readRowCount = 0;
+    const select = (sql, values = []) => {
+        const answer = read(sql, values);
+        readRowCount += answer.readRowCount;
+        return answer.rows;
+    };
+    const entries = select(SCHEMA_SQL);
+    const tables = entries.filter((entry) => entry.type === "table" && (entry.table_kind === "table" || entry.table_kind === "virtual") && !entry.name.startsWith("sqlite_"));
+    let dumpSql = "";
+    let dumpSizeBytes = 0;
+    let hasRows = false;
+    const add = (sql) => {
+        dumpSql += sql;
+        dumpSizeBytes += utf8SizeBytes(sql);
+    };
+    let tableIndex = 0;
+    let position = null;
+    if (cursor === null)
+        add(DUMP_START);
+    else {
+        position = readCursor(cursor);
+        tableIndex = tables.findIndex((table) => table.name === position.table_name);
+        if (tableIndex === -1)
+            throw new DumpCursorError(`The table ${position.table_name} isn't there any more.`);
+    }
+    for (; tableIndex < tables.length; tableIndex++) {
+        const table = tables[tableIndex];
+        if (!position)
+            add(`${table.sql};\n`);
+        position ??= { table_name: table.name, last_rowid_number: table.is_without_rowid ? null : 0, dumped_row_count: 0 };
+        const columns = select("SELECT name, hidden = 0 AS is_insertable, pk AS primary_key_number FROM pragma_table_xinfo(?) ORDER BY cid", [table.name]);
+        // Generated columns, and a virtual table's hidden ones, can't be inserted: the INSERTs name the rest.
+        const insertedColumns = columns.filter((column) => column.is_insertable === 1);
+        const insertInto = `INSERT INTO ${quoteName(table.name)}${insertedColumns.length < columns.length ? `(${insertedColumns.map((column) => quoteName(column.name)).join(",")})` : ""} VALUES(`;
+        // quote() writes each value as SQL, the way sqlite3's .dump does: 'text' with '' for a quote, X'…' for bytes.
+        const valuesSql = insertedColumns.map((column, i) => `quote(${quoteName(column.name)}) AS value_${i}`).join(", ");
+        const primaryKey = columns.filter((column) => column.primary_key_number > 0).sort((first, second) => first.primary_key_number - second.primary_key_number);
+        while (true) {
+            const rows = position.last_rowid_number === null
+                ? select(`SELECT ${valuesSql} FROM ${quoteName(table.name)} ORDER BY ${primaryKey.map((column) => quoteName(column.name)).join(", ")} LIMIT ${PAGE_ROW_COUNT} OFFSET ?`, [position.dumped_row_count])
+                : select(`SELECT rowid AS paging_rowid, ${valuesSql} FROM ${quoteName(table.name)} WHERE rowid > ? ORDER BY rowid LIMIT ${PAGE_ROW_COUNT}`, [position.last_rowid_number]);
+            for (const row of rows) {
+                const insert = `${insertInto}${insertedColumns.map((_, i) => row[`value_${i}`]).join(",")});\n`;
+                // The part ends before a row that would take it past partSizeBytes; the next starts with that row.
+                if (hasRows && dumpSizeBytes + utf8SizeBytes(insert) > partSizeBytes)
+                    return { dumpSql, nextCursor: writeCursor(position), readRowCount };
+                add(insert);
+                hasRows = true;
+                if (position.last_rowid_number === null)
+                    position.dumped_row_count++;
+                else
+                    position.last_rowid_number = row.paging_rowid;
+            }
+            if (rows.length < PAGE_ROW_COUNT)
+                break;
+        }
+        position = null;
+    }
+    // The rest is small: AUTOINCREMENT's counters, then views, indexes and triggers, made after the rows
+    // so triggers don't fire on them, then the end.
+    if (entries.some((entry) => entry.name === "sqlite_sequence")) {
+        add("DELETE FROM sqlite_sequence;\n");
+        for (const counter of select("SELECT quote(name) AS name_sql, quote(seq) AS counter_sql FROM sqlite_sequence"))
+            add(`INSERT INTO sqlite_sequence VALUES(${counter.name_sql},${counter.counter_sql});\n`);
+    }
+    for (const entry of entries) {
+        if ((entry.type === "view" || entry.type === "index" || entry.type === "trigger") && !entry.table_name.startsWith("sqlite_"))
+            add(`${entry.sql};\n`);
+    }
+    add(DUMP_END);
+    return { dumpSql, nextCursor: null, readRowCount };
+}
+/** How many bytes text takes as UTF-8, without making the bytes. */
+export function utf8SizeBytes(text) {
+    let sizeBytes = 0;
+    for (let i = 0; i < text.length; i++) {
+        const codeUnitNumber = text.charCodeAt(i);
+        // A surrogate pair is one character of 4 bytes, 2 for each half.
+        sizeBytes += codeUnitNumber < 0x80 ? 1 : codeUnitNumber < 0x800 ? 2 : codeUnitNumber >= 0xd800 && codeUnitNumber < 0xe000 ? 2 : 3;
+    }
+    return sizeBytes;
+}
+function writeCursor(position) {
+    const bytes = new TextEncoder().encode(JSON.stringify(position));
+    return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function readCursor(cursor) {
+    let position;
+    try {
+        const binary = atob(cursor.replaceAll("-", "+").replaceAll("_", "/"));
+        position = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0))));
+    }
+    catch {
+        throw new DumpCursorError("The cursor isn't one an export answered.");
+    }
+    const { table_name: tableName, last_rowid_number: lastRowidNumber, dumped_row_count: dumpedRowCount } = (position ?? {});
+    if (typeof tableName !== "string" || !(lastRowidNumber === null || Number.isInteger(lastRowidNumber)) || !Number.isInteger(dumpedRowCount))
+        throw new DumpCursorError("The cursor isn't one an export answered.");
+    return { table_name: tableName, last_rowid_number: lastRowidNumber, dumped_row_count: dumpedRowCount };
+}
+const IMPORT_FIX = "Import takes a dump's CREATE and INSERT statements, as sqlite3's .dump or export_database writes them; it only adds. Run other changes with query_database or batch_database.";
+/**
+ * Reads a part of a dump into the statements to run. Import only adds: it takes CREATE and INSERT
+ * statements, and leaves out what sqlite3 writes around them (the transaction, PRAGMAs, ANALYZE and its
+ * sqlite_stat1 rows). The values in an INSERT become values for ?s, since Zaisma's database takes
+ * statements up to 100 KB and a row of a dump can be bigger; unistr('…'), which sqlite3 writes for text with
+ * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up.
+ */
+export function importStatements(dumpSql) {
+    const statements = [];
+    const scanned = scanStatements(dumpSql);
+    let skippedStatementCount = 0;
+    scanned.forEach((scannedStatement, i) => {
+        const statementNumber = i + 1;
+        const text = dumpSql.slice(scannedStatement.startIndex, scannedStatement.endIndex);
+        const [firstWord = "", secondWord = "", thirdWord = ""] = scannedStatement.leadingWords;
+        const words = scannedStatement.leadingWords.join(" ");
+        const isSkipped = ["BEGIN", "COMMIT", "END", "ROLLBACK", "ANALYZE"].includes(firstWord) ||
+            (firstWord === "PRAGMA" && (secondWord === "FOREIGN_KEYS" || secondWord === "WRITABLE_SCHEMA")) ||
+            /^CREATE TABLE (IF NOT EXISTS )?SQLITE_SEQUENCE$/.test(words) ||
+            words === "DELETE FROM SQLITE_SEQUENCE" ||
+            (firstWord === "INSERT" && secondWord === "INTO" && (thirdWord === "SQLITE_STAT1" || thirdWord === "SQLITE_STAT4"));
+        if (isSkipped) {
+            skippedStatementCount++;
+            return;
+        }
+        const refuse = (message) => new DatabaseError("bad_sql", `Statement ${statementNumber} of the dump (${preview(text)}): ${message}`, IMPORT_FIX);
+        if (firstWord === "CREATE") {
+            statements.push({ sql: text, values: [], statementNumber });
+            return;
+        }
+        if (firstWord !== "INSERT")
+            throw refuse(`${firstWord || "it"} isn't a CREATE or INSERT.`);
+        if (secondWord === "OR" && thirdWord === "REPLACE")
+            throw refuse("INSERT OR REPLACE changes rows that are there.");
+        const bound = bindLiterals(text, refuse);
+        if (thirdWord === "SQLITE_SEQUENCE") {
+            // sqlite_sequence has a row per table and no key: set the counter, never lower it.
+            const counterMatch = /VALUES\s*\(\s*\?\s*,\s*(\d+)\s*\)$/i.exec(bound.sql);
+            if (!counterMatch || bound.values.length !== 1)
+                throw refuse("sqlite_sequence takes a table's name and its counter, like INSERT INTO sqlite_sequence VALUES('scores',12).");
+            const tableName = bound.values[0];
+            const counter = counterMatch[1];
+            // The counter goes in the SQL (it's digits only): bound, a number would be stored as a REAL.
+            statements.push({ sql: `INSERT INTO sqlite_sequence (name, seq) SELECT ?, ${counter} WHERE NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = ?)`, values: [tableName, tableName], statementNumber });
+            statements.push({ sql: `UPDATE sqlite_sequence SET seq = max(seq, ${counter}) WHERE name = ?`, values: [tableName], statementNumber });
+            return;
+        }
+        if (bound.values.length > DATABASE_LIMITS.maximumValueCount)
+            throw new DatabaseError("bad_values", `Statement ${statementNumber} of the dump (${preview(text)}) has ${bound.values.length} text and blob values.`, `Give each row its own INSERT, as sqlite3's .dump does: the database takes up to ${DATABASE_LIMITS.maximumValueCount} values a statement.`);
+        statements.push({ sql: bound.sql, values: bound.values, statementNumber });
+    });
+    return { statements, statementCount: scanned.length, skippedStatementCount };
+}
+/** The start of a statement, for an error. */
+export function preview(text) {
+    const oneLine = text.replace(/\s+/g, " ");
+    return oneLine.length > 80 ? `${oneLine.slice(0, 79)}…` : oneLine;
+}
+/**
+ * An INSERT with its text and blob literals as ?s, and their values: 'it''s' becomes "it's", X'00ff' the
+ * bytes and unistr('a\u000ab') the text it stands for. Numbers, NULL and names stay as they are.
+ */
+function bindLiterals(text, refuse) {
+    const values = [];
+    let sql = "";
+    let i = 0;
+    /** The text of the 'quoted' literal starting at startIndex, and where it ends. */
+    const readQuoted = (startIndex) => {
+        let endIndex = startIndex + 1;
+        let literal = "";
+        while (endIndex < text.length) {
+            if (text[endIndex] === "'") {
+                if (text[endIndex + 1] !== "'")
+                    return { literal, endIndex: endIndex + 1 };
+                literal += "'";
+                endIndex += 2;
+            }
+            else
+                literal += text[endIndex++];
+        }
+        throw refuse("a quote isn't closed.");
+    };
+    const isWordCharacter = (character) => character !== undefined && /[A-Za-z0-9_$]/.test(character);
+    while (i < text.length) {
+        const character = text[i];
+        const afterWord = isWordCharacter(text[i - 1]);
+        if (character === "-" && text[i + 1] === "-") {
+            const endIndex = text.indexOf("\n", i);
+            i = endIndex === -1 ? text.length : endIndex + 1;
+            sql += " ";
+        }
+        else if (character === "/" && text[i + 1] === "*") {
+            const endIndex = text.indexOf("*/", i + 2);
+            i = endIndex === -1 ? text.length : endIndex + 2;
+            sql += " ";
+        }
+        else if (character === '"' || character === "`" || character === "[") {
+            // A name: copied as it is.
+            const close = character === "[" ? "]" : character;
+            let endIndex = i + 1;
+            while (endIndex < text.length && !(text[endIndex] === close && text[endIndex + 1] !== close))
+                endIndex += text[endIndex] === close ? 2 : 1;
+            sql += text.slice(i, endIndex + 1);
+            i = endIndex + 1;
+        }
+        else if (character === "'") {
+            const { literal, endIndex } = readQuoted(i);
+            values.push(literal);
+            sql += "?";
+            i = endIndex;
+        }
+        else if ((character === "x" || character === "X") && text[i + 1] === "'" && !afterWord) {
+            const { literal, endIndex } = readQuoted(i + 1);
+            if (literal.length % 2 || /[^0-9A-Fa-f]/.test(literal))
+                throw refuse(`X'${literal.slice(0, 20)}' isn't bytes in hex.`);
+            values.push(Uint8Array.from({ length: literal.length / 2 }, (_, byteIndex) => parseInt(literal.slice(byteIndex * 2, byteIndex * 2 + 2), 16)));
+            sql += "?";
+            i = endIndex;
+        }
+        else if (!afterWord && /^unistr\s*\(\s*'/i.test(text.slice(i, i + 40))) {
+            const quoteIndex = text.indexOf("'", i);
+            const { literal, endIndex } = readQuoted(quoteIndex);
+            const closeMatch = /^\s*\)/.exec(text.slice(endIndex));
+            if (!closeMatch)
+                throw refuse("unistr( takes one 'text'.");
+            values.push(literal.replace(/\\(\\|u[0-9A-Fa-f]{4}|\+[0-9A-Fa-f]{6}|U[0-9A-Fa-f]{8}|[0-9A-Fa-f]{4})/g, (_, escape) => (escape === "\\" ? "\\" : String.fromCodePoint(parseInt(escape.replace(/^[uU+]/, ""), 16)))));
+            sql += "?";
+            i = endIndex + closeMatch[0].length;
+        }
+        else if (isWordCharacter(character)) {
+            let endIndex = i + 1;
+            while (isWordCharacter(text[endIndex]))
+                endIndex++;
+            sql += text.slice(i, endIndex);
+            i = endIndex;
+        }
+        else {
+            sql += character;
+            i++;
+        }
+    }
+    return { sql, values };
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, type Audience, type AwayInfo, type AwayMode, type AwayReason, type BroadcastOptions, type Delivery, type GameServer, type GameServerErrorCode, type HandlerResult, type IdleCheck, type JoinAnswer, type JoinInfo, type KickOptions, type LeaveInfo, type LeaveReason, type MoveOptions, type MoveResult, type Player, type Purchase, type Refusal, type ReserveOptions, type RestoreInfo, type Room, type RoomErrorCode, type RoomInfo, type SendOptions, type VersionUpdate, } from "./room.ts";
+export { REQUEST_LIMITS, type RequestErrorCode, type Server } from "./requests.ts";
+export { SCHEDULE_LIMITS, type Schedule, type ScheduledRun } from "./schedules.ts";
+export { WEBHOOK_LIMITS, verifyWebhook, type WebhookError, type WebhookErrorCode, type WebhookEvent, type WebhookEventKind, type WebhookHeaders } from "./webhooks.ts";
+export { DATABASE_LIMITS, DatabaseError, type DatabaseErrorCode, type DatabaseRow, type DatabaseStatement, type DatabaseValue, type GameDatabase } from "./database.ts";
+export { OUTSIDE_CALL_LIMITS, OutsideCallError, type OutsideCallErrorCode } from "./outside-calls.ts";
+export { PASS_ISSUER_URL, PASS_TOKEN_TYPE, PASS_VERSION_NUMBER, PassError, RECEIPT_ISSUER_URL, RECEIPT_TOKEN_TYPE, RECEIPT_VERSION_NUMBER, ReceiptError, canChat, passesAreFriends, passesHaveBlockBetween, verifyPass, verifyReceipt, type PassClaims, type PassErrorCode, type PassExpectations, type PlayerKind, type PublicKey, type ReceiptClaims, type ReceiptErrorCode, type ReceiptExpectations, type WhoCanChat } from "./pass.ts";
+export { CHAT_CHECK_LIMITS, ChatCheckError, checkChat, type ChatCheck, type ChatCheckOptions, type ChatCheckReason } from "./chat.ts";
+export { guestName, isRoomCode } from "./names.ts";
+export { relay } from "./relay.ts";

package/src/index.js

@@ -0,0 +1,12 @@
+// What @zaisma/game-server gives developers, named one by one: from v1 it only grows (test/contracts).
+// Zaisma's own parts of the package, never locked, are in ./internal.
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, } from "./room.js";
+export { REQUEST_LIMITS } from "./requests.js";
+export { SCHEDULE_LIMITS } from "./schedules.js";
+export { WEBHOOK_LIMITS, verifyWebhook } from "./webhooks.js";
+export { DATABASE_LIMITS, DatabaseError } from "./database.js";
+export { OUTSIDE_CALL_LIMITS, OutsideCallError } from "./outside-calls.js";
+export { PASS_ISSUER_URL, PASS_TOKEN_TYPE, PASS_VERSION_NUMBER, PassError, RECEIPT_ISSUER_URL, RECEIPT_TOKEN_TYPE, RECEIPT_VERSION_NUMBER, ReceiptError, canChat, passesAreFriends, passesHaveBlockBetween, verifyPass, verifyReceipt } from "./pass.js";
+export { CHAT_CHECK_LIMITS, ChatCheckError, checkChat } from "./chat.js";
+export { guestName, isRoomCode } from "./names.js";
+export { relay } from "./relay.js";

package/src/internal.d.ts

@@ -0,0 +1,13 @@
+export * from "./room.ts";
+export * from "./room-calls.ts";
+export * from "./state-sync.ts";
+export * from "./database.ts";
+export * from "./dump.ts";
+export * from "./requests.ts";
+export * from "./outside-calls.ts";
+export * from "./schedules.ts";
+export * from "./webhooks.ts";
+export * from "./pass.ts";
+export * from "./names.ts";
+export * from "./chat.ts";
+export * from "./relay.ts";

package/src/internal.js

@@ -0,0 +1,15 @@
+// Zaisma's own use of the game server package: everything in src, and what only Zaisma does (signing passes).
+// Never published or locked: games and developers' servers use the package's index.
+export * from "./room.js";
+export * from "./room-calls.js";
+export * from "./state-sync.js";
+export * from "./database.js";
+export * from "./dump.js";
+export * from "./requests.js";
+export * from "./outside-calls.js";
+export * from "./schedules.js";
+export * from "./webhooks.js";
+export * from "./pass.js";
+export * from "./names.js";
+export * from "./chat.js";
+export * from "./relay.js";

package/src/names.d.ts

@@ -0,0 +1,4 @@
+/** A friendly guest name like "Swift Fox 42". Guests can't type their own names. */
+export declare function guestName(): string;
+export declare function roomCode(): string;
+export declare function isRoomCode(code: string): boolean;

package/src/names.js

@@ -0,0 +1,18 @@
+const ADJECTIVES = ["Swift", "Brave", "Quiet", "Lucky", "Bright", "Clever", "Sunny", "Bold", "Calm", "Fuzzy", "Jolly", "Nimble", "Rapid", "Sly", "Witty", "Zany", "Cosmic", "Mighty", "Tiny", "Wild"];
+const ANIMALS = ["Fox", "Otter", "Panda", "Hawk", "Lynx", "Koala", "Badger", "Falcon", "Gecko", "Moose", "Owl", "Raven", "Seal", "Tiger", "Wolf", "Yak", "Bison", "Crane", "Heron", "Newt"];
+function pick(list, randomNumber) {
+    return list[randomNumber % list.length];
+}
+/** A friendly guest name like "Swift Fox 42". Guests can't type their own names. */
+export function guestName() {
+    const [adjectiveNumber, animalNumber, endNumber] = crypto.getRandomValues(new Uint32Array(3));
+    return `${pick(ADJECTIVES, adjectiveNumber)} ${pick(ANIMALS, animalNumber)} ${10 + (endNumber % 90)}`;
+}
+/** No 0/O or 1/I, so codes read out loud or typed from a screen don't get mixed up. */
+const CODE_ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ";
+export function roomCode() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(6)), (byte) => CODE_ALPHABET[byte & 31]).join("");
+}
+export function isRoomCode(code) {
+    return /^[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{6}$/.test(code);
+}

package/src/outside-calls.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Calls from a game server to other servers (game server reach): plain fetch(). On Zaisma every call
+ * goes through the rooms Worker's gateway (apps/rooms/src/outbound.ts), which takes only https to the
+ * hosts the game lists in game_server_allowed_hosts; a call it refuses throws an OutsideCallError in
+ * the game server with one of these codes. On the developer's own server the Node runner calls out
+ * freely, so the same code runs in both.
+ */
+export type OutsideCallErrorCode = 
+/** Only https: addresses. */
+"not_https"
+/** An IP address, this computer, or Zaisma's own domains. */
+ | "unreachable_host"
+/** A host the game doesn't list in game_server_allowed_hosts. */
+ | "host_not_allowed"
+/** More calls a minute than a game makes in one place (OUTSIDE_CALL_LIMITS.maximumCallsPerMin). */
+ | "outside_call_limit"
+/** A body over OUTSIDE_CALL_LIMITS.maximumBodySizeBytes. */
+ | "too_big"
+/** No answer within OUTSIDE_CALL_LIMITS.timeoutSec. */
+ | "outside_call_timeout"
+/** The other server couldn't be reached, like a name that doesn't exist. */
+ | "outside_call_failed";
+export declare const OUTSIDE_CALL_LIMITS: {
+    readonly maximumBodySizeBytes: number;
+    readonly timeoutSec: 10;
+    readonly maximumCallsPerMin: 600;
+};
+export declare const OUTSIDE_CALL_ERROR_CODES: readonly string[];
+/** A call from a game server to another server that Zaisma's gateway refused (or that failed), with a code, what happened and what to do. */
+export declare class OutsideCallError extends Error {
+    readonly code: OutsideCallErrorCode;
+    readonly fix: string;
+    constructor(code: OutsideCallErrorCode, message: string, fix: string);
+    /** True for any error named OutsideCallError with a known code, so instanceof works for the copy a game's sandbox has too. */
+    static [Symbol.hasInstance](candidate: unknown): boolean;
+}
+/** What a refused call answers inside the sandbox, which its fetch() turns into an OutsideCallError. */
+export interface OutsideCallRefusal {
+    error: {
+        code: OutsideCallErrorCode;
+        message: string;
+        fix: string;
+    };
+}
+/** The header a refusal comes back with, so the sandbox can tell it from a server's own answer. */
+export declare const OUTSIDE_CALL_REFUSAL_HEADER = "zaisma-outside-call-refused";

package/src/outside-calls.js

@@ -0,0 +1,30 @@
+/**
+ * Calls from a game server to other servers (game server reach): plain fetch(). On Zaisma every call
+ * goes through the rooms Worker's gateway (apps/rooms/src/outbound.ts), which takes only https to the
+ * hosts the game lists in game_server_allowed_hosts; a call it refuses throws an OutsideCallError in
+ * the game server with one of these codes. On the developer's own server the Node runner calls out
+ * freely, so the same code runs in both.
+ */
+export const OUTSIDE_CALL_LIMITS = {
+    maximumBodySizeBytes: 5 * 1024 * 1024,
+    timeoutSec: 10,
+    maximumCallsPerMin: 600,
+};
+export const OUTSIDE_CALL_ERROR_CODES = ["not_https", "unreachable_host", "host_not_allowed", "outside_call_limit", "too_big", "outside_call_timeout", "outside_call_failed"];
+/** A call from a game server to another server that Zaisma's gateway refused (or that failed), with a code, what happened and what to do. */
+export class OutsideCallError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(`${message} ${fix} (${code})`);
+        this.name = "OutsideCallError";
+        this.code = code;
+        this.fix = fix;
+    }
+    /** True for any error named OutsideCallError with a known code, so instanceof works for the copy a game's sandbox has too. */
+    static [Symbol.hasInstance](candidate) {
+        return candidate instanceof Error && candidate.name === "OutsideCallError" && OUTSIDE_CALL_ERROR_CODES.includes(candidate.code);
+    }
+}
+/** The header a refusal comes back with, so the sandbox can tell it from a server's own answer. */
+export const OUTSIDE_CALL_REFUSAL_HEADER = "zaisma-outside-call-refused";