@zaisma/game-server 1.25.0 → 1.27.0

package/bin/node-parts.js

@@ -1,6 +1,7 @@
 // The parts of the Node runner (node.js) that stand on their own: where it gets the pass keys and
 // profiles, its local SQLite files, and the checks on its options. Nothing here is part of the
 // public package: tests reach it by path.
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { DATABASE_LIMITS, GameServerError, answerDatabase, checkBatch, checkPlayerId, checkStatement, checkedRow, eraseRefused, eraseStatements, readDatabaseAnswer, tablesFromColumns, tooManyRows, TABLE_COLUMNS_SQL } from "../src/internal.js";
 
@@ -249,9 +250,43 @@ export function localRoomStates(file) {
       console.warn("Saved room states from an older runner were dropped; rooms start fresh.");
     }
     database.exec("CREATE TABLE IF NOT EXISTS room_states (room_code TEXT PRIMARY KEY, format_version INTEGER NOT NULL, state_json TEXT NOT NULL, saved_room_json TEXT NOT NULL, saved_at_ms INTEGER NOT NULL, is_saved_empty INTEGER NOT NULL, is_kept INTEGER NOT NULL)");
+    // A kept room's world back to an earlier moment: copies of its state, and each restore with the state from just before it, for its undo.
+    database.exec("CREATE TABLE IF NOT EXISTS room_state_copies (room_code TEXT NOT NULL, saved_at_ms INTEGER NOT NULL, state_json TEXT NOT NULL, saved_room_json TEXT NOT NULL, PRIMARY KEY (room_code, saved_at_ms))");
+    database.exec("CREATE TABLE IF NOT EXISTS kept_room_restores (id TEXT PRIMARY KEY, room_code TEXT NOT NULL, restore_to_at_ms INTEGER NOT NULL, restored_at_ms INTEGER NOT NULL, undoes_kept_room_restore_id TEXT, undo_state_json TEXT NOT NULL, undo_saved_room_json TEXT NOT NULL, undo_saved_at_ms INTEGER NOT NULL, is_told INTEGER NOT NULL DEFAULT 0)");
     return database;
   };
   const isThere = () => database !== null || (file !== ":memory:" && existsSync(file));
+  /** Keep a copy of a kept room's state: the newest of each minute for a day, of each hour back to 30 days. */
+  const keepCopy = (roomCode, stateJson, savedRoomJson, savedAtMs) => {
+    const minuteMs = savedAtMs - (savedAtMs % 60_000);
+    const opened = open();
+    const isNewMinute = opened.prepare("SELECT 1 FROM room_state_copies WHERE room_code = ? AND saved_at_ms >= ? LIMIT 1").get(roomCode, minuteMs) === undefined;
+    if (!isNewMinute) opened.prepare("DELETE FROM room_state_copies WHERE room_code = ? AND saved_at_ms >= ?").run(roomCode, minuteMs);
+    opened.prepare("INSERT OR REPLACE INTO room_state_copies (room_code, saved_at_ms, state_json, saved_room_json) VALUES (?, ?, ?, ?)").run(roomCode, savedAtMs, stateJson, savedRoomJson);
+    if (!isNewMinute) return;
+    const dayAgoMs = savedAtMs - WORLD_COPY_MINUTES_DURATION_MS;
+    opened.prepare("DELETE FROM room_state_copies WHERE room_code = ?1 AND saved_at_ms < ?2 AND saved_at_ms NOT IN (SELECT MAX(saved_at_ms) FROM room_state_copies WHERE room_code = ?1 AND saved_at_ms < ?2 GROUP BY saved_at_ms / 3600000)").run(roomCode, dayAgoMs);
+    opened.prepare("DELETE FROM room_state_copies WHERE room_code = ? AND saved_at_ms < ?").run(roomCode, savedAtMs - WORLD_COPIES_DURATION_MS);
+  };
+  const restoreJson = (row) => ({
+    id: row.id,
+    roomCode: row.room_code,
+    restoreToAt: new Date(Number(row.restore_to_at_ms)).toISOString(),
+    restoredAt: new Date(Number(row.restored_at_ms)).toISOString(),
+    undoesKeptRoomRestoreId: row.undoes_kept_room_restore_id,
+    undoExpiresAt: new Date(Number(row.restored_at_ms) + WORLD_COPIES_DURATION_MS).toISOString(),
+  });
+  /** Puts a kept room's row back to a state, keeping the state it held, so the restore can be undone. */
+  const restoreTo = (roomCode, to, restoreToAtMs, undoneId, nowMs) => {
+    const opened = open();
+    const current = opened.prepare("SELECT state_json, saved_room_json, saved_at_ms FROM room_states WHERE room_code = ? AND is_kept = 1").get(roomCode);
+    if (!current) return { refusal: "no_kept_room" };
+    const id = `kept_room_restore_${randomUUID().replaceAll("-", "")}`;
+    const record = JSON.parse(to.saved_room_json);
+    opened.prepare("INSERT INTO kept_room_restores (id, room_code, restore_to_at_ms, restored_at_ms, undoes_kept_room_restore_id, undo_state_json, undo_saved_room_json, undo_saved_at_ms) VALUES (?, ?, ?, ?, ?, ?, ?, ?)").run(id, roomCode, restoreToAtMs, nowMs, undoneId, current.state_json, current.saved_room_json, current.saved_at_ms);
+    opened.prepare("UPDATE room_states SET state_json = ?, saved_room_json = ?, saved_at_ms = ?, is_saved_empty = 0 WHERE room_code = ?").run(to.state_json, JSON.stringify(record), to.saved_at_ms, roomCode);
+    return { keptRoomRestore: restoreJson(opened.prepare("SELECT * FROM kept_room_restores WHERE id = ?").get(id)) };
+  };
   return {
     /** A room's saved state, the players in its match and the room, when it was saved and whether it was empty then; null if it has none. */
     read(roomCode) {
@@ -262,6 +297,7 @@ export function localRoomStates(file) {
       return { stateJson: row.state_json, matchPlayers, savedRoom, savedAtMs: Number(row.saved_at_ms), isSavedEmpty: row.is_saved_empty === 1 };
     },
     write(roomCode, { stateJson, matchPlayers, savedRoom, savedAtMs, isSavedEmpty = false }) {
+      if (savedRoom.isKept === true) keepCopy(roomCode, stateJson, JSON.stringify(savedRoomRecord(savedRoom, matchPlayers)), savedAtMs);
       open()
         .prepare("INSERT INTO room_states (room_code, format_version, state_json, saved_room_json, saved_at_ms, is_saved_empty, is_kept) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(room_code) DO UPDATE SET format_version = excluded.format_version, state_json = excluded.state_json, saved_room_json = excluded.saved_room_json, saved_at_ms = excluded.saved_at_ms, is_saved_empty = excluded.is_saved_empty, is_kept = excluded.is_kept")
         .run(roomCode, ROOM_STATES_FORMAT_VERSION_NUMBER, stateJson, JSON.stringify(savedRoomRecord(savedRoom, matchPlayers)), savedAtMs, isSavedEmpty ? 1 : 0, savedRoom.isKept === true ? 1 : 0);
@@ -271,7 +307,44 @@ export function localRoomStates(file) {
       if (isThere()) open().prepare("UPDATE room_states SET saved_room_json = ?, is_kept = ?, is_saved_empty = 1 WHERE room_code = ?").run(JSON.stringify(savedRoomRecord(savedRoom, matchPlayers)), savedRoom.isKept === true ? 1 : 0, roomCode);
     },
     remove(roomCode) {
-      if (isThere()) open().prepare("DELETE FROM room_states WHERE room_code = ?").run(roomCode);
+      if (!isThere()) return;
+      open().prepare("DELETE FROM room_states WHERE room_code = ?").run(roomCode);
+      open().prepare("DELETE FROM room_state_copies WHERE room_code = ?").run(roomCode);
+      open().prepare("DELETE FROM kept_room_restores WHERE room_code = ?").run(roomCode);
+    },
+    /** The earliest moment a kept room can go back to and its restores, newest first, or null when it isn't kept. */
+    keptRoomRestores(roomCode, nowMs = Date.now()) {
+      if (!isThere()) return null;
+      const opened = open();
+      if (opened.prepare("SELECT 1 FROM room_states WHERE room_code = ? AND is_kept = 1").get(roomCode) === undefined) return null;
+      const earliest = opened.prepare("SELECT MIN(saved_at_ms) AS saved_at_ms FROM room_state_copies WHERE room_code = ? AND saved_at_ms >= ?").get(roomCode, nowMs - WORLD_COPIES_DURATION_MS);
+      const restores = opened.prepare("SELECT * FROM kept_room_restores WHERE room_code = ? AND restored_at_ms >= ? ORDER BY restored_at_ms DESC LIMIT 50").all(roomCode, nowMs - WORLD_COPIES_DURATION_MS);
+      return { earliestRestoreToAt: new Date(Number(earliest?.saved_at_ms ?? nowMs)).toISOString(), restores: restores.map(restoreJson) };
+    },
+    /** A kept room back at its newest copy at or before a moment. */
+    restoreKeptRoom(roomCode, restoreToAtMs, nowMs = Date.now()) {
+      if (!isThere()) return { refusal: "no_kept_room" };
+      const listed = this.keptRoomRestores(roomCode, nowMs);
+      if (!listed) return { refusal: "no_kept_room" };
+      const to = open().prepare("SELECT state_json, saved_room_json, saved_at_ms FROM room_state_copies WHERE room_code = ? AND saved_at_ms <= ? ORDER BY saved_at_ms DESC LIMIT 1").get(roomCode, restoreToAtMs);
+      if (!to || restoreToAtMs > nowMs || restoreToAtMs < nowMs - WORLD_COPIES_DURATION_MS) return { refusal: "bad_time", earliestRestoreToAt: listed.earliestRestoreToAt };
+      return restoreTo(roomCode, to, restoreToAtMs, null, nowMs);
+    },
+    /** A kept room back at the state it held just before an earlier restore. */
+    undoKeptRoomRestore(roomCode, keptRoomRestoreId, nowMs = Date.now()) {
+      if (!isThere()) return { refusal: "no_kept_room" };
+      const undone = open().prepare("SELECT * FROM kept_room_restores WHERE id = ? AND room_code = ? AND restored_at_ms >= ?").get(keptRoomRestoreId, roomCode, nowMs - WORLD_COPIES_DURATION_MS);
+      if (!undone) return { refusal: "no_kept_room_restore" };
+      return restoreTo(roomCode, { state_json: undone.undo_state_json, saved_room_json: undone.undo_saved_room_json, saved_at_ms: undone.undo_saved_at_ms }, Number(undone.restored_at_ms), keptRoomRestoreId, nowMs);
+    },
+    /** A restore this room hasn't told its game server yet, once. */
+    takeToldRestore(roomCode) {
+      if (!isThere()) return null;
+      const opened = open();
+      const row = opened.prepare("SELECT id, restore_to_at_ms, restored_at_ms, undoes_kept_room_restore_id FROM kept_room_restores WHERE room_code = ? AND is_told = 0 ORDER BY restored_at_ms DESC LIMIT 1").get(roomCode);
+      if (!row) return null;
+      opened.prepare("UPDATE kept_room_restores SET is_told = 1 WHERE room_code = ?").run(roomCode);
+      return { id: row.id, restoreToAtMs: Number(row.restore_to_at_ms), restoredAtMs: Number(row.restored_at_ms), undoesKeptRoomRestoreId: row.undoes_kept_room_restore_id, erasedPlayerIds: [] };
     },
     /** Delete the states saved before then, except those of rooms still running and kept rooms (room.setKept). */
     removeOlder(beforeMs, runningRoomCodes) {
@@ -289,6 +362,10 @@ export function secretsFromEnvironment() {
   return Object.freeze(Object.fromEntries(Object.entries(process.env).filter(([, environmentValue]) => typeof environmentValue === "string")));
 }
 
+/** How long a kept room's state copies last, and a restore's undo; the first of those keeps a copy a minute, the rest one an hour. */
+const WORLD_COPIES_DURATION_MS = 30 * 86_400_000;
+const WORLD_COPY_MINUTES_DURATION_MS = 86_400_000;
+
 const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile", "zaismaKey", "developerApiUrl", "webtransportPort", "certificatePath", "certificateKeyPath", "identifyPlayer", "outsideGuestsEnabled"];
 
 /**

package/bin/node.js

@@ -304,6 +304,7 @@ export function startServer(options) {
     let room = rooms.get(code);
     if (room) return room;
     const saved = start ? null : readSaved(code);
+    const toldRestore = saved ? (roomStates?.takeToldRestore(code) ?? null) : null;
     const sockets = new Map();
     const core = new RoomCore(
       definition,
@@ -346,7 +347,7 @@ export function startServer(options) {
       },
       // As in Zaisma's rooms: a room that ticks, or a turn-based one that had players in its match, comes back with its state and
       // onRestored, its match's players away until they reconnect; a turn-based room nobody was in comes back with its state and its room settings alone.
-      saved ? { state: saved.state, room: saved.savedRoom, ...(definition.ticksPerSec || saved.matchPlayers?.length ? { restoreInfo: restoreInfoOf(saved.savedAtMs, Date.now(), null, saved.isSavedEmpty), lostPlayers: saved.matchPlayers } : {}) } : { start },
+      saved ? { state: saved.state, room: saved.savedRoom, ...(definition.ticksPerSec || saved.matchPlayers?.length || toldRestore ? { restoreInfo: restoreInfoOf(saved.savedAtMs, Date.now(), null, saved.isSavedEmpty, toldRestore), lostPlayers: saved.matchPlayers } : {}) } : { start },
     );
     if (saved) core.savedAtMs = saved.savedAtMs;
     // passes: each player's checked pass, newest, for the blocks and friendships between them (passesHaveBlockBetween, passesAreFriends);
@@ -408,9 +409,31 @@ export function startServer(options) {
         closeIfEmpty(code, room);
         return { isDone: true };
       },
+      restoreKeptRoom: async (code, restoreToAtMs) => (roomStates ? startOverRestored(code, () => roomStates.restoreKeptRoom(code, restoreToAtMs)) : { refusal: "no_history" }),
+      undoKeptRoomRestore: async (code, keptRoomRestoreId) => (roomStates ? startOverRestored(code, () => roomStates.undoKeptRoomRestore(code, keptRoomRestoreId)) : { refusal: "no_history" }),
+      listKeptRoomRestores: async (code) => roomStates?.keptRoomRestores(code) ?? null,
     };
   }
 
+  /**
+   * A kept room back at an earlier state: what it holds now is saved first, so the undo brings all of it back, then its row changes and the running
+   * room goes. Its players' connections drop, their games reconnect, and the room comes back from its row, with onRestored, as after a restart.
+   */
+  function startOverRestored(code, restore) {
+    const room = rooms.get(code);
+    if (room && !room.core.ended) {
+      room.savedStateKey = null;
+      saveRoom(code, room);
+    }
+    const answer = restore();
+    if (answer.keptRoomRestore && room) {
+      stopTimers(room);
+      rooms.delete(code);
+      for (const ws of room.sockets.values()) ws.terminate();
+    }
+    return answer;
+  }
+
   /** A room here by its code that hasn't ended, or, when isWaking, a kept one asleep in the saved states, woken. */
   function runningRoom(code, isWaking) {
     const running = rooms.get(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_MESSAGE_SENDER_KINDS, 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 ChatAnswer, type ChatInfo, type JoinInfo, type KickOptions, type LiveRoom, 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 RoomMessage, type RoomMessageSenderKind, type RoomPlayer, type RoomSelection, type SendOptions, type VersionUpdate, } from "./room.ts";
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_MESSAGE_SENDER_KINDS, 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 ChatAnswer, type ChatInfo, type JoinInfo, type KickOptions, type LiveRoom, type LeaveInfo, type LeaveReason, type MoveOptions, type MoveResult, type Player, type Purchase, type Refusal, type ReserveOptions, type KeptRoomRestoreInfo, type RestoreInfo, type Room, type RoomErrorCode, type RoomInfo, type RoomMessage, type RoomMessageSenderKind, type RoomPlayer, type RoomSelection, 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";

package/src/requests.d.ts

@@ -12,6 +12,7 @@
 import type { GameDatabase } from "./database.ts";
 import type { ReceiptClaims } from "./pass.ts";
 import type { KickOptions, LiveRoom, Player, RoomPlayer, RoomSelection } from "./room.ts";
+import type { KeptRoomRestore, KeptRoomRestoreList } from "./room-calls.ts";
 /**
  * What onRequest, onSchedule and onWebhook reach besides what they're given: the game's own database, the
  * same one its rooms use, its secrets, receipt checks, and the game's live rooms. Room messages sent from here
@@ -51,6 +52,18 @@ export interface Server {
     endRoom(roomCode: string, message?: string): Promise<{
         isDone: boolean;
     }>;
+    /**
+     * Put a kept room's world back as it was at a moment in the last 30 days (an ISO time). Who may do this is your game's own rule, so
+     * check it first. Players in the room drop for a second or two and reconnect, and its onRestored runs with restoreInfo.keptRoomRestore;
+     * tell them your own way. Called from inside that room, the room starts over, so nothing after the call runs on it.
+     */
+    restoreKeptRoom(roomCode: string, restoreOptions: {
+        restoreToAt: string;
+    }): Promise<KeptRoomRestore>;
+    /** Put a kept room's world back as it was just before an earlier restore, for 30 days after it. */
+    undoKeptRoomRestore(roomCode: string, keptRoomRestoreId: string): Promise<KeptRoomRestore>;
+    /** What a restore screen draws from: the earliest moment the world can go back to, and its restores, newest first. */
+    listKeptRoomRestores(roomCode: string): Promise<KeptRoomRestoreList>;
 }
 export declare const REQUEST_LIMITS: {
     /** A request, as JSON. */

package/src/room-calls.d.ts

@@ -12,7 +12,35 @@ export interface RoomCallLimits {
     maximumRoomMessageSizeBytes: number;
 }
 /** The error a mistake in a room call throws: GameServerError, or the sandbox's copy of it. */
-export type RoomCallErrorClass = new (code: "bad_room_call" | "room_call_unavailable", field: string, message: string, fix: string) => Error;
+export type RoomCallErrorClass = new (code: "bad_room_call" | "room_call_unavailable" | "room_call_limit", field: string, message: string, fix: string) => Error;
+/** A kept room's restore, as server.restoreKeptRoom, undoKeptRoomRestore and listKeptRoomRestores answer it, with ISO times. */
+export interface KeptRoomRestore {
+    id: string;
+    roomCode: string;
+    restoreToAt: string;
+    restoredAt: string;
+    undoesKeptRoomRestoreId: string | null;
+    undoExpiresAt: string;
+}
+/** What server.listKeptRoomRestores answers: the earliest moment the world can go back to, and its restores, newest first. */
+export interface KeptRoomRestoreList {
+    earliestRestoreToAt: string;
+    restores: KeptRoomRestore[];
+}
+/** How a room reach answers a restore: the restore, or why not, which the call throws as an error. */
+export type KeptRoomRestoreAnswer = {
+    keptRoomRestore: KeptRoomRestore;
+    refusal?: undefined;
+    earliestRestoreToAt?: undefined;
+} | {
+    keptRoomRestore?: undefined;
+    refusal: "no_kept_room" | "no_kept_room_restore" | "no_history" | "limited" | "failed";
+    earliestRestoreToAt?: undefined;
+} | {
+    keptRoomRestore?: undefined;
+    refusal: "bad_time";
+    earliestRestoreToAt: string;
+};
 /** A send's delivery as the room acts on it: latest-only, with its latestKey, or reliable. */
 export type CheckedDelivery = {
     isLatestOnly: false;
@@ -67,6 +95,12 @@ export interface RoomCallChecks {
         labels?: Record<string, string>;
     };
     checkEnd(message: unknown): string | undefined;
+    /** server.restoreKeptRoom's options as the moment to go back to, in epoch milliseconds. */
+    checkRestoreToAt(restoreOptions: unknown, call: string): number;
+    checkKeptRoomRestoreId(keptRoomRestoreId: unknown, call: string): string;
+    /** A room reach's answer as the restore, or thrown as the error the game server's code catches. */
+    keptRoomRestoreOf(answer: KeptRoomRestoreAnswer, call: string): KeptRoomRestore;
+    keptRoomRestoreListOf(listed: KeptRoomRestoreList | null, call: string): KeptRoomRestoreList;
     /** room.sendToRoom: another room's code (never this room's) and the message as plain JSON within the size, copied. */
     checkSendToRoom(toRoomCode: unknown, message: unknown, ownRoomCode: string | null, call: string): {
         toRoomCode: string;

package/src/room-calls.js

@@ -177,6 +177,40 @@ function roomCallChecksParts() {
                 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);
         };
+        const checkRestoreToAt = (restoreOptions, call) => {
+            const fix = 'Give { restoreToAt } as an ISO time from the last 30 days, like "2026-10-18T14:05:00Z"; server.listKeptRoomRestores says the earliest.';
+            const { restoreToAt } = closed(restoreOptions, ["restoreToAt"], call);
+            const atMs = typeof restoreToAt === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.test(restoreToAt) ? Date.parse(restoreToAt) : NaN;
+            if (!Number.isFinite(atMs))
+                throw mistake(call, call + " needs restoreToAt as an ISO time.", fix);
+            return atMs;
+        };
+        const checkKeptRoomRestoreId = (keptRoomRestoreId, call) => {
+            if (typeof keptRoomRestoreId !== "string" || !keptRoomRestoreId)
+                throw mistake(call, call + " needs a restore's ID.", "Give an id from server.listKeptRoomRestores.");
+            return keptRoomRestoreId;
+        };
+        const noKeptRoom = (call) => mistake(call, call + " needs a kept room of this game that isn't deleted.", "Give the code of a kept room: its game server calls room.setKept(true).");
+        const keptRoomRestoreOf = (answer, call) => {
+            if (answer.keptRoomRestore)
+                return answer.keptRoomRestore;
+            if (answer.refusal === "bad_time")
+                throw mistake(call, call + "'s restoreToAt isn't a moment this world can go back to.", "Give a time from " + answer.earliestRestoreToAt + " to now.");
+            if (answer.refusal === "no_kept_room")
+                throw noKeptRoom(call);
+            if (answer.refusal === "no_kept_room_restore")
+                throw mistake(call, call + " needs a restore of this world from the last 30 days.", "Give an id from server.listKeptRoomRestores.");
+            if (answer.refusal === "limited")
+                throw new ErrorClass("room_call_limit", call, "A world can go back up to 5 times a minute.", "Wait a minute, then try again.");
+            if (answer.refusal === "no_history")
+                throw new ErrorClass("room_call_unavailable", call, call + " isn't available here: these rooms keep no history.", "On Zaisma, and on the Node runner with --room-state-file, it works.");
+            throw new ErrorClass("room_call_unavailable", call, "The world didn't answer, so nothing changed.", "Try again in a moment.");
+        };
+        const keptRoomRestoreListOf = (listed, call) => {
+            if (!listed)
+                throw noKeptRoom(call);
+            return listed;
+        };
         const readRoomMessage = (message, call) => {
             if (message === undefined || message === null)
                 throw mistake(call, `${call} needs a message.`, "Give the message as plain JSON, like { kind: \"blood_moon\" }.");
@@ -207,7 +241,7 @@ function roomCallChecksParts() {
             return { toRoomCode, message: readRoomMessage(message, call) };
         };
         const checkSendToEveryRoom = (message, roomSelection, call) => ({ message: readRoomMessage(message, call), ...checkRoomSelection(roomSelection, call) });
-        return { checkBroadcast, checkSend, checkBroadcastBytes, checkSendBytes, checkKick, checkReserve, checkMoveTo, checkSetInfo, checkEnd, checkSendToRoom, checkSendToEveryRoom, checkRoomSelection, tidy, tidyRoomInfo, checkRoomData };
+        return { checkBroadcast, checkSend, checkBroadcastBytes, checkSendBytes, checkKick, checkReserve, checkMoveTo, checkSetInfo, checkEnd, checkRestoreToAt, checkKeptRoomRestoreId, keptRoomRestoreOf, keptRoomRestoreListOf, checkSendToRoom, checkSendToEveryRoom, checkRoomSelection, tidy, tidyRoomInfo, checkRoomData };
     }
     return { checksFor };
 }

package/src/room.d.ts

@@ -688,6 +688,8 @@ export interface RoomReach {
     }>;
 }
 /** What the game server reaches outside rooms besides RoomReach (server.getRoom, kickFromRoom, endRoom), its calls already checked. */
+export type { KeptRoomRestore, KeptRoomRestoreAnswer, KeptRoomRestoreList } from "./room-calls.ts";
+import type { KeptRoomRestoreAnswer, KeptRoomRestoreList } from "./room-calls.ts";
 export interface ServerRoomReach extends RoomReach {
     getRoom(roomCode: string): Promise<{
         room: LiveRoom;
@@ -699,6 +701,9 @@ export interface ServerRoomReach extends RoomReach {
     endRoom(roomCode: string, message: string | undefined): Promise<{
         isDone: boolean;
     }>;
+    restoreKeptRoom(roomCode: string, restoreToAtMs: number): Promise<KeptRoomRestoreAnswer>;
+    undoKeptRoomRestore(roomCode: string, keptRoomRestoreId: string): Promise<KeptRoomRestoreAnswer>;
+    listKeptRoomRestores(roomCode: string): Promise<KeptRoomRestoreList | null>;
 }
 /**
  * What onRestored hears: when the state it came back with was saved (an ISO time), how many seconds of
@@ -709,13 +714,34 @@ export interface RestoreInfo {
     savedAt: string;
     lostDurationSec: number;
     savedVersionId: string | null;
+    /** The developer's restore that put this kept room's world back at an earlier moment, or null for any other restart. Tell your players your own way. */
+    keptRoomRestore: KeptRoomRestoreInfo | null;
+}
+/**
+ * What a kept room's onRestored hears when its world went back to an earlier moment (server.restoreKeptRoom, the API): the
+ * restore's ID, the moment, when it happened and the restore it undid, if any, with ISO times. erasedPlayerIds are players
+ * erased since the moment: the world's state came back with them in it, so drop them from it here.
+ */
+export interface KeptRoomRestoreInfo {
+    /** The restore's ID, for server.undoKeptRoomRestore; null for a deleted world brought back from its last copy, which has no undo. */
+    id: string | null;
+    restoreToAt: string;
+    restoredAt: string;
+    undoesKeptRoomRestoreId: string | null;
+    erasedPlayerIds: string[];
 }
 /**
  * A restored room's restoreInfo, from when its state was saved and the version that saved it. A state
  * saved as the room emptied (isSavedEmpty) lost nothing, however long ago: a kept world waking after a week
  * reads savedAt for the time that passed.
  */
-export declare function restoreInfoOf(savedAtMs: number, nowMs?: number, savedVersionId?: string | null, isSavedEmpty?: boolean): RestoreInfo;
+export declare function restoreInfoOf(savedAtMs: number, nowMs?: number, savedVersionId?: string | null, isSavedEmpty?: boolean, toldRestore?: {
+    id: string | null;
+    restoreToAtMs: number;
+    restoredAtMs: number;
+    undoesKeptRoomRestoreId: string | null;
+    erasedPlayerIds: string[];
+} | null): RestoreInfo;
 /**
  * What canJoin answers: true lets the player in; false turns them away; { refusalMessage } turns them
  * away with that message. Answering nothing turns them away too, and is logged as a mistake.

package/src/room.js

@@ -40,8 +40,19 @@ export const ROOM_MESSAGE_LIMITS = {
  * saved as the room emptied (isSavedEmpty) lost nothing, however long ago: a kept world waking after a week
  * reads savedAt for the time that passed.
  */
-export function restoreInfoOf(savedAtMs, nowMs = Date.now(), savedVersionId = null, isSavedEmpty = false) {
-    return { savedAt: new Date(savedAtMs).toISOString(), lostDurationSec: isSavedEmpty ? 0 : Math.max(0, Math.round((nowMs - savedAtMs) / 1000)), savedVersionId };
+export function restoreInfoOf(savedAtMs, nowMs = Date.now(), savedVersionId = null, isSavedEmpty = false, toldRestore = null) {
+    return {
+        savedAt: new Date(savedAtMs).toISOString(),
+        lostDurationSec: isSavedEmpty ? 0 : Math.max(0, Math.round((nowMs - savedAtMs) / 1000)),
+        savedVersionId,
+        keptRoomRestore: toldRestore && {
+            id: toldRestore.id,
+            restoreToAt: new Date(toldRestore.restoreToAtMs).toISOString(),
+            restoredAt: new Date(toldRestore.restoredAtMs).toISOString(),
+            undoesKeptRoomRestoreId: toldRestore.undoesKeptRoomRestoreId,
+            erasedPlayerIds: toldRestore.erasedPlayerIds,
+        },
+    };
 }
 /** What the sender hears when the game server's onChat stopped their message. */
 export const STOPPED_BY_GAME_MESSAGE = "Your message wasn't sent.";
@@ -388,6 +399,21 @@ export function newServer(serverParts, roomReach) {
             const reach = reachFor("server.endRoom");
             return reach.endRoom(roomCodeOf(roomCode, "server.endRoom"), checks.checkEnd(message));
         },
+        restoreKeptRoom: async (roomCode, restoreOptions) => {
+            const call = "server.restoreKeptRoom";
+            const reach = reachFor(call);
+            return checks.keptRoomRestoreOf(await reach.restoreKeptRoom(roomCodeOf(roomCode, call), checks.checkRestoreToAt(restoreOptions, call)), call);
+        },
+        undoKeptRoomRestore: async (roomCode, keptRoomRestoreId) => {
+            const call = "server.undoKeptRoomRestore";
+            const reach = reachFor(call);
+            return checks.keptRoomRestoreOf(await reach.undoKeptRoomRestore(roomCodeOf(roomCode, call), checks.checkKeptRoomRestoreId(keptRoomRestoreId, call)), call);
+        },
+        listKeptRoomRestores: async (roomCode) => {
+            const call = "server.listKeptRoomRestores";
+            const listed = await reachFor(call).listKeptRoomRestores(roomCodeOf(roomCode, call));
+            return checks.keptRoomRestoreListOf(listed, call);
+        },
     };
 }
 /** room.secrets and server.secrets where a game has none. */