@zaisma/game-server 0.0.1 → 1.1.0

package/src/schedules.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Schedules: a game server running by itself, outside rooms and requests, for daily resets, weekly
+ * leaderboards or a persistent world's turns. The game server lists its schedules, each a name and a
+ * cron in UTC, and onSchedule(run, server) runs at each, with server.database. Zaisma runs them in the
+ * game's own object (apps/rooms/src/game-server.ts) and the Node runner with timers (startSchedules),
+ * both from the times here, so a schedule runs at the same minutes in both.
+ *
+ * Crons are the usual five fields, minute hour day-of-month month day-of-week, in UTC: numbers, *,
+ * ranges (1-5), steps (*\/15) and lists (1,15). So a schedule runs at most once a minute.
+ */
+import type { Server } from "./requests.ts";
+/** One of a game server's schedules: its name, and when it runs. */
+export interface Schedule {
+    /** Lowercase letters, digits and hyphens, like "daily-reset". onSchedule tells them apart by it. */
+    name: string;
+    /** When it runs: five fields, minute hour day-of-month month day-of-week, in UTC. "0 0 * * *" is every midnight. */
+    cron: string;
+}
+/** A schedule's run, as onSchedule gets it: which schedule, and the minute it was due (an ISO time, UTC). */
+export interface ScheduledRun {
+    name: string;
+    cron: string;
+    scheduledAt: string;
+}
+export declare const SCHEDULE_LIMITS: {
+    readonly maximumScheduleCount: 10;
+    readonly maximumNameCharacterCount: 40;
+    /** How long onSchedule may take, awaiting the database included, before the run fails. */
+    readonly runTimeoutSec: 30;
+};
+/** A game server that runs on schedules. */
+export interface ScheduleHandler {
+    schedules?: readonly Schedule[];
+    onSchedule?(run: ScheduledRun, server: Server): unknown;
+}
+/** A cron read into the values each field allows. Day 7 of the week is Sunday, like 0. */
+interface CronTimes {
+    minutes: boolean[];
+    hours: boolean[];
+    monthDays: boolean[];
+    months: boolean[];
+    weekDays: boolean[];
+    /** Both day fields given: a day matches either, as cron has always done. */
+    isEitherDay: boolean;
+}
+/** Read a cron, or say what's wrong with it. */
+export declare function readCron(cron: unknown): {
+    cronTimes: CronTimes;
+} | {
+    mistake: string;
+};
+/** When a cron next runs after afterMs (epoch milliseconds): a whole minute, UTC. Null for a cron that doesn't read. */
+export declare function nextRunAtMs(cron: string, afterMs: number): number | null;
+/**
+ * A game server's schedules, checked: a list of up to SCHEDULE_LIMITS.maximumScheduleCount
+ * { name, cron }, names different, crons that read. Schedules need onSchedule, and onSchedule needs
+ * schedules. Otherwise what's wrong, and what to do.
+ */
+export declare function readSchedules(schedules: unknown, hasOnSchedule: boolean): {
+    schedules: Schedule[];
+} | {
+    message: string;
+    fix: string;
+};
+/**
+ * Run a game server's onSchedule for one run, with a time limit. failure says why it failed, for the
+ * game server's errors: it threw, or took longer than SCHEDULE_LIMITS.runTimeoutSec.
+ */
+export declare function runSchedule(handler: ScheduleHandler, run: ScheduledRun, server: Server): Promise<{
+    isDone: true;
+} | {
+    failure: string;
+}>;
+/**
+ * Run a game server's schedules with timers, as the Node runner does on the developer's own server:
+ * each at the minutes its cron gives, from the moment this starts. onFailure hears about a run that
+ * failed.
+ */
+export declare function startSchedules(handler: ScheduleHandler, server: Server, onFailure: (run: ScheduledRun, failure: string) => void): {
+    stop(): void;
+};
+export {};

package/src/schedules.js

@@ -0,0 +1,200 @@
+/**
+ * Schedules: a game server running by itself, outside rooms and requests, for daily resets, weekly
+ * leaderboards or a persistent world's turns. The game server lists its schedules, each a name and a
+ * cron in UTC, and onSchedule(run, server) runs at each, with server.database. Zaisma runs them in the
+ * game's own object (apps/rooms/src/game-server.ts) and the Node runner with timers (startSchedules),
+ * both from the times here, so a schedule runs at the same minutes in both.
+ *
+ * Crons are the usual five fields, minute hour day-of-month month day-of-week, in UTC: numbers, *,
+ * ranges (1-5), steps (*\/15) and lists (1,15). So a schedule runs at most once a minute.
+ */
+export const SCHEDULE_LIMITS = {
+    maximumScheduleCount: 10,
+    maximumNameCharacterCount: 40,
+    /** How long onSchedule may take, awaiting the database included, before the run fails. */
+    runTimeoutSec: 30,
+};
+const FIELDS = [
+    { name: "minute", minimum: 0, maximum: 59 },
+    { name: "hour", minimum: 0, maximum: 23 },
+    { name: "day of the month", minimum: 1, maximum: 31 },
+    { name: "month", minimum: 1, maximum: 12 },
+    { name: "day of the week", minimum: 0, maximum: 7 },
+];
+const CRON_FIX = 'Give five fields in UTC: minute hour day-of-month month day-of-week, like "0 0 * * *" (every midnight), "*/15 * * * *" (every 15 minutes) or "0 4 * * 1" (Mondays at 04:00).';
+/** Read a cron, or say what's wrong with it. */
+export function readCron(cron) {
+    if (typeof cron !== "string")
+        return { mistake: `cron is ${JSON.stringify(cron) ?? String(cron)}, not text. ${CRON_FIX}` };
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return { mistake: `The cron "${cron}" has ${parts.length} field${parts.length === 1 ? "" : "s"}, not 5 (schedules run at most once a minute, so there's no seconds field). ${CRON_FIX}` };
+    const allowed = [];
+    for (const [index, field] of FIELDS.entries()) {
+        const values = Array(field.maximum + 1).fill(false);
+        for (const part of parts[index].split(",")) {
+            const match = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+            if (!match)
+                return { mistake: `The cron "${cron}" has "${part}" as its ${field.name}. Fields are numbers, *, ranges like 1-5, steps like */15 and lists like 1,15: no names like MON, and no ?, L or #. ${CRON_FIX}` };
+            const stepNumber = match[2] === undefined ? 1 : Number(match[2]);
+            // *, a range, or one number; a number with a step (5/15) runs from there to the field's end.
+            let [fromNumber, toNumber] = [field.minimum, field.maximum];
+            if (match[1].includes("-"))
+                [fromNumber, toNumber] = match[1].split("-").map(Number);
+            else if (match[1] !== "*")
+                [fromNumber, toNumber] = [Number(match[1]), match[2] === undefined ? Number(match[1]) : field.maximum];
+            if (fromNumber < field.minimum || toNumber > field.maximum || fromNumber > toNumber || stepNumber < 1) {
+                return { mistake: `The cron "${cron}" has "${part}" as its ${field.name}, which goes from ${field.minimum} to ${field.maximum}. ${CRON_FIX}` };
+            }
+            for (let allowedNumber = fromNumber; allowedNumber <= toNumber; allowedNumber += stepNumber)
+                values[allowedNumber] = true;
+        }
+        allowed.push(values);
+    }
+    const weekDays = allowed[4];
+    if (weekDays[7])
+        weekDays[0] = true;
+    const cronTimes = { minutes: allowed[0], hours: allowed[1], monthDays: allowed[2], months: allowed[3], weekDays, isEitherDay: parts[2] !== "*" && parts[4] !== "*" };
+    if (nextAtMs(cronTimes, Date.UTC(2000, 0, 1)) === null)
+        return { mistake: `The cron "${cron}" never runs: no month has that day. ${CRON_FIX}` };
+    return { cronTimes };
+}
+/** How far ahead to look for the next run: past every leap day. */
+const SEARCH_DAY_COUNT = 8 * 366;
+const DAY_MS = 86_400_000;
+function nextAtMs(cronTimes, afterMs) {
+    // The first whole minute after afterMs.
+    const firstMs = Math.floor(afterMs / 60_000) * 60_000 + 60_000;
+    const firstDayMs = Math.floor(firstMs / DAY_MS) * DAY_MS;
+    for (let dayIndex = 0; dayIndex < SEARCH_DAY_COUNT; dayIndex++) {
+        const dayMs = firstDayMs + dayIndex * DAY_MS;
+        const date = new Date(dayMs);
+        if (!cronTimes.months[date.getUTCMonth() + 1])
+            continue;
+        const isMonthDay = cronTimes.monthDays[date.getUTCDate()];
+        const isWeekDay = cronTimes.weekDays[date.getUTCDay()];
+        if (cronTimes.isEitherDay ? !(isMonthDay || isWeekDay) : !(isMonthDay && isWeekDay))
+            continue;
+        const fromMinuteIndex = dayIndex === 0 ? (firstMs - dayMs) / 60_000 : 0;
+        for (let minuteIndex = fromMinuteIndex; minuteIndex < 1440; minuteIndex++) {
+            if (cronTimes.hours[Math.floor(minuteIndex / 60)] && cronTimes.minutes[minuteIndex % 60])
+                return dayMs + minuteIndex * 60_000;
+        }
+    }
+    return null;
+}
+/** When a cron next runs after afterMs (epoch milliseconds): a whole minute, UTC. Null for a cron that doesn't read. */
+export function nextRunAtMs(cron, afterMs) {
+    const read = readCron(cron);
+    return "mistake" in read ? null : nextAtMs(read.cronTimes, afterMs);
+}
+/**
+ * A game server's schedules, checked: a list of up to SCHEDULE_LIMITS.maximumScheduleCount
+ * { name, cron }, names different, crons that read. Schedules need onSchedule, and onSchedule needs
+ * schedules. Otherwise what's wrong, and what to do.
+ */
+export function readSchedules(schedules, hasOnSchedule) {
+    const example = 'Give a list like [{ name: "daily-reset", cron: "0 0 * * *" }].';
+    if (schedules === undefined || (Array.isArray(schedules) && schedules.length === 0)) {
+        return hasOnSchedule ? { message: "onSchedule is there but schedules isn't, so it would never run.", fix: `Add schedules, saying when it runs. ${example}` } : { schedules: [] };
+    }
+    if (!Array.isArray(schedules))
+        return { message: `schedules is ${JSON.stringify(schedules)?.slice(0, 80) ?? String(schedules)}, not a list.`, fix: example };
+    if (schedules.length > SCHEDULE_LIMITS.maximumScheduleCount) {
+        return { message: `There are ${schedules.length} schedules; a game server has up to ${SCHEDULE_LIMITS.maximumScheduleCount}.`, fix: "Run more than one job from a schedule: onSchedule can do several things at once." };
+    }
+    const read = [];
+    for (const schedule of schedules) {
+        const { name, cron, ...rest } = (schedule && typeof schedule === "object" && !Array.isArray(schedule) ? schedule : {});
+        if (!schedule || typeof schedule !== "object" || Array.isArray(schedule))
+            return { message: `A schedule is ${JSON.stringify(schedule)?.slice(0, 80)}, not { name, cron }.`, fix: example };
+        const extra = Object.keys(rest)[0];
+        if (extra !== undefined)
+            return { message: `A schedule has ${extra}, which schedules don't take.`, fix: `A schedule is only { name, cron }. ${example}` };
+        if (typeof name !== "string" || !new RegExp(`^[a-z0-9][a-z0-9-]{0,${SCHEDULE_LIMITS.maximumNameCharacterCount - 1}}$`).test(name)) {
+            return { message: `A schedule's name is ${JSON.stringify(name) ?? "missing"}.`, fix: `Name it with lowercase letters, digits and hyphens, up to ${SCHEDULE_LIMITS.maximumNameCharacterCount} characters, like "daily-reset".` };
+        }
+        if (read.some((other) => other.name === name))
+            return { message: `Two schedules are named "${name}".`, fix: "Give each schedule its own name: onSchedule tells them apart by it." };
+        const cronRead = readCron(cron);
+        if ("mistake" in cronRead)
+            return { message: `Schedule "${name}": ${cronRead.mistake.replace(` ${CRON_FIX}`, "")}`, fix: CRON_FIX };
+        read.push({ name, cron: cron.trim().split(/\s+/).join(" ") });
+    }
+    if (!hasOnSchedule)
+        return { message: "schedules is there but onSchedule isn't, so nothing would run.", fix: "Add onSchedule(run, server): run.name says which schedule is due." };
+    return { schedules: read };
+}
+/**
+ * Run a game server's onSchedule for one run, with a time limit. failure says why it failed, for the
+ * game server's errors: it threw, or took longer than SCHEDULE_LIMITS.runTimeoutSec.
+ */
+export async function runSchedule(handler, run, server) {
+    if (typeof handler.onSchedule !== "function")
+        return { failure: "This game server has no onSchedule" };
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(() => handler.onSchedule(run, server)),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`onSchedule ("${run.name}") didn't finish within ${SCHEDULE_LIMITS.runTimeoutSec} seconds`)), SCHEDULE_LIMITS.runTimeoutSec * 1000);
+            }),
+        ]);
+        return { isDone: true };
+    }
+    catch (error) {
+        return { failure: String((error instanceof Error && error.stack) || error) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The longest a timer waits in one go (setTimeout's own limit is about 24.8 days). */
+const MAXIMUM_TIMER_MS = 24 * 3_600_000;
+/**
+ * Run a game server's schedules with timers, as the Node runner does on the developer's own server:
+ * each at the minutes its cron gives, from the moment this starts. onFailure hears about a run that
+ * failed.
+ */
+export function startSchedules(handler, server, onFailure) {
+    const timers = new Set();
+    let isStopped = false;
+    for (const schedule of handler.schedules ?? []) {
+        const plan = (afterMs) => {
+            const atMs = nextRunAtMs(schedule.cron, afterMs);
+            if (atMs === null || isStopped)
+                return;
+            const wait = (timer) => {
+                timers.add(timer);
+                timer.unref?.();
+            };
+            const due = () => {
+                // Long waits go in steps, and the clock is read again after each.
+                if (atMs - Date.now() > 0) {
+                    const timer = setTimeout(() => {
+                        timers.delete(timer);
+                        due();
+                    }, Math.min(atMs - Date.now(), MAXIMUM_TIMER_MS));
+                    return wait(timer);
+                }
+                plan(atMs);
+                // A run gives up after SCHEDULE_LIMITS.runTimeoutSec, so it's over before the next minute.
+                const run = { name: schedule.name, cron: schedule.cron, scheduledAt: new Date(atMs).toISOString() };
+                void runSchedule(handler, run, server).then((outcome) => {
+                    if ("failure" in outcome)
+                        onFailure(run, outcome.failure);
+                });
+            };
+            due();
+        };
+        plan(Date.now());
+    }
+    return {
+        stop() {
+            isStopped = true;
+            for (const timer of timers)
+                clearTimeout(timer);
+            timers.clear();
+        },
+    };
+}

package/src/state-sync.d.ts

@@ -0,0 +1,57 @@
+/**
+ * State sync (docs/DECISIONS.md, "Rooms carry PC-grade real-time games"): a game server with
+ * stateSyncEnabled sends each player their view of the state, a full copy the first time and after that
+ * only what changed, as { type: "state", serverTimeMs, full } and { type: "state", serverTimeMs, changes }.
+ * Each change is [path, value] for a set and [path] for a removal: objects are compared key by key,
+ * arrays index by index while their length stays the same and whole when it changes, everything else by
+ * value. There are no acknowledgements: over a reliable connection a change can't be lost, and a player
+ * whose connection is backed up gets nothing and then a full copy once they've caught up.
+ *
+ * Everything runs where the state lives: in the room on the developer's own server (RoomCore), and in
+ * the game server's sandbox on Zaisma, which loads stateSyncModuleSource(). So it's one function with no
+ * outside references, whose source is copied as it is. The SDK has its own copy of applyStateChanges,
+ * which test/node/state-sync.test.ts holds equal to this one.
+ */
+/** Where in the state a change is: keys of objects and indexes of arrays, from the top. */
+export type StatePath = (string | number)[];
+/** A change to the state: [path, value] sets what's at path, [path] removes it. An empty path replaces the whole state. */
+export type StateChange = [path: StatePath] | [path: StatePath, value: unknown];
+/** One update for some players: a full copy of their view, or the changes since the last one they got. */
+export type StateFrame = {
+    full: unknown;
+} | {
+    changes: StateChange[];
+};
+/** What a round of state sync sends, to whom, and what went wrong (a view that threw or was too big), for the game's errors. */
+export interface StateRound {
+    frames: {
+        playerIds: string[];
+        frame: StateFrame;
+    }[];
+    problems: string[];
+}
+/**
+ * Who sees what, round after round: the last view each viewer was sent, so each round sends only what
+ * changed. A viewer it hasn't sent to, or has forgotten, gets a full copy.
+ */
+export interface StateTracker {
+    /** The viewer gets a full copy next: a new connection, or a backlog they've caught up from. */
+    forget(viewerId: string): void;
+    /**
+     * This round's frames. viewOf answers a viewer's view (stateView), or null when everyone sees the
+     * whole state. Backed-up viewers get nothing and a full copy once they're back; viewers not listed are forgotten.
+     */
+    round(state: unknown, viewerIds: readonly string[], viewOf: ((viewerId: string) => unknown) | null, backedUpViewerIds: ReadonlySet<string>): StateRound;
+}
+/** What changed from previous to next, as changes that applyStateChanges turns previous into next with. */
+export declare const diffState: (previous: unknown, next: unknown) => StateChange[];
+/** The state with the changes applied, as a new state; the one given stays as it was. */
+export declare const applyStateChanges: (state: unknown, changes: readonly StateChange[]) => unknown;
+/** A tracker of what each viewer was last sent, for rounds of state sync; views over maximumViewSizeBytes aren't sent. */
+export declare const newStateTracker: (maximumViewSizeBytes: number) => StateTracker;
+/**
+ * The same parts as an ES module's source, for the game server's sandbox: export default is
+ * { diffState, applyStateChanges, newStateTracker }. A bundler that names functions (esbuild's keepNames)
+ * calls __name inside them, so the module gives it.
+ */
+export declare function stateSyncModuleSource(): string;

package/src/state-sync.js

@@ -0,0 +1,175 @@
+/**
+ * State sync (docs/DECISIONS.md, "Rooms carry PC-grade real-time games"): a game server with
+ * stateSyncEnabled sends each player their view of the state, a full copy the first time and after that
+ * only what changed, as { type: "state", serverTimeMs, full } and { type: "state", serverTimeMs, changes }.
+ * Each change is [path, value] for a set and [path] for a removal: objects are compared key by key,
+ * arrays index by index while their length stays the same and whole when it changes, everything else by
+ * value. There are no acknowledgements: over a reliable connection a change can't be lost, and a player
+ * whose connection is backed up gets nothing and then a full copy once they've caught up.
+ *
+ * Everything runs where the state lives: in the room on the developer's own server (RoomCore), and in
+ * the game server's sandbox on Zaisma, which loads stateSyncModuleSource(). So it's one function with no
+ * outside references, whose source is copied as it is. The SDK has its own copy of applyStateChanges,
+ * which test/node/state-sync.test.ts holds equal to this one.
+ */
+/** The parts, as one function with nothing from outside it, so its source runs the same in the sandbox. */
+function stateSyncParts() {
+    const isPlainObject = (given) => typeof given === "object" && given !== null && !Array.isArray(given);
+    function diffInto(previous, next, path, changes) {
+        if (previous === next)
+            return;
+        if (isPlainObject(previous) && isPlainObject(next)) {
+            for (const key of Object.keys(previous))
+                if (!Object.hasOwn(next, key))
+                    changes.push([[...path, key]]);
+            for (const key of Object.keys(next)) {
+                if (Object.hasOwn(previous, key))
+                    diffInto(previous[key], next[key], [...path, key], changes);
+                else
+                    changes.push([[...path, key], next[key]]);
+            }
+            return;
+        }
+        if (Array.isArray(previous) && Array.isArray(next) && previous.length === next.length) {
+            for (let i = 0; i < next.length; i++)
+                diffInto(previous[i], next[i], [...path, i], changes);
+            return;
+        }
+        changes.push([path, next]);
+    }
+    function diffState(previous, next) {
+        const changes = [];
+        diffInto(previous, next, [], changes);
+        return changes;
+    }
+    /**
+     * The state with the changes applied, as a new state: what changed is copied along its path and the
+     * rest is shared, so the state it was given stays as it was (the SDK keeps earlier ones for smoothing).
+     */
+    function applyStateChanges(state, changes) {
+        // Objects and arrays copied in this call, which its later changes may write to.
+        const copied = new Set();
+        const copyOf = (given) => {
+            if (copied.has(given))
+                return given;
+            const copy = Array.isArray(given) ? given.slice() : { ...given };
+            copied.add(copy);
+            return copy;
+        };
+        let root = state;
+        for (const change of changes) {
+            const path = change[0];
+            if (!path.length) {
+                root = change.length > 1 ? change[1] : null;
+                continue;
+            }
+            root = copyOf(root);
+            let parent = root;
+            for (let i = 0; i < path.length - 1; i++) {
+                const child = copyOf(parent[path[i]]);
+                parent[path[i]] = child;
+                parent = child;
+            }
+            const key = path[path.length - 1];
+            // A key named __proto__ is plain data, as JSON.parse makes it, never the object's prototype.
+            if (change.length > 1)
+                Object.defineProperty(parent, key, { value: change[1], writable: true, enumerable: true, configurable: true });
+            else
+                delete parent[key];
+        }
+        return root;
+    }
+    function utf8SizeBytes(text) {
+        return new TextEncoder().encode(text).length;
+    }
+    function newStateTracker(maximumViewSizeBytes) {
+        // Each viewer's last view as JSON and as a copy; viewers sent the same view share one.
+        const sentViews = new Map();
+        let hasReportedTooBig = false;
+        return {
+            forget(viewerId) {
+                sentViews.delete(viewerId);
+            },
+            round(state, viewerIds, viewOf, backedUpViewerIds) {
+                const listed = new Set(viewerIds);
+                for (const viewerId of [...sentViews.keys()])
+                    if (!listed.has(viewerId))
+                        sentViews.delete(viewerId);
+                const round = { frames: [], problems: [] };
+                // This round's views by their JSON: each is copied, size-checked, sent in full and diffed once, whoever sees it.
+                const views = new Map();
+                let wholeStateText;
+                let hasViewFailed = false;
+                for (const viewerId of viewerIds) {
+                    if (backedUpViewerIds.has(viewerId)) {
+                        sentViews.delete(viewerId);
+                        continue;
+                    }
+                    let text;
+                    try {
+                        text = viewOf ? JSON.stringify(viewOf(viewerId)) : (wholeStateText ??= JSON.stringify(state));
+                    }
+                    catch (error) {
+                        if (!hasViewFailed)
+                            round.problems.push(viewOf ? `stateView failed: ${String(error?.stack || error)}` : `The state isn't plain JSON, so it can't be sent: ${String(error)}`);
+                        hasViewFailed = true;
+                        continue;
+                    }
+                    text ??= "null";
+                    const last = sentViews.get(viewerId);
+                    if (last && last.text === text)
+                        continue;
+                    let seen = views.get(text);
+                    if (!seen) {
+                        const sizeBytes = text.length * 3 > maximumViewSizeBytes ? utf8SizeBytes(text) : text.length;
+                        seen = { sent: sizeBytes > maximumViewSizeBytes ? null : { text, view: JSON.parse(text) }, fullFrame: null, changeFrames: new Map() };
+                        views.set(text, seen);
+                        if (!seen.sent && !hasReportedTooBig) {
+                            hasReportedTooBig = true;
+                            round.problems.push(`A player's view of the state is ${Math.round(sizeBytes / 1024)} KB as JSON, over the ${Math.round(maximumViewSizeBytes / 1024)} KB a player can be sent, so it isn't sent. Cut it to what each player needs with stateView.`);
+                        }
+                    }
+                    if (!seen.sent) {
+                        sentViews.delete(viewerId);
+                        continue;
+                    }
+                    let frame;
+                    if (!last) {
+                        if (!seen.fullFrame)
+                            round.frames.push((seen.fullFrame = { playerIds: [], frame: { full: seen.sent.view } }));
+                        frame = seen.fullFrame;
+                    }
+                    else {
+                        if (!seen.changeFrames.has(last)) {
+                            const changes = diffState(last.view, seen.sent.view);
+                            const made = changes.length ? { playerIds: [], frame: { changes } } : null;
+                            if (made)
+                                round.frames.push(made);
+                            seen.changeFrames.set(last, made);
+                        }
+                        frame = seen.changeFrames.get(last);
+                    }
+                    sentViews.set(viewerId, seen.sent);
+                    frame?.playerIds.push(viewerId);
+                }
+                return round;
+            },
+        };
+    }
+    return { diffState, applyStateChanges, newStateTracker };
+}
+const parts = stateSyncParts();
+/** What changed from previous to next, as changes that applyStateChanges turns previous into next with. */
+export const diffState = parts.diffState;
+/** The state with the changes applied, as a new state; the one given stays as it was. */
+export const applyStateChanges = parts.applyStateChanges;
+/** A tracker of what each viewer was last sent, for rounds of state sync; views over maximumViewSizeBytes aren't sent. */
+export const newStateTracker = parts.newStateTracker;
+/**
+ * The same parts as an ES module's source, for the game server's sandbox: export default is
+ * { diffState, applyStateChanges, newStateTracker }. A bundler that names functions (esbuild's keepNames)
+ * calls __name inside them, so the module gives it.
+ */
+export function stateSyncModuleSource() {
+    return `var __name = (target) => target;\nexport default (${stateSyncParts.toString()})();\n`;
+}

package/src/webhooks.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Webhooks to the game server: a webhook can send Zaisma's events about a game to that game's own
+ * game server, whose onWebhook(event, server) turns them into whatever it likes, like a Discord post
+ * or a GitHub issue made with the developer's own tokens from server.secrets (docs/DECISIONS.md,
+ * "Webhooks to the game server"). Zaisma runs it in the game's own object (apps/rooms/src/game-server.ts)
+ * for a webhook whose destination_kind is game_server. On the developer's own server the Node runner
+ * (@zaisma/game-server/node) takes the same event as a signed POST at /v1/webhooks, checks it here with the
+ * webhook's whsec_ signing secret (Standard Webhooks, standardwebhooks.com) and runs the same
+ * onWebhook, so the code moves unchanged.
+ */
+import type { Server } from "./requests.ts";
+/**
+ * Every kind of event Zaisma sends today. A WebhookEvent's kind is one of these or a kind added later,
+ * so a game server switches on the ones it knows and skips the rest.
+ */
+export type WebhookEventKind = "bug_reported" | "player_reported" | "scan_status_changed" | "live_version_changed" | "review_status_changed" | "country_blocks_changed" | "game_server_error_found" | "alert_raised" | "account_deleted" | "security_alert" | "purchase_completed" | "purchase_refunded" | "test";
+/** Who deleted their Zaisma account, on an account_deleted event. */
+export interface AccountDeletion {
+    /** The player who deleted their Zaisma account. */
+    player_id: string;
+    /** The game's deleted_account_erase_enabled: whether their rows are erased from the game's database (always false about a sign-in app). The Node runner erases them from its local database when it's true. */
+    deleted_account_erase_enabled: boolean;
+}
+/**
+ * What a webhook is sent, as the developer API's get_game, get_version and get_reports answer each
+ * part (snake_case, like all the API's JSON: the one place the game server isn't camelCase). The same
+ * event comes on every try, with the same id. New kinds and fields can be added; none is removed.
+ */
+export interface WebhookEvent {
+    /** A webhook_event_… ID, the same on every try, so a game server can skip one it already handled. */
+    id: string;
+    /** What happened: a WebhookEventKind (security_alert only to your own server, never a game server on Zaisma; test from test_webhook), or a kind added later, to skip. alert_raised covers every alert: switch on alert.kind. */
+    kind: WebhookEventKind | (string & {});
+    /** When Zaisma made the event, an ISO time in UTC. Events can arrive out of order: compare created_at before overwriting newer state. */
+    created_at: string;
+    /** The game as get_game answers it; null for a test event, a security_alert, or an account_deleted event about a sign-in app. */
+    game: Record<string, unknown> | null;
+    /** The version as get_version answers it; null when the event isn't about one. */
+    version: Record<string, unknown> | null;
+    /** The bug report as get_reports lists it; null unless kind is bug_reported. */
+    bug_report: Record<string, unknown> | null;
+    /** The player report as get_reports lists it; null unless kind is player_reported. */
+    player_report: Record<string, unknown> | null;
+    /** The error as get_stats lists it; null unless kind is game_server_error_found. */
+    game_server_error: Record<string, unknown> | null;
+    /** The alert as the game's alerts list it; null unless kind is alert_raised. */
+    alert: Record<string, unknown> | null;
+    /** Who deleted their account and whether their rows are erased; null unless kind is account_deleted. */
+    account_deletion: AccountDeletion | null;
+    /** The sign-in app as list_sign_in_apps answers it; null unless an account_deleted event is about a site, not a game. */
+    sign_in_app: Record<string, unknown> | null;
+    /** The developer's own account event as get_activity lists it; null unless kind is security_alert. */
+    security_event: Record<string, unknown> | null;
+    /** The purchase as get_purchase answers it, with its receipt and game_account_id; null unless kind is purchase_completed or purchase_refunded. */
+    purchase: Record<string, unknown> | null;
+}
+export declare const WEBHOOK_LIMITS: {
+    /** How long onWebhook may take, awaiting the database and outside calls included, before the try fails and waits for the next. */
+    readonly answerTimeoutSec: 10;
+    /** The most of a webhook's POST verifyWebhook and the Node runner take, in bytes: well above any event Zaisma sends. */
+    readonly maximumEventSizeBytes: number;
+    /** How far a POST's webhook-timestamp may be from the server's clock, so an old one can't be sent again. */
+    readonly timestampToleranceDurationSec: 300;
+};
+/** A game server that takes webhooks. */
+export interface WebhookHandler {
+    onWebhook?(event: WebhookEvent, server: Server): unknown;
+}
+/**
+ * Why a webhook POST wasn't trusted (verifyWebhook), or why onWebhook didn't take an event (runWebhook):
+ * - missing_headers: no webhook-id, webhook-timestamp or webhook-signature header.
+ * - too_large: the body is over WEBHOOK_LIMITS.maximumEventSizeBytes.
+ * - old_timestamp: webhook-timestamp isn't within WEBHOOK_LIMITS.timestampToleranceDurationSec of this server's clock.
+ * - bad_signing_secret: the signing secret isn't a whsec_ secret.
+ * - bad_signature: no webhook-signature matches the signing secret.
+ * - not_an_event: the body isn't JSON, or isn't an event with the webhook-id's id.
+ * - no_webhook_handler: the game server has no onWebhook.
+ * - game_server_error: onWebhook threw (message holds the error), or took longer than WEBHOOK_LIMITS.answerTimeoutSec.
+ * New codes can be added.
+ */
+export type WebhookErrorCode = "missing_headers" | "too_large" | "old_timestamp" | "bad_signing_secret" | "bad_signature" | "not_an_event" | "no_webhook_handler" | "game_server_error";
+/** A webhook error, shaped like the developer API's: a code, what happened and what to do. */
+export interface WebhookError {
+    code: WebhookErrorCode;
+    message: string;
+    fix: string;
+}
+/**
+ * Run a game server's onWebhook for one event, with a time limit. An error says why the try failed,
+ * for the game server's errors: it has no onWebhook, it threw, or it took longer than
+ * WEBHOOK_LIMITS.answerTimeoutSec.
+ */
+export declare function runWebhook(handler: WebhookHandler, event: WebhookEvent, server: Server): Promise<{
+    isDone: true;
+} | {
+    error: WebhookError;
+}>;
+/** The Standard Webhooks headers a signed POST comes with. */
+export interface WebhookHeaders {
+    webhookId: string | null;
+    webhookTimestamp: string | null;
+    webhookSignature: string | null;
+}
+/**
+ * Check a webhook POST the Standard Webhooks way: its webhook-signature holds a "v1,<base64>" HMAC-SHA256
+ * of "<webhook-id>.<webhook-timestamp>.<body>" keyed by the signing secret's bytes, and its timestamp is
+ * within WEBHOOK_LIMITS.timestampToleranceDurationSec of now. Answers the event, or an error saying why
+ * it isn't one to trust.
+ */
+export declare function verifyWebhook(signingSecret: string, headers: WebhookHeaders, body: string, nowMs?: number): Promise<{
+    event: WebhookEvent;
+} | {
+    error: WebhookError;
+}>;