castle-web-sdk 0.4.25 → 0.4.26

package/README.md

@@ -10,11 +10,12 @@ there — nothing to install, and no deck `package.json` names it. Import
 what you need from `castle-web-sdk`:
 
 ```js
-import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
+import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 ```
 
 ## Contents
 
+- [Store](#store)
 - [Storage](#storage)
 - [SharedStorage](#sharedstorage)
 - [Leaderboard](#leaderboard)
@@ -63,8 +64,9 @@ or server `broadcast` to send its raw bytes. Receivers always get those bytes as
 `Uint8Array`; reconstruct another view type such as `Float32Array` on receipt.
 Multi-byte values use the sender platform's byte order. Every other payload uses
 JSON. Client→server messages are capped at 16 KB and server→client messages at
-64 KB, for both JSON and binary frames. A binary frame includes a one-byte protocol
-tag. A published server bundle on an older runtime throws
+64 KB, for both JSON and binary frames. Both caps are on the frame, and a binary
+frame includes a one-byte protocol tag, so the largest payload is one byte under the
+cap. A published server bundle on an older runtime throws
 `TypeError: This Castle runtime does not support binary multiplayer messages yet.`
 
 Server callbacks are the default export from the deck's server entry. They are
@@ -85,71 +87,215 @@ TypeScript server entries can import callback, session, player, and platform
 handle types from `castle-web-sdk/server`. Server transport has no runtime
 dependency on a WebSocket package.
 
-## Storage
+### `session.storage`
 
-`Storage` saves data for the current player. Nobody else can read it.
-Use it for save files, settings, progress.
+A session ends when its last player leaves, and its memory goes with it.
+`session.storage` is what outlives one, and it is the same store the deck's
+clients see through [`Store`](#store):
+
+```js
+export default {
+  async onPlayerJoin(session, player) {
+    const { wins = 0 } = await session.storage.deck.get(["wins"]);
+    session.send(player.playerId, { wins });
+  },
+
+  async onShutdown(session) {
+    await session.storage.deck.set({ endedAt: Date.now() });
+  },
+};
+```
+
+`session.storage.deck` is shared by everyone playing.
+`session.storage.user(userId)` is one player's public data.
+`session.storage.board(name)` is a leaderboard. Each scope has the same
+`get`, `set`, `remove`, `increment` and `list` as `Store`.
+
+Two differences follow from a session server not being a player:
+
+- **It owns `deck` scope.** Once a deck has a published server, clients read
+  that data but no longer write it, which is what lets you keep authoritative
+  state players cannot forge.
+- **It has no self.** There is no `storage.me`, and a user scope or a board
+  submission must name the player: `session.storage.user(player.userId)`,
+  `session.storage.board("high").submit(player.userId, score)`. A server can
+  submit anyone's score, which is what makes a server-run leaderboard worth
+  trusting. It can never read `private` storage, not even for its own players.
+
+`onShutdown` is awaited, so a save made there does land — but only on a clean
+stop. An out-of-memory kill or a host failing sends no shutdown at all, so
+save as things change and treat `onShutdown` as the last chance, not the plan.
+
+## Store
 
-### `Storage.get<T>(key): Promise<T | null>`
+`Store` saves data one key at a time. It is the storage to use for
+multiplayer decks: two players writing different keys no longer
+overwrite each other, a counter can be added to safely from several
+places at once, and a deck can hold much more than `Storage` allows and
+read back a slice of it rather than the whole thing.
 
-Returns the value at `key`, or `null` if not set.
+Values can be anything that converts to JSON, the same as `Storage`.
+
+Scopes decide who owns a key:
+
+- `Store.deck` — shared by everyone playing. If the deck publishes a
+  session server, the server owns these keys and players read them.
+- `Store.me` — the current player's data, which other players can read.
+- `Store.user(userId)` — another player's public data. Anyone can read
+  it; only that player, or the deck's session server, can write it.
+- `Store.private` — the current player's own data. Nobody else can read
+  it, and a session server never sees it.
+
+### `Store.<scope>.get<T>(keys): Promise<Record<string, T>>`
+
+Reads several keys at once. Keys with nothing stored are missing from
+the result rather than present as `null`.
 
 ```js
-const level = (await Storage.get("level")) ?? 1;
+const { level = 1, name } = await Store.deck.get(["level", "name"]);
 ```
 
-### `Storage.set(key, value)`
+### `Store.<scope>.set(values): Promise<void>`
 
-Sets `key` to `value`. `value` must be something that can convert to
-JSON (`null`, booleans, finite numbers, strings, arrays, plain
-objects). The next `get(key)` returns the new value immediately. Writes
-save in the background.
+Writes several keys. Nearby writes are grouped, so saving on every
+change costs one request per burst. The promise resolves once the
+platform has the write, so a deck can tell whether saving worked.
 
 ```js
-Storage.set("level", 7);
-Storage.set("settings", { sound: true, music: false });
+await Store.deck.set({ level: 7, name: "Ada" });
 ```
 
-### `Storage.remove(key)`
+### `Store.<scope>.remove(keys): Promise<void>`
 
-Removes `key`.
+Removes keys.
 
-## SharedStorage
+### `Store.<scope>.increment(key, delta?): Promise<number>`
+
+Adds `delta` (default `1`) to a number and returns the new total,
+starting the key at `delta` if it was not set. Two players incrementing
+at the same moment both count, which is the thing a read, add and write
+back cannot promise.
 
-`SharedStorage` saves data that other players can read. Values must
-be something that can convert to JSON, same as `Storage`.
+```js
+const plays = await Store.deck.increment("plays");
+```
+
+### `Store.<scope>.list(options?): Promise<{ entries, cursor }>`
+
+Reads a page of keys in order, optionally only those starting with
+`prefix`. Pass the `cursor` from one page to get the next.
+
+```js
+let cursor = null;
+const world = [];
+do {
+  const page = await Store.deck.list({ prefix: "block:", cursor });
+  world.push(...page.entries);
+  cursor = page.cursor;
+} while (cursor);
+```
 
-Scopes:
+Keep reading until `cursor` is `null`. A page can come back shorter than
+you asked for because it reached its size limit, not because the keys
+ran out, so the cursor is the only reliable end signal.
 
-- `'deck'` — one shared bucket for the whole deck. Any player can read
-  or write.
-- `'user'` — a per-player public bucket. Any player can read; only the
-  owning player can write.
+A paged read is not a snapshot: something written while you are paging
+may land in no page or in two. Treat the result as a starting point and
+apply live updates on top, which a multiplayer deck is doing anyway.
 
-### `SharedStorage.get(scope, key): Promise<T | null>`
+### `Store.board(name)`
 
-Reads a shared value. For `'user'`, omit the user id to read the
-current player's bucket, or pass one to read someone else's:
+A leaderboard, separate from the keys above so that reading the top
+scores stays fast no matter how many players there are.
 
 ```js
-const worldHighScore = await SharedStorage.get("deck", "highScore");
-const myColor = await SharedStorage.get("user", "color");
-const theirColor = await SharedStorage.get("user", otherUserId, "color");
+await Store.board("highscores").submit(score);
+const top = await Store.board("highscores").top(10);
+const mine = await Store.board("highscores").get();
 ```
 
-### `SharedStorage.set(scope, key, value)`
+- `submit(score)` records the current player's score. A later submission
+  replaces an earlier one, so compare first if you only want to keep a
+  personal best.
+- `top(limit?)` returns the highest scores, best first.
+- `get(userId?)` returns one player's score, defaulting to the current
+  player, or `null` if they have none.
+
+A deck's session server can submit any player's score, which is how a
+leaderboard becomes something a player cannot fake. See the multiplayer
+guide.
+
+### Limits
 
-Writes a shared value. `'user'` writes always go to the current
-player's bucket. Writes save in the background.
+The platform caps key length, value size, how many keys one call may
+touch, page size, and how much a deck may store in total, and it limits
+how fast a player may read and write. Going over any of them rejects
+with a `CastleError` whose `code` says which, so a deck can tell a
+player it is saving too fast apart from a deck that is out of space.
+
+## Storage
+
+> Older API, still supported and not going away. New decks should use
+> [`Store`](#store) instead: it stores each key on its own, so concurrent
+> writes do not overwrite each other, and it holds far more than this does.
+> `Storage` keeps one document per player and rewrites all of it on every
+> change.
+
+`Storage` saves data for the current player. Nobody else can read it.
+
+- **`Storage.get<T>(key): Promise<T | null>`** — the value at `key`, or
+  `null` if it is not set.
+- **`Storage.set(key, value)`** — sets `key`. `value` must be something
+  that converts to JSON. The next `get(key)` returns it immediately;
+  the write saves in the background.
+- **`Storage.remove(key)`** — removes `key`.
 
 ```js
-SharedStorage.set("deck", "highScore", 9001);
+const level = (await Storage.get("level")) ?? 1;
+Storage.set("level", 7);
+```
+
+The same thing with `Store`, which is what a new deck should write:
+
+```js
+const { level = 1 } = await Store.private.get(["level"]);
+await Store.private.set({ level: 7 });
+```
+
+## SharedStorage
+
+> Older API, still supported and not going away. New decks should use
+> [`Store`](#store) instead. `SharedStorage` has no ownership rule — any
+> player can overwrite any key in the `'deck'` bucket — and two players
+> writing at the same moment lose one of the writes. `Store` fixes both,
+> and adds counters, listing, and leaderboards.
+
+`SharedStorage` saves data that other players can read. Values must be
+something that converts to JSON, same as `Storage`.
+
+Scopes: `'deck'` is one bucket for the whole deck, readable and writable
+by any player. `'user'` is a per-player bucket that anyone can read and
+only the owning player can write.
+
+- **`SharedStorage.get(scope, key)`** — reads a shared value. For
+  `'user'`, pass a user id before the key to read someone else's bucket.
+- **`SharedStorage.set(scope, key, value)`** — writes. `'user'` writes
+  always go to the current player.
+- **`SharedStorage.remove(scope, key)`** — removes a shared value.
+
+```js
+const worldHighScore = await SharedStorage.get("deck", "highScore");
+const theirColor = await SharedStorage.get("user", otherUserId, "color");
 SharedStorage.set("user", "color", "red");
 ```
 
-### `SharedStorage.remove(scope, key)`
+The same thing with `Store`:
 
-Removes a shared value.
+```js
+const { highScore } = await Store.deck.get(["highScore"]);
+const { color } = await Store.user(otherUserId).get(["color"]);
+await Store.me.set({ color: "red" });
+```
 
 ## Leaderboard
 

package/dist/castle.d.ts

@@ -20,6 +20,8 @@ export type { FileChange, FilesChangedEvent } from "./runtime";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
+export { Store } from "./store";
+export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreScopeApi, } from "./store";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
 export type { Json } from "./types";

package/dist/castle.js

@@ -12,5 +12,6 @@ export { Portal } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
+export { Store } from "./store";
 export { Time } from "./time";
 export { User } from "./user";

package/dist/chunk.d.ts

@@ -0,0 +1 @@
+export declare function chunked<T>(items: T[], size: number): T[][];

package/dist/chunk.js

@@ -0,0 +1,15 @@
+// Both deck-storage APIs send their keys and entries a batch at a time -- the
+// per-key Store from the browser, session storage from a server -- so the split
+// lives here rather than once in each, where the two could drift on where a
+// batch ends.
+export function chunked(items, size) {
+    if (items.length === 0)
+        return [];
+    if (items.length <= size)
+        return [items];
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}

package/dist/commands.d.ts

@@ -2,6 +2,20 @@ import type { Json } from "./types";
 export declare const CASTLE_SDK_PROTOCOL = 1;
 export type StorageBlob = Record<string, string>;
 export type SharedScope = "deck" | "user";
+export type StoreScope = "deck" | "user" | "private";
+export interface StoreEntry {
+    key: string;
+    value: string;
+}
+export interface StoreUsage {
+    rowCount: number;
+    byteCount: number;
+}
+export interface StoreBoardEntry {
+    subject: string;
+    score: number;
+    updatedAt: string;
+}
 export interface StorageUpdate {
     key: string;
     value: string | null;
@@ -110,6 +124,53 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "cauldronStorage.get": {
+        scope: StoreScope;
+        subject?: string | null;
+        keys: string[];
+    };
+    "cauldronStorage.set": {
+        scope: StoreScope;
+        subject?: string | null;
+        entries: StoreEntry[];
+        asServer?: boolean;
+        unload?: boolean;
+    };
+    "cauldronStorage.delete": {
+        scope: StoreScope;
+        subject?: string | null;
+        keys: string[];
+        asServer?: boolean;
+        unload?: boolean;
+    };
+    "cauldronStorage.increment": {
+        scope: StoreScope;
+        subject?: string | null;
+        key: string;
+        delta: number;
+        asServer?: boolean;
+    };
+    "cauldronStorage.list": {
+        scope: StoreScope;
+        subject?: string | null;
+        prefix?: string | null;
+        limit?: number | null;
+        cursor?: string | null;
+    };
+    "cauldronStorage.boardSubmit": {
+        board: string;
+        subject?: string | null;
+        score: number;
+        asServer?: boolean;
+    };
+    "cauldronStorage.boardTop": {
+        board: string;
+        limit?: number | null;
+    };
+    "cauldronStorage.boardGet": {
+        board: string;
+        subject?: string | null;
+    };
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -152,6 +213,31 @@ export interface CommandResult {
     "portal.prefetch": PortalPrefetchResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "cauldronStorage.get": {
+        entries: StoreEntry[];
+    };
+    "cauldronStorage.set": {
+        usage: StoreUsage;
+    };
+    "cauldronStorage.delete": {
+        usage: StoreUsage;
+    };
+    "cauldronStorage.increment": {
+        value: string;
+    };
+    "cauldronStorage.list": {
+        entries: StoreEntry[];
+        cursor: string | null;
+    };
+    "cauldronStorage.boardSubmit": {
+        entry: StoreBoardEntry;
+    };
+    "cauldronStorage.boardTop": {
+        entries: StoreBoardEntry[];
+    };
+    "cauldronStorage.boardGet": {
+        entry: StoreBoardEntry | null;
+    };
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {

package/dist/runtime.js

@@ -68,27 +68,35 @@ export function fileUrl(path) {
 }
 // Move a deck file. `writeFile`'s counterpart for the case where the file's
 // NAME is the thing changing -- an editor renaming a blueprint has to move the
-// file, not write a copy and leave the old one behind. Rejects when the
-// destination exists or the source is gone (the serve's own guards), so a
-// caller can surface the collision instead of silently clobbering.
+// file, not write a copy and leave the old one behind. Rides the same local
+// socket / shell bridge as `writeFile`: a content iframe cannot POST the HTTP
+// files API (serve capability gate), so rename must not fetch either.
+// Rejects when the destination exists or the source is gone.
 export async function renameFile(from, to) {
-    await fileOp("rename", { from, to });
+    const response = await sendLocalRequest({
+        type: "rename_file",
+        from,
+        to,
+    });
+    if (response.ok === false) {
+        throw new Error(typeof response.error === "string" && response.error
+            ? response.error
+            : "castle: rename failed");
+    }
 }
 // Delete a deck file. Editor UI only, same as `writeFile` -- a published deck
-// has no serve to ask.
+// has no serve to ask. Still HTTP for now (shell Files panel); content iframes
+// cannot call it until it grows a bridge message like `rename_file`.
 export async function deleteFile(path) {
-    await fileOp("delete", { path });
-}
-async function fileOp(action, body) {
-    const res = await fetch(`/__castle/files/${action}`, {
+    const res = await fetch("/__castle/files/delete", {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
+        body: JSON.stringify({ path }),
     });
     if (res.ok)
         return;
     const detail = await res.text().catch(() => "");
-    throw new Error(`castle: ${action} failed (${res.status}) ${detail}`.trim());
+    throw new Error(`castle: delete failed (${res.status}) ${detail}`.trim());
 }
 // Ask the editor shell to open (or focus) an editor for `path`. This is how a
 // kit editor hands the creator off to another file -- the creation modal
@@ -840,7 +848,8 @@ function handleLocalMessage(msg) {
     else if (msg.type === "files_changed") {
         dispatchFilesChanged(msg);
     }
-    else if (msg.type === "write_file_response") {
+    else if (msg.type === "write_file_response" ||
+        msg.type === "rename_file_response") {
         resolveLocalRequest(msg);
     }
     else if (msg.type === "castle_command_response") {

package/dist/server/platformHandle.d.ts

@@ -24,5 +24,15 @@ export interface PlatformHandle {
     on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
     on(event: "replaced", callback: () => unknown): void;
     on(event: "shutdown", callback: (reason?: string) => unknown): void;
+    /**
+     * Deck storage. Strings in and strings out, like the rest of this handle, so a
+     * runtime other than the Node shim can implement it without knowing what storage is.
+     *
+     * Optional because a published bundle may run on a host that predates storage.
+     * Rejects with an Error whose `code` is the platform's error code.
+     */
+    storage?(op: string, argsJson: string): Promise<string>;
+    /** False when the host cannot broker storage, so a call can fail at once. */
+    readonly storageEnabled?: boolean;
     readonly config: PlatformSessionConfig;
 }

package/dist/server/storage.d.ts

@@ -0,0 +1,46 @@
+import type { Json } from "../types";
+import type { PlatformHandle } from "./platformHandle";
+export interface ServerStorageListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+export interface ServerStorageListEntry<T extends Json = Json> {
+    key: string;
+    value: T;
+}
+export interface ServerStorageListPage<T extends Json = Json> {
+    entries: ServerStorageListEntry<T>[];
+    /** Null means there is nothing left. A short page alone does not mean that. */
+    cursor: string | null;
+}
+export interface ServerStorageScope {
+    get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
+    set(values: Record<string, Json>): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    increment(key: string, delta?: number): Promise<number>;
+    list<T extends Json = Json>(options?: ServerStorageListOptions): Promise<ServerStorageListPage<T>>;
+}
+export interface ServerStorageBoardScore {
+    subject: string;
+    score: number;
+    updatedAt: string;
+}
+export interface ServerStorageBoard {
+    /**
+     * Records a score for a player. A client may only submit its own; a server is the
+     * authority for its whole session and names whose score this is, which is the
+     * difference that makes a leaderboard worth trusting.
+     */
+    submit(userId: string, score: number): Promise<ServerStorageBoardScore>;
+    top(limit?: number): Promise<ServerStorageBoardScore[]>;
+    get(userId: string): Promise<ServerStorageBoardScore | null>;
+}
+export interface ServerStorage {
+    /** Shared by everyone playing the deck, and owned by this server. */
+    readonly deck: ServerStorageScope;
+    /** One player's public data. Readable by anyone; writable by them or by this server. */
+    user(userId: string): ServerStorageScope;
+    board(name: string): ServerStorageBoard;
+}
+export declare function createServerStorage(platformHandle: PlatformHandle): ServerStorage;