@arcadible/sdk 1.1.0 → 1.2.0

package/README.md

@@ -19,7 +19,7 @@
 
 <br>
 
-Each version of a game on [Arcadible](https://arcadible.com) has its own origin, so its browser storage starts empty with every update. Saves made through the Arcadible SDK are kept by the play page instead, on the player's device, so they carry over. The SDK is optional, and saves are all it does.
+Each build of a game on [Arcadible](https://arcadible.com) has its own origin, so its browser storage starts empty with every update. Saves made through the Arcadible SDK are kept by the play page instead, on the player's device, so they carry over. The SDK is optional, and saves are all it does.
 
 ## Install
 
@@ -27,7 +27,7 @@ Each version of a game on [Arcadible](https://arcadible.com) has its own origin,
 npm install @arcadible/sdk
 ```
 
-For a game with a build step, such as a Vite project. A game without one includes the hosted script instead, served on Arcadible from every game's own origin:
+Use the package in a game with a build step, such as a Vite project. A game without one includes the hosted script instead, which Arcadible serves from every build's own origin, as `arc serve` does locally:
 
 ```html
 <script src="/arcadible/sdk/v1.js"></script>
@@ -46,9 +46,9 @@ const progress = saved ? JSON.parse(saved) : { level: 1 };
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-A save is a name holding one string. `ready` settles once the game's saves have loaded, and never fails; from then on, `readSync` answers from memory. Every call that fails rejects (or, for `readSync`, throws) with an `ArcadibleError`, whose `code` says what to do.
+A save is a name holding one string. `ready` settles once the game's saves have loaded, and never fails; from then on, `readSync`, `listSync`, and `infoSync` answer from memory. Every call that fails rejects (or, for the sync calls, throws) with an `ArcadibleError`, whose `code` says what to do. `arcadible.saves.where` says who can read the saves back: every version of the game, only this build, or only until the page closes.
 
-Off Arcadible, such as on your dev server, the package works on its own, with the same rules and limits: saves are kept on the page's own origin, and `arcadible.build` is `null`.
+Off Arcadible, such as on your dev server, the package works on its own, with the same rules and limits: saves are kept on the page's own origin, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
 ## Learn more
 

package/dist/bus/client.d.ts

@@ -1,4 +1,4 @@
-import { type Welcome } from "./protocol.js";
+import { type Shape, type Welcome } from "./protocol.js";
 import type { Server } from "./server.js";
 export type BusOptions = {
     client: string;
@@ -8,9 +8,13 @@ export type BusOptions = {
     requestTimeout?: number | undefined;
     standalone: () => Server;
 };
+export type RequestOptions<T> = {
+    late?: (result: T) => void;
+};
 export type Bus = {
     readonly welcomed: Promise<Welcome>;
-    request(name: string, params?: object): Promise<unknown>;
-    on(name: string, listener: (data: unknown) => void): () => void;
+    request<T>(name: string, params: object | undefined, shape: Shape<T>, options?: RequestOptions<T>): Promise<T>;
+    on<T>(name: string, shape: Shape<T>, listener: (data: T) => void): () => void;
 };
+export declare function mayHaveLanded(err: unknown): boolean;
 export declare function openBus(options: BusOptions): Bus;

package/dist/bus/client.js

@@ -1,8 +1,28 @@
 // The game's end of the bus: it says hello to the play page, and stands
 // alone when no page answers, running the page's end itself, in its own
-// page, so the rules are the same.
+// page, so the rules are the same. It takes nothing the page sends on trust:
+// every call settles, with what its request expects or a code.
 // [import]
-import { ArcadibleError, BUS_VERSION, Codes, HANDSHAKE_TIMEOUT, isHostOrigin, isMessage, isWelcome, REQUEST_TIMEOUT, } from "./protocol.js";
+import { ArcadibleError, BUS_VERSION, Codes, HANDSHAKE_TIMEOUT, isErrorBody, isHostOrigin, isMessage, isWelcome, log, REQUEST_TIMEOUT, } from "./protocol.js";
+// [declare]
+// How many calls that timed out keep waiting for a late answer; past it,
+// the oldest stop.
+const MAX_LATE = 64;
+// failures after which the page may still have done what was asked: a
+// `timeout`, or an answer the game couldn't read.
+const uncertain = new WeakSet();
+// [function]
+// Whether the page may have done what a failed call asked, so a game's
+// memory copy keeps what it showed.
+export function mayHaveLanded(err) {
+    return err instanceof ArcadibleError && uncertain.has(err);
+}
+// [function]
+function unsure(code, message) {
+    const err = new ArcadibleError(code, message);
+    uncertain.add(err);
+    return err;
+}
 // [function]
 export function openBus(options) {
     const win = options.window ?? (typeof window === "undefined" ? undefined : window);
@@ -13,6 +33,7 @@ export function openBus(options) {
     let nextId = 1;
     let handshakeTimer;
     const pending = new Map();
+    const late = new Map();
     const listeners = new Map();
     let welcome = () => undefined;
     const welcomed = new Promise((resolve) => {
@@ -23,22 +44,62 @@ export function openBus(options) {
         const message = event.data;
         if (!isMessage(message))
             return;
-        handle(message);
+        try {
+            handle(message);
+        }
+        catch (err) {
+            log("error", "a message from the play page failed.", err);
+        }
+    };
+    // [function]
+    // a call's answer: settled before anything else is read, so whatever the
+    // page sent, the call ends.
+    const settle = function (call, message) {
+        const error = message["error"];
+        if (error !== undefined) {
+            if (!isErrorBody(error)) {
+                call.reject(unsure(Codes.Unavailable, "The play page's answer was malformed."));
+                return;
+            }
+            const text = error.message;
+            call.reject(new ArcadibleError(error.code, typeof text === "string" ? text : "That failed. Try again."));
+        }
+        else if (call.shape(message["result"])) {
+            call.resolve(message["result"]);
+        }
+        else {
+            call.reject(unsure(Codes.Unavailable, "The play page's answer was malformed."));
+        }
+    };
+    // [function]
+    const answerLate = function (id, message) {
+        const call = late.get(id);
+        if (!call)
+            return;
+        late.delete(id);
+        const result = message["result"];
+        if (message["error"] === undefined && call.shape(result)) {
+            call.late(result);
+        }
     };
     // [function]
     const handle = function (message) {
         if (message.kind === "response") {
             const call = pending.get(message.id);
-            if (!call)
+            if (!call) {
+                answerLate(message.id, message);
                 return;
+            }
             pending.delete(message.id);
             clearTimeout(call.timer);
-            if ("error" in message) {
-                const { code, message: text } = message.error;
-                call.reject(new ArcadibleError(code, text));
+            try {
+                settle(call, message);
             }
-            else {
-                call.resolve(message.result);
+            catch (err) {
+                // `settle` rejects before it could throw; this only keeps a call
+                // from hanging if that ever changes.
+                call.reject(unsure(Codes.Unavailable, "The play page's answer was malformed."));
+                log("error", `${call.name}'s answer couldn't be read.`, err);
             }
         }
         else if (message.kind === "event") {
@@ -71,6 +132,9 @@ export function openBus(options) {
             return;
         state = "standalone";
         win?.removeEventListener("message", onWindowMessage);
+        if (win && win.parent !== win) {
+            log("warn", 'no play page answered within a second, so this game keeps its saves on its own origin, where only this build reads them (saves.where is "build"); reloading usually fixes it.');
+        }
         const channel = new MessageChannel();
         attach(channel.port1, options.standalone().connect(channel.port2));
     };
@@ -101,7 +165,7 @@ export function openBus(options) {
     }
     return {
         welcomed,
-        async request(name, params) {
+        async request(name, params, shape, requestOptions = {}) {
             await welcomed;
             // welcomed, so there's a channel: the play page's, or this page's own.
             const link = port;
@@ -111,22 +175,50 @@ export function openBus(options) {
             const id = nextId++;
             return new Promise((resolve, reject) => {
                 const timer = setTimeout(() => {
+                    const call = pending.get(id);
                     pending.delete(id);
-                    reject(new ArcadibleError(Codes.Timeout, `${name} timed out.`));
+                    if (call?.late) {
+                        late.set(id, { shape: call.shape, late: call.late });
+                        if (late.size > MAX_LATE) {
+                            late.delete(late.keys().next().value);
+                        }
+                    }
+                    reject(unsure(Codes.Timeout, "The play page took too long to answer. Try again."));
                 }, requestTimeout);
-                pending.set(id, { resolve, reject, timer });
+                pending.set(id, {
+                    name,
+                    resolve: resolve,
+                    reject,
+                    timer,
+                    shape,
+                    late: requestOptions.late,
+                });
                 link.postMessage({ kind: "request", id, name, params });
             });
         },
-        on(name, listener) {
+        on(name, shape, listener) {
+            // each listener on its own: one that throws, or data it can't take,
+            // doesn't stop the others.
+            const checked = function (data) {
+                if (!shape(data)) {
+                    log("warn", `ignored a malformed ${name} from the play page.`);
+                    return;
+                }
+                try {
+                    listener(data);
+                }
+                catch (err) {
+                    log("error", `a ${name} listener failed.`, err);
+                }
+            };
             let set = listeners.get(name);
             if (!set) {
                 set = new Set();
                 listeners.set(name, set);
             }
-            set.add(listener);
+            set.add(checked);
             return () => {
-                set.delete(listener);
+                set.delete(checked);
             };
         },
     };

package/dist/bus/protocol.d.ts

@@ -16,6 +16,12 @@ export declare const Codes: {
     readonly Unsupported: "unsupported";
 };
 export type Code = (typeof Codes)[keyof typeof Codes];
+/**
+ * The build that's running, from the page's own lookup: its version, from
+ * `arcadible.toml` or `package.json`, and its channel (`production`,
+ * `staging`, or `local` under `arc serve`). `null` standing alone, or when
+ * the page doesn't say.
+ */
 export type Build = {
     version: string;
     channel: string;
@@ -30,6 +36,7 @@ export type Welcome = {
     v: number;
     build: Build | null;
 };
+export type Shape<T> = (value: unknown) => value is T;
 export type ErrorBody = {
     code: string;
     message: string;
@@ -55,13 +62,24 @@ type BusEvent = {
     data?: unknown;
 };
 export type Message = Request | Response | BusEvent;
+/** A failed call. Match on `code`; the message is for people. */
 export declare class ArcadibleError extends Error {
     readonly code: Code;
     constructor(code: Code, message: string);
     toJSON(): ErrorBody;
 }
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isString(value: unknown): value is string;
+export declare function isNumber(value: unknown): value is number;
+export declare function isStringOrNull(value: unknown): value is string | null;
+export declare function isStringArray(value: unknown): value is string[];
+export declare function isErrorBody(value: unknown): value is {
+    code: string;
+};
+export declare function log(level: "warn" | "error", sentence: string, ...detail: unknown[]): void;
 export declare function isHello(value: unknown): value is Hello;
 export declare function isWelcome(value: unknown): value is Welcome;
+export declare function buildOf(value: unknown): Build | null;
 export declare function isMessage(value: unknown): value is Message;
 export declare function utf8Size(text: string): number;
 export declare function messageSize(value: unknown, limit?: number): number;

package/dist/bus/protocol.js

@@ -26,8 +26,10 @@ export function isHostOrigin(origin, origins) {
 // The most requests one game can have waiting on the page; past it, a
 // request fails with `busy`.
 export const MAX_IN_FLIGHT = 64;
-// One message, checked by the side that receives it: room for a whole 1 MB
-// save, and the rest of the message.
+// The largest message either side sends: room for a whole 1 MB save, or
+// every save at once (a game's are 1 MB together), and the rest of the
+// message. The page refuses a larger request, and never sends a larger
+// answer or event (DESIGN.md, section 4).
 export const MAX_MESSAGE = 1024 * 1024 + 64 * 1024;
 // [declare]
 // Every code a call can fail with. Worth retrying: `busy`, `timeout`, and
@@ -46,7 +48,7 @@ export const Codes = {
     Unsupported: "unsupported",
 };
 // [class]
-// A failed call. Match on `code`; the message is for people.
+/** A failed call. Match on `code`; the message is for people. */
 export class ArcadibleError extends Error {
     // [field]
     code;
@@ -62,10 +64,38 @@ export class ArcadibleError extends Error {
     }
 }
 // [function]
-function isObject(value) {
+export function isObject(value) {
     return typeof value === "object" && value !== null;
 }
 // [function]
+export function isString(value) {
+    return typeof value === "string";
+}
+// [function]
+export function isNumber(value) {
+    return typeof value === "number";
+}
+// [function]
+export function isStringOrNull(value) {
+    return value === null || typeof value === "string";
+}
+// [function]
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every(isString);
+}
+// [function]
+// What an error is sent as: a string `code`, and a message for people.
+export function isErrorBody(value) {
+    return isObject(value) && typeof value["code"] === "string";
+}
+// [function]
+// The SDK's console line: one sentence after its name, so a developer can
+// tell it from the game's own. `warn` for a degraded state, and `error`
+// only for a bug.
+export function log(level, sentence, ...detail) {
+    console[level](`Arcadible SDK: ${sentence}`, ...detail);
+}
+// [function]
 export function isHello(value) {
     return (isObject(value) &&
         value["arcadible"] === "hello" &&
@@ -79,6 +109,17 @@ export function isWelcome(value) {
         value["v"] === BUS_VERSION);
 }
 // [function]
+// The welcome's build as a game sees it: a copy of just its version and
+// channel, so a page can't add fields games come to depend on, or `null`
+// when the page doesn't say, or says it wrong.
+export function buildOf(value) {
+    return isObject(value) &&
+        typeof value["version"] === "string" &&
+        typeof value["channel"] === "string"
+        ? { version: value["version"], channel: value["channel"] }
+        : null;
+}
+// [function]
 export function isMessage(value) {
     if (!isObject(value))
         return false;

package/dist/bus/server.d.ts

@@ -2,7 +2,8 @@ import { type Build, type Welcome } from "./protocol.js";
 export type Params = Record<string, unknown>;
 export type Handler = {
     run(params: Params): Promise<unknown>;
-    coalesce?(params: Params): string;
+    key?(params: Params): string;
+    coalesce?: boolean;
 };
 export type ModuleContext = {
     broadcast(name: string, data: unknown): void;

package/dist/bus/server.js

@@ -1,13 +1,14 @@
 // The page's end of the bus: it answers a game's requests with its modules'
 // handlers, one at a time in order, and refuses what's too large, too many,
-// or unknown. `answerHellos` connects it to the play page's iframe.
+// or unknown. It never sends more than `MAX_MESSAGE` either. `answerHellos`
+// connects it to the play page's iframe.
 // [import]
-import { ArcadibleError, BUS_VERSION, Codes, isHello, isMessage, MAX_IN_FLIGHT, MAX_MESSAGE, messageSize, } from "./protocol.js";
+import { ArcadibleError, BUS_VERSION, Codes, isHello, isMessage, log, MAX_IN_FLIGHT, MAX_MESSAGE, messageSize, } from "./protocol.js";
 // [function]
 function errorBody(err) {
     if (err instanceof ArcadibleError)
         return err.toJSON();
-    console.error("arcadible: a request failed:", err);
+    log("error", "a request failed.", err);
     return {
         code: Codes.Unavailable,
         message: "That's unavailable right now. Try again.",
@@ -23,7 +24,7 @@ function paramsOf(value) {
 export function createServer(options) {
     const ports = new Set();
     const inFlight = new Map();
-    // requests waiting their turn, by name and coalescing key.
+    // the newest request waiting its turn, by key.
     const waiting = new Map();
     let queue = Promise.resolve();
     const enqueue = function (job) {
@@ -31,9 +32,20 @@ export function createServer(options) {
         queue = run.catch(() => undefined);
         return run;
     };
+    // nothing goes to a game that's larger than a request may be: the limits
+    // keep every answer and event within it, so one that isn't is a bug.
+    const fits = function (message, what) {
+        if (messageSize(message, MAX_MESSAGE) <= MAX_MESSAGE)
+            return true;
+        log("error", `${what} was too large to send.`);
+        return false;
+    };
     const send = function (port, name, data) {
-        if (ports.has(port))
-            port.postMessage({ kind: "event", name, data });
+        if (!ports.has(port))
+            return;
+        const message = { kind: "event", name, data };
+        if (fits(message, name))
+            port.postMessage(message);
     };
     const modules = options.modules.map((make) => make({
         broadcast(name, data) {
@@ -50,10 +62,23 @@ export function createServer(options) {
     const refuse = function (port, id, error) {
         port.postMessage({ kind: "response", id, error });
     };
-    const respond = function (port, id, outcome) {
-        inFlight.set(port, (inFlight.get(port) ?? 1) - 1);
-        if (ports.has(port))
-            port.postMessage({ kind: "response", id, ...outcome });
+    // answers each request in `entry`, which counted once toward the limit.
+    const respond = function ({ ids, name, port }, outcome) {
+        const count = inFlight.get(port);
+        if (count !== undefined)
+            inFlight.set(port, count - 1);
+        if (!ports.has(port))
+            return;
+        const fitting = "result" in outcome && !fits(outcome, `${name}'s answer`)
+            ? {
+                error: {
+                    code: Codes.Unavailable,
+                    message: "That's unavailable right now. Try again.",
+                },
+            }
+            : outcome;
+        for (const id of ids)
+            port.postMessage({ kind: "response", id, ...fitting });
     };
     const answer = function (port, request) {
         const { id, name } = request;
@@ -65,35 +90,33 @@ export function createServer(options) {
             });
             return;
         }
+        const params = paramsOf(request.params);
+        const key = handler.key?.(params) ?? null;
+        const pending = key === null ? undefined : waiting.get(key);
+        if (handler.coalesce &&
+            pending &&
+            pending.name === name &&
+            pending.port === port) {
+            pending.params = params;
+            pending.ids.push(id);
+            return;
+        }
         if ((inFlight.get(port) ?? 0) >= MAX_IN_FLIGHT) {
             refuse(port, id, {
                 code: Codes.Busy,
-                message: "Too many requests at once. Wait for some to finish.",
+                message: "Too many calls at once. Wait for some to finish.",
             });
             return;
         }
         inFlight.set(port, (inFlight.get(port) ?? 0) + 1);
-        const params = paramsOf(request.params);
-        const key = handler.coalesce
-            ? `${name}\u0000${handler.coalesce(params)}`
-            : null;
-        const pending = key === null ? undefined : waiting.get(key);
-        if (pending) {
-            pending.params = params;
-            pending.ids.push(id);
-            return;
-        }
-        const entry = { params, ids: [id] };
+        const entry = { name, port, params, ids: [id] };
         if (key !== null)
             waiting.set(key, entry);
         enqueue(() => {
-            if (key !== null)
+            if (key !== null && waiting.get(key) === entry)
                 waiting.delete(key);
             return handler.run(entry.params);
-        }).then((result) => entry.ids.forEach((i) => respond(port, i, { result })), (err) => {
-            const error = errorBody(err);
-            entry.ids.forEach((i) => respond(port, i, { error }));
-        });
+        }).then((result) => respond(entry, { result }), (err) => respond(entry, { error: errorBody(err) }));
     };
     const receive = function (port, data) {
         if (!isMessage(data) || data.kind !== "request")

package/dist/client.d.ts

@@ -4,10 +4,24 @@ import { type Saves } from "./saves/client.js";
 export type Ready = {
     build: Build | null;
 };
+/** The `arcadible` object a game calls. */
 export interface Arcadible {
+    /** The SDK's own version. */
     readonly version: string;
+    /**
+     * Settles once the game's saves have loaded, or after 10 seconds if they
+     * haven't, and never fails. It resolves with `build`; each module's own
+     * facts are on the module, such as `saves.where`.
+     */
     readonly ready: Promise<Ready>;
+    /**
+     * The build that's running, its version and channel, once `ready` has
+     * settled: compare a save's `info().version` with it, so as not to
+     * overwrite a save from a newer version. `null` when nobody says, such as
+     * standing alone, and `undefined` before.
+     */
     readonly build: Build | null | undefined;
+    /** Saves that carry over between the game's versions. */
     readonly saves: Saves;
 }
 export type ClientOptions = {

package/dist/client.js

@@ -3,14 +3,20 @@
 // same rules in its own page, when no page answers.
 // [import]
 import { openBus } from "./bus/client.js";
-import { REQUEST_TIMEOUT } from "./bus/protocol.js";
+import { buildOf, REQUEST_TIMEOUT } from "./bus/protocol.js";
 import { indexedDBBackend } from "./saves/backend/indexeddb.js";
 import { createSaves } from "./saves/client.js";
 import { serve } from "./host.js";
 import { VERSION } from "./version.js";
-// The scope a game standing alone keeps its saves under, on its own origin.
-// Standing alone there's no version to stamp: saves say `null`.
-const STANDALONE = { game: "standalone", channel: "local", version: null };
+// The scope a game standing alone keeps its saves under, on its own origin,
+// where only this build reads them. Standing alone there's no version to
+// stamp: saves say `null`.
+const STANDALONE = {
+    game: "standalone",
+    channel: "local",
+    version: null,
+    where: "build",
+};
 // [function]
 export function createClient(options = {}) {
     const backend = options.backend ?? (() => indexedDBBackend());
@@ -28,7 +34,7 @@ export function createClient(options = {}) {
     let settled = null;
     // ready once welcomed, and each module's first messages have arrived.
     const ready = Promise.all([bus.welcomed, opened]).then(([welcome]) => {
-        settled = { build: welcome.build ?? null };
+        settled = { build: buildOf(welcome.build) };
         return settled;
     });
     return {

package/dist/host.d.ts

@@ -1,10 +1,12 @@
 import { type Server } from "./bus/server.js";
 import type { Backend } from "./saves/backend/types.js";
+import type { Where } from "./saves/rules.js";
 export type ServeOptions = {
     game: string;
     channel: string;
     version: string | null;
     backend: Backend;
+    where?: Where;
     now?: () => Date;
 };
 type HostOptions = ServeOptions & {

package/dist/host.js

@@ -15,6 +15,7 @@ export function serve(options) {
                 now: options.now ?? (() => new Date()),
                 scope: { game, channel },
                 version,
+                where: options.where ?? "game",
             }),
         ],
     });

package/dist/saves/backend/indexeddb.d.ts

@@ -3,7 +3,6 @@ export type IndexedDBOptions = {
     factory?: IDBFactory | null;
     player?: string;
     persist?: boolean;
-    openTimeout?: number;
 };
 export declare function indexedDBBackend(options?: IndexedDBOptions): Backend & {
     close(): void;