@arcadible/sdk 0.0.0-stage → 0.3.1

package/dist/bus/server.js

@@ -0,0 +1,175 @@
+// 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.
+// [import]
+import { ArcadibleError, BUS_VERSION, Codes, isHello, isMessage, 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);
+    return {
+        code: Codes.Unavailable,
+        message: "That's unavailable right now. Try again.",
+    };
+}
+// [function]
+function paramsOf(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+// [function]
+// Answers the bus for one game, on any number of ports, one request at a
+// time in order, so a read always sees the writes before it.
+export function createServer(options) {
+    const ports = new Set();
+    const inFlight = new Map();
+    // requests waiting their turn, by name and coalescing key.
+    const waiting = new Map();
+    let queue = Promise.resolve();
+    const enqueue = function (job) {
+        const run = queue.then(job);
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    const send = function (port, name, data) {
+        if (ports.has(port))
+            port.postMessage({ kind: "event", name, data });
+    };
+    const modules = options.modules.map((make) => make({
+        broadcast(name, data) {
+            for (const port of ports)
+                send(port, name, data);
+        },
+    }));
+    const handlers = new Map();
+    for (const module of modules) {
+        for (const [name, handler] of Object.entries(module.handlers)) {
+            handlers.set(name, handler);
+        }
+    }
+    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 });
+    };
+    const answer = function (port, request) {
+        const { id, name } = request;
+        const handler = handlers.get(name);
+        if (!handler) {
+            refuse(port, id, {
+                code: Codes.Unsupported,
+                message: `Unknown request: ${name}`,
+            });
+            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.",
+            });
+            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] };
+        if (key !== null)
+            waiting.set(key, entry);
+        enqueue(() => {
+            if (key !== null)
+                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 }));
+        });
+    };
+    const receive = function (port, data) {
+        if (!isMessage(data) || data.kind !== "request")
+            return;
+        if (messageSize(data, MAX_MESSAGE) > MAX_MESSAGE) {
+            refuse(port, data.id, {
+                code: Codes.TooLarge,
+                message: "The message is too large.",
+            });
+            return;
+        }
+        answer(port, data);
+    };
+    const disconnect = function (port) {
+        ports.delete(port);
+        inFlight.delete(port);
+        port.onmessage = null;
+        port.close();
+    };
+    return {
+        connect(port) {
+            ports.add(port);
+            inFlight.set(port, 0);
+            port.onmessage = (event) => receive(port, event.data);
+            // first in the queue, so it's sent before any answer. A channel
+            // replaced before its turn (hellos in a loop) opens nothing.
+            enqueue(async () => {
+                for (const module of modules) {
+                    if (!ports.has(port))
+                        return;
+                    await module.open?.((name, data) => send(port, name, data));
+                }
+            });
+            return {
+                arcadible: "welcome",
+                v: BUS_VERSION,
+                build: options.build,
+            };
+        },
+        disconnect,
+        close() {
+            for (const module of modules)
+                module.close?.();
+            for (const port of ports)
+                disconnect(port);
+        },
+    };
+}
+// [function]
+// The play page's end of the handshake: it answers a hello from its own
+// iframe, at its build's exact origin, with a welcome and a private
+// channel. A new page load in the frame says hello again, and replaces the
+// channel. Call it before inserting the iframe, so no hello is missed.
+export function answerHellos({ frame, origin, server, window: win, }) {
+    let current = null;
+    const onMessage = function (event) {
+        const target = frame.contentWindow;
+        if (!target ||
+            event.source !== target ||
+            event.origin !== origin ||
+            !isHello(event.data)) {
+            return;
+        }
+        const channel = new MessageChannel();
+        const welcome = server.connect(channel.port1);
+        if (current)
+            server.disconnect(current);
+        current = channel.port1;
+        target.postMessage({ ...welcome, v: Math.min(event.data.v, BUS_VERSION) }, origin, [channel.port2]);
+    };
+    win.addEventListener("message", onMessage);
+    return {
+        close() {
+            win.removeEventListener("message", onMessage);
+            server.close();
+            current = null;
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { type Build } from "./bus/protocol.js";
+import type { Backend } from "./saves/backend/types.js";
+import { type Saves } from "./saves/client.js";
+export type Ready = {
+    build: Build | null;
+};
+export interface Arcadible {
+    readonly version: string;
+    readonly ready: Promise<Ready>;
+    readonly build: Build | null | undefined;
+    readonly saves: Saves;
+}
+export type ClientOptions = {
+    window?: Window;
+    origins?: readonly string[];
+    handshakeTimeout?: number;
+    requestTimeout?: number;
+    backend?: () => Backend;
+};
+export declare function createClient(options?: ClientOptions): Arcadible;

package/dist/client.js

@@ -0,0 +1,42 @@
+// `createClient`: the `arcadible` object a game calls, the bus with its
+// modules on top. It says hello to the play page, and stands alone, with the
+// 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 { 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 };
+// [function]
+export function createClient(options = {}) {
+    const backend = options.backend ?? (() => indexedDBBackend());
+    const bus = openBus({
+        client: VERSION,
+        window: options.window,
+        origins: options.origins,
+        handshakeTimeout: options.handshakeTimeout,
+        requestTimeout: options.requestTimeout,
+        standalone: () => serve({ ...STANDALONE, backend: backend() }),
+    });
+    const { saves, opened } = createSaves(bus, {
+        timeout: options.requestTimeout ?? REQUEST_TIMEOUT,
+    });
+    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 };
+        return settled;
+    });
+    return {
+        version: VERSION,
+        ready,
+        get build() {
+            return settled ? settled.build : undefined;
+        },
+        saves,
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,23 @@
+import { type Server } from "./bus/server.js";
+import type { Backend } from "./saves/backend/types.js";
+export type ServeOptions = {
+    game: string;
+    channel: string;
+    version: string | null;
+    backend: Backend;
+    now?: () => Date;
+};
+export type HostOptions = ServeOptions & {
+    frame: HTMLIFrameElement;
+    origin: string;
+    window?: Window;
+};
+export declare function serve(options: ServeOptions): Server;
+export declare function createHost(options: HostOptions): {
+    close(): void;
+};
+export type { Server } from "./bus/server.js";
+export { indexedDBBackend } from "./saves/backend/indexeddb.js";
+export type { IndexedDBOptions } from "./saves/backend/indexeddb.js";
+export { memoryBackend } from "./saves/backend/memory.js";
+export type { Backend, Change, NewRecord, SaveRecord, Scope, } from "./saves/backend/types.js";

package/dist/host.js

@@ -0,0 +1,35 @@
+// `@arcadible/sdk/host`: the page's side. The play page uses `createHost`;
+// a game standing alone runs `serve` in its own page.
+// [import]
+import { answerHellos, createServer } from "./bus/server.js";
+import { savesServer } from "./saves/server.js";
+// [function]
+// Answers the bus for one game in one channel, on any number of ports.
+export function serve(options) {
+    const { backend, channel, game, version } = options;
+    return createServer({
+        build: version === null ? null : { version, channel },
+        modules: [
+            savesServer({
+                backend,
+                now: options.now ?? (() => new Date()),
+                scope: { game, channel },
+                version,
+            }),
+        ],
+    });
+}
+// [function]
+// The play page's host: it answers its iframe's hello with a welcome and a
+// private channel. Call it before inserting the iframe, so no hello is
+// missed.
+export function createHost(options) {
+    return answerHellos({
+        frame: options.frame,
+        origin: options.origin,
+        server: serve(options),
+        window: options.window ?? window,
+    });
+}
+export { indexedDBBackend } from "./saves/backend/indexeddb.js";
+export { memoryBackend } from "./saves/backend/memory.js";

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type Arcadible } from "./client.js";
+export declare const arcadible: Arcadible;
+export { ArcadibleError, Codes } from "./bus/protocol.js";
+export type { Build, Code } from "./bus/protocol.js";
+export type { Arcadible, Ready } from "./client.js";
+export type { Saves } from "./saves/client.js";
+export type { SaveInfo } from "./saves/rules.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+// `@arcadible/sdk`: the `arcadible` object a game calls. One per page, so a
+// game that has both the hosted script and the package shares it.
+// [import]
+import { createClient } from "./client.js";
+// [declare]
+const scope = globalThis;
+// [export]
+export const arcadible = scope.arcadible ?? createClient();
+scope.arcadible = arcadible;
+export { ArcadibleError, Codes } from "./bus/protocol.js";

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

@@ -0,0 +1,10 @@
+import type { Backend } from "./types.js";
+export type IndexedDBOptions = {
+    factory?: IDBFactory | null;
+    player?: string;
+    persist?: boolean;
+    openTimeout?: number;
+};
+export declare function indexedDBBackend(options?: IndexedDBOptions): Backend & {
+    close(): void;
+};

package/dist/saves/backend/indexeddb.js

@@ -0,0 +1,224 @@
+// [import]
+import { listenersByKey } from "./listeners.js";
+import { memoryBackend } from "./memory.js";
+// [declare]
+const DB_NAME = "arcadible-saves";
+const DB_VERSION = 1;
+const SAVES = "saves";
+const GAMES = "games";
+const BY_SCOPE = "scope";
+// tells the page's other tabs about each change.
+const CHANNEL = "arcadible-saves";
+// every save is a guest's for One; a signed-in player's sit beside them
+// later, under their own id, with no migration.
+const GUEST = "guest";
+// how long opening may take before saves are kept in memory instead: some
+// browsers can leave an open hanging.
+const OPEN_TIMEOUT = 5000;
+// [function]
+function settle(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+// [function]
+function finish(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted."));
+    });
+}
+// [function]
+function open(factory, timeout) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("Opening IndexedDB timed out.")), timeout);
+        const request = factory.open(DB_NAME, DB_VERSION);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            // the same key the server's records will have: player, game,
+            // channel, and name.
+            const saves = db.createObjectStore(SAVES, {
+                keyPath: ["player", "game", "channel", "name"],
+            });
+            saves.createIndex(BY_SCOPE, ["player", "game", "channel"]);
+            db.createObjectStore(GAMES, { keyPath: ["player", "game", "channel"] });
+        };
+        request.onsuccess = () => {
+            clearTimeout(timer);
+            resolve(request.result);
+        };
+        request.onerror = () => {
+            clearTimeout(timer);
+            reject(request.error);
+        };
+    });
+}
+// [function]
+function toRecord(stored) {
+    const { name, data, version, savedAt, size, revision } = stored;
+    return { name, data, version, savedAt, size, revision };
+}
+// [function]
+// the connection was closed under us (a newer page upgrading, or Safari
+// dropping it): open again.
+function isClosed(err) {
+    return (err instanceof Error &&
+        (err.name === "InvalidStateError" || err.name === "UnknownError"));
+}
+// [function]
+// Saves kept in IndexedDB: the play page's, which every game shares, and a
+// game standing alone on its own origin. Where IndexedDB won't open, such as
+// some `file://` pages, they're kept in memory, and `status()` says so.
+export function indexedDBBackend(options = {}) {
+    const factory = options.factory === undefined
+        ? (globalThis.indexedDB ?? null)
+        : options.factory;
+    const player = options.player ?? GUEST;
+    const fallback = memoryBackend();
+    const listeners = listenersByKey();
+    let status = "local";
+    let asked = false;
+    const keyOf = (scope) => `${player}\u0000${scope.game}\u0000${scope.channel}`;
+    const rangeOf = (scope) => IDBKeyRange.only([player, scope.game, scope.channel]);
+    const connect = async function () {
+        try {
+            if (!factory)
+                throw new Error("IndexedDB isn't available here.");
+            const db = await open(factory, options.openTimeout ?? OPEN_TIMEOUT);
+            // a newer version of this page wants to upgrade: step aside.
+            db.onversionchange = () => db.close();
+            if (options.persist && !asked) {
+                asked = true;
+                globalThis.navigator?.storage?.persist?.().catch(() => false);
+            }
+            return db;
+        }
+        catch (err) {
+            console.warn("arcadible: saves are kept in memory only:", err);
+            status = "ephemeral";
+            return null;
+        }
+    };
+    let opening = connect();
+    // runs `op` on the database, opening it again once if it was closed, or
+    // on the memory fallback when there's none.
+    const run = async function (op, otherwise) {
+        const current = opening;
+        const db = await current;
+        if (!db)
+            return otherwise();
+        try {
+            return await op(db);
+        }
+        catch (err) {
+            if (!isClosed(err))
+                throw err;
+            // once, however many operations found it closed.
+            if (opening === current)
+                opening = connect();
+            const again = await opening;
+            return again ? op(again) : otherwise();
+        }
+    };
+    const broadcast = typeof BroadcastChannel === "undefined"
+        ? null
+        : new BroadcastChannel(CHANNEL);
+    if (broadcast) {
+        broadcast.onmessage = (event) => {
+            const { key, change, source } = event.data;
+            listeners.tell(key, change, source);
+        };
+    }
+    const tell = function (scope, change, source) {
+        const key = keyOf(scope);
+        listeners.tell(key, change, source);
+        broadcast?.postMessage({ key, change, source });
+    };
+    const change = async function (db, scope, name, decide) {
+        // one transaction for the check and the write, so two tabs can't both
+        // pass the limits, or take the same revision.
+        const tx = db.transaction([SAVES, GAMES], "readwrite");
+        const saves = tx.objectStore(SAVES);
+        const games = tx.objectStore(GAMES);
+        const gameKey = [player, scope.game, scope.channel];
+        const [all, row] = await Promise.all([
+            settle(saves.index(BY_SCOPE).getAll(rangeOf(scope))),
+            settle(games.get(gameKey)),
+        ]);
+        let next;
+        try {
+            next = decide(all.map(toRecord));
+        }
+        catch (err) {
+            tx.abort();
+            await finish(tx).catch(() => undefined);
+            throw err;
+        }
+        const exists = all.some((r) => r.name === name);
+        if (!next && !exists) {
+            await finish(tx);
+            return null;
+        }
+        const game = row ?? {
+            player,
+            game: scope.game,
+            channel: scope.channel,
+        };
+        const revision = (game.revision ?? 0) + 1;
+        games.put({ ...game, revision });
+        const record = next ? { ...next, revision } : null;
+        if (record)
+            saves.put({ ...record, player, ...scope });
+        else
+            saves.delete([player, scope.game, scope.channel, name]);
+        await finish(tx);
+        return { name, record, revision };
+    };
+    return {
+        status: () => status,
+        list(scope) {
+            return run(async (db) => {
+                const tx = db.transaction(SAVES, "readonly");
+                const all = await settle(tx.objectStore(SAVES).index(BY_SCOPE).getAll(rangeOf(scope)));
+                return all.map(toRecord);
+            }, () => fallback.list(scope));
+        },
+        get(scope, name) {
+            return run(async (db) => {
+                const tx = db.transaction(SAVES, "readonly");
+                const stored = await settle(tx
+                    .objectStore(SAVES)
+                    .get([player, scope.game, scope.channel, name]));
+                return stored ? toRecord(stored) : null;
+            }, () => fallback.get(scope, name));
+        },
+        async change(scope, name, decide, source) {
+            const result = await run((db) => change(db, scope, name, decide), () => fallback.change(scope, name, decide, source));
+            if (result)
+                tell(scope, result, source);
+            return result;
+        },
+        touch(scope, at) {
+            return run(async (db) => {
+                const tx = db.transaction(GAMES, "readwrite");
+                const games = tx.objectStore(GAMES);
+                const key = [player, scope.game, scope.channel];
+                const row = (await settle(games.get(key)));
+                games.put({
+                    ...(row ?? { player, game: scope.game, channel: scope.channel }),
+                    usedAt: at,
+                });
+                return finish(tx);
+            }, () => fallback.touch(scope, at));
+        },
+        subscribe(scope, listener) {
+            return listeners.add(keyOf(scope), listener);
+        },
+        close() {
+            broadcast?.close();
+            opening.then((db) => db?.close()).catch(() => undefined);
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { Change } from "./types.js";
+export type Listener = (change: Change, source: string) => void;
+export declare function listenersByKey(): {
+    add(key: string, listener: Listener): () => void;
+    tell(key: string, change: Change, source: string): void;
+};

package/dist/saves/backend/listeners.js

@@ -0,0 +1,33 @@
+// [import]
+// [function]
+// Each game's subscribers, by key, for a backend to tell of changes. Each
+// gets its own copy, so one can't change what the next one sees, and one
+// that throws doesn't fail the change, which is already kept.
+export function listenersByKey() {
+    const listeners = new Map();
+    return {
+        add(key, listener) {
+            let set = listeners.get(key);
+            if (!set) {
+                set = new Set();
+                listeners.set(key, set);
+            }
+            set.add(listener);
+            return () => {
+                set.delete(listener);
+                if (set.size === 0 && listeners.get(key) === set)
+                    listeners.delete(key);
+            };
+        },
+        tell(key, change, source) {
+            for (const listener of [...(listeners.get(key) ?? [])]) {
+                try {
+                    listener(structuredClone(change), source);
+                }
+                catch (err) {
+                    console.error("arcadible: a change's listener failed:", err);
+                }
+            }
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { SaveStatus } from "../rules.js";
+import type { Backend, Scope } from "./types.js";
+export declare function memoryBackend({ status, }?: {
+    status?: SaveStatus;
+}): Backend & {
+    used(scope: Scope): string | undefined;
+};

package/dist/saves/backend/memory.js

@@ -0,0 +1,51 @@
+// [import]
+import { listenersByKey } from "./listeners.js";
+// [function]
+function keyOf(scope) {
+    return `${scope.game}\u0000${scope.channel}`;
+}
+// [function]
+// Saves kept in memory, for tests, `arc preview`, and wherever IndexedDB
+// won't open. Hosts sharing one act like tabs sharing a device. Its saves
+// last as long as the page, so it says `ephemeral`.
+export function memoryBackend({ status = "ephemeral", } = {}) {
+    const games = new Map();
+    const listeners = listenersByKey();
+    const gameOf = function (scope) {
+        const key = keyOf(scope);
+        let game = games.get(key);
+        if (!game) {
+            game = { saves: new Map(), revision: 0 };
+            games.set(key, game);
+        }
+        return game;
+    };
+    return {
+        status: () => status,
+        list: async (scope) => [...gameOf(scope).saves.values()].map((r) => ({ ...r })),
+        get: async (scope, name) => {
+            const record = gameOf(scope).saves.get(name);
+            return record ? { ...record } : null;
+        },
+        change: async (scope, name, decide, source) => {
+            const game = gameOf(scope);
+            const next = decide([...game.saves.values()].map((r) => ({ ...r })));
+            if (!next && !game.saves.has(name))
+                return null;
+            const revision = ++game.revision;
+            const record = next ? { ...next, revision } : null;
+            if (record)
+                game.saves.set(name, record);
+            else
+                game.saves.delete(name);
+            const change = { name, record: record && { ...record }, revision };
+            listeners.tell(keyOf(scope), change, source);
+            return change;
+        },
+        touch: async (scope, at) => {
+            gameOf(scope).usedAt = at;
+        },
+        subscribe: (scope, listener) => listeners.add(keyOf(scope), listener),
+        used: (scope) => games.get(keyOf(scope))?.usedAt,
+    };
+}

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

@@ -0,0 +1,27 @@
+import type { SaveStatus } from "../rules.js";
+export type Scope = {
+    game: string;
+    channel: string;
+};
+export type SaveRecord = {
+    name: string;
+    data: string;
+    version: string | null;
+    savedAt: string;
+    size: number;
+    revision: number;
+};
+export type NewRecord = Omit<SaveRecord, "revision">;
+export type Change = {
+    name: string;
+    record: SaveRecord | null;
+    revision: number;
+};
+export interface Backend {
+    status(): SaveStatus;
+    list(scope: Scope): Promise<SaveRecord[]>;
+    get(scope: Scope, name: string): Promise<SaveRecord | null>;
+    change(scope: Scope, name: string, decide: (saves: SaveRecord[]) => NewRecord | null, source: string): Promise<Change | null>;
+    touch(scope: Scope, at: string): Promise<void>;
+    subscribe(scope: Scope, listener: (change: Change, source: string) => void): () => void;
+}