@arcadible/sdk 1.0.0 → 1.1.1

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,7 +46,7 @@ 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 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` answers from memory. Every call that fails rejects (or, for `readSync`, throws) with an `ArcadibleError`, whose `code` says what to do.
 
 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`.
 

package/dist/bus/protocol.d.ts

@@ -16,6 +16,11 @@ 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.
+ */
 export type Build = {
     version: string;
     channel: string;
@@ -55,6 +60,7 @@ 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);

package/dist/bus/protocol.js

@@ -9,22 +9,19 @@ export const BUS_VERSION = 1;
 export const HANDSHAKE_TIMEOUT = 1000;
 // How long a request waits for its response.
 export const REQUEST_TIMEOUT = 10_000;
-// The play pages a game accepts a welcome from: production's, and `arc
-// serve`'s on this machine. Another development page (play.arcadible.test)
-// is passed with `createClient({ origins })`, never trusted by what games
-// ship, since a hostile network could pose as an http one.
-const HOST_ORIGINS = ["https://play.arcadible.com"];
-// `arc serve`'s play page, on any port. The network can't pose as loopback,
-// and on Arcadible a build's `frame-ancestors` lets only the play page frame
-// it, so no local page can reach a player's saves there.
-const LOCAL_ORIGIN = /^http:\/\/localhost:\d+$/u;
 // [function]
 // Whether a game accepts a welcome from `origin`: one of `origins` when it
-// was given, or else production's or `arc serve`'s.
+// was given (tests, and development pages), or else any real origin, `http`
+// included, whatever framed it. Who may frame a build is decided outside the
+// game, where it can change: on Arcadible by each build's `frame-ancestors`,
+// which the browser enforces before the game runs, and elsewhere by whoever
+// serves it. So the host is never trusted with anything of value (DESIGN.md,
+// section 4). Only `null` is refused: a `file://` page or a sandboxed frame,
+// which can't be told apart.
 export function isHostOrigin(origin, origins) {
     return origins
         ? origins.includes(origin)
-        : HOST_ORIGINS.includes(origin) || LOCAL_ORIGIN.test(origin);
+        : origin !== "null" && origin !== "";
 }
 // The most requests one game can have waiting on the page; past it, a
 // request fails with `busy`.
@@ -49,7 +46,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;

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

@@ -23,7 +23,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) {
@@ -50,9 +50,14 @@ 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))
+    // answers each request in `entry`, which counted once toward the limit.
+    const respond = function ({ ids, port }, outcome) {
+        const count = inFlight.get(port);
+        if (count !== undefined)
+            inFlight.set(port, count - 1);
+        if (!ports.has(port))
+            return;
+        for (const id of ids)
             port.postMessage({ kind: "response", id, ...outcome });
     };
     const answer = function (port, request) {
@@ -65,35 +70,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,20 @@ 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, and never fails. */
     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` standing alone, off
+     * Arcadible, 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/saves/backend/memory.js

@@ -5,7 +5,7 @@ function keyOf(scope) {
     return `${scope.game}\u0000${scope.channel}`;
 }
 // [function]
-// Saves kept in memory, for tests, `arc preview`, and wherever IndexedDB
+// Saves kept in memory, for tests, 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", } = {}) {

package/dist/saves/client.d.ts

@@ -1,11 +1,18 @@
 import type { Bus } from "../bus/client.js";
 import { type SaveInfo } from "./rules.js";
+/** `arcadible.saves`: each save is a name holding one string. */
 export interface Saves {
+    /** Keeps `data` as the save `name`, replacing what it held. */
     write(name: string, data: string): Promise<SaveInfo>;
+    /** The save's string, or `null` when there's none. */
     read(name: string): Promise<string | null>;
+    /** The names of the game's saves, sorted. */
     list(): Promise<string[]>;
+    /** Which version wrote the save, and when, or `null` when there's none. */
     info(name: string): Promise<SaveInfo | null>;
+    /** Removes the save, if there is one. */
     remove(name: string): Promise<void>;
+    /** After `ready`, the save's string from memory; before it, throws `not_ready`. */
     readSync(name: string): string | null;
 }
 export declare function createSaves(bus: Bus, { timeout }: {

package/dist/saves/client.js

@@ -25,6 +25,11 @@ export function createSaves(bus, { timeout }) {
     // the newest revision seen of each save, removals included.
     const revisions = new Map();
     const early = [];
+    // the newest write of each save, until the page answers it: an older
+    // write's answer, merged with it or ahead of it, mustn't replace it in
+    // the memory copy.
+    const writing = new Map();
+    let writes = 0;
     let open = () => undefined;
     const opened = new Promise((resolve) => {
         open = () => {
@@ -130,6 +135,8 @@ export function createSaves(bus, { timeout }) {
             // the memory copy changes at once, so the next read sees it; the
             // promise settles once the page has kept it.
             const previous = mirror.get(name);
+            const ticket = ++writes;
+            writing.set(name, ticket);
             if (optimistic) {
                 mirror.set(name, {
                     name,
@@ -147,10 +154,15 @@ export function createSaves(bus, { timeout }) {
                     name,
                     data,
                 }));
-                kept(name, meta.revision, { name, data, info: meta });
+                if (writing.get(name) === ticket) {
+                    writing.delete(name);
+                    kept(name, meta.revision, { name, data, info: meta });
+                }
                 return infoOf(meta);
             }
             catch (err) {
+                if (writing.get(name) === ticket)
+                    writing.delete(name);
                 // one the page refused is rolled back, unless something newer
                 // replaced it meanwhile.
                 if (optimistic &&

package/dist/saves/rules.d.ts

@@ -2,8 +2,14 @@ import { ArcadibleError } from "../bus/protocol.js";
 export declare const MAX_SAVES = 32;
 export declare const MAX_TOTAL: number;
 export type SaveStatus = "local" | "ephemeral";
+/** What a game is told of a save. */
 export type SaveInfo = {
+    /**
+     * The game's version that wrote it, stamped by the page; `null` when it
+     * was written standing alone, where there's no version to stamp.
+     */
     version: string | null;
+    /** When it was written, as an ISO 8601 time. */
     savedAt: string;
 };
 export type SaveMeta = SaveInfo & {

package/dist/saves/server.js

@@ -23,6 +23,11 @@ function nameOf(params) {
     return params["name"];
 }
 // [function]
+// what a write or remove is about, so they keep their order (bus/server.ts).
+function saveKey(params) {
+    return String(params["name"]);
+}
+// [function]
 // the device is out of room: retrying won't help until the player frees
 // some. Anything else is the bus's `unavailable`.
 function storageError(err) {
@@ -57,9 +62,13 @@ export function savesServer(options) {
         return change?.record ? toSave(change.record).info : null;
     };
     const load = async function () {
+        // when the saves were last opened is bookkeeping: a device too full to
+        // keep it still loads them.
         const [list] = await Promise.all([
             backend.list(scope),
-            backend.touch(scope, now().toISOString()),
+            backend.touch(scope, now().toISOString()).catch((err) => {
+                console.warn("arcadible: the saves' last use couldn't be kept:", err);
+            }),
         ]);
         return { status: backend.status(), items: list.map(toSave) };
     };
@@ -89,9 +98,10 @@ export function savesServer(options) {
                 "saves.list": {
                     run: async () => (await backend.list(scope)).map((record) => record.name).sort(),
                 },
-                "saves.write": { run: write, coalesce: (p) => String(p["name"]) },
+                "saves.write": { run: write, key: saveKey, coalesce: true },
                 // the removal's revision, or null when there was nothing to remove.
                 "saves.remove": {
+                    key: saveKey,
                     run: async (params) => {
                         const change = await backend.change(scope, nameOf(params), () => null, source);
                         return change?.revision ?? null;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.1.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // The client's version, sent in its hello and shown as `arcadible.version`,
 // for bug reports. It matches package.json (test/unit/protocol.test.ts).
-export const VERSION = "1.0.0";
+export const VERSION = "1.1.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": "Offst, Inc.",
-  "description": "The Arcadible SDK: how a game talks to Arcadible, over a bus between the game and the play page, starting with saves that survive updates.",
+  "description": "The Arcadible SDK: saves that carry over between a game's versions on Arcadible.",
   "devDependencies": {
     "@playwright/test": "1.63.0",
     "@types/node": "^25.0.3",
@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.0.0"
+  "version": "1.1.1"
 }