castle-web-sdk 0.4.44 → 0.4.46

package/dist/saveCoordinator.js

@@ -0,0 +1,252 @@
+import { asSaveError, encodeSaveInput, matchSaveTarget, SaveError, saveTargetKey, } from "./save";
+// The request is built when a save is first sent, from the revisions known then.
+function buildRequest(intent, access, revisions, writers) {
+    const changes = intent.changes.map((change) => {
+        const key = saveTargetKey(change.target);
+        const expectedRevision = change.expectedRevision === undefined
+            ? revisions.get(key)
+            : change.expectedRevision;
+        if (expectedRevision === undefined) {
+            throw new SaveError({
+                code: "CAULDRON_STORAGE_INVALID_ARGUMENT",
+                message: "Load a target's revision before saving it.",
+                operationId: intent.operationId,
+                retryable: false,
+                committed: false,
+                target: change.target,
+            });
+        }
+        const writer = change.writer ?? writers.get(key);
+        return {
+            ...change,
+            expectedRevision,
+            ...(writer === undefined ? {} : { writer }),
+        };
+    });
+    return {
+        operationId: intent.operationId,
+        expectedAccess: access,
+        ...(intent.checks ? { checks: intent.checks } : {}),
+        changes,
+    };
+}
+// A committed error with its receipt is a repeat of a save that committed
+// earlier, whose fresh reply failed for some other reason.
+async function send(api, request) {
+    try {
+        return await api.transaction(request);
+    }
+    catch (failure) {
+        const error = asSaveError(failure, request.operationId);
+        if (error.committed === true && error.receipt)
+            return error.receipt;
+        throw error;
+    }
+}
+// An unknown outcome is not a cancellation: the first request may still
+// arrive. So it is looked up, then sent again exactly as before.
+async function settle(api, request) {
+    try {
+        return await send(api, request);
+    }
+    catch (error) {
+        if (error.committed !== "unknown")
+            throw error;
+    }
+    let found;
+    try {
+        found = await api.operation(request.operationId);
+    }
+    catch (failure) {
+        const error = asSaveError(failure, request.operationId);
+        throw new SaveError({
+            ...error.extensions,
+            code: error.code,
+            message: error.message,
+            operationId: request.operationId,
+            retryable: error.retryable,
+            committed: "unknown",
+        });
+    }
+    if (found.state === "committed")
+        return found.receipt;
+    return send(api, request);
+}
+/**
+ * Starts from a snapshot of the targets to be saved and the writers of any
+ * claimed ones. Keep the coordinator where it outlives a replaceable worker.
+ */
+export function createSaveCoordinator(api, snapshot, writers = []) {
+    const access = snapshot.access;
+    const revisions = new Map(snapshot.targets.map((entry) => [
+        saveTargetKey(entry.target),
+        entry.revision,
+    ]));
+    const writerTokens = new Map(writers.map((entry) => [saveTargetKey(entry.target), entry.writer]));
+    const submittedIds = new Set();
+    const queue = [];
+    let flushes = [];
+    let blocked;
+    let running;
+    function apply(receipt, request) {
+        const targets = request.changes.map((change) => change.target);
+        for (const entry of receipt.revisions) {
+            const target = matchSaveTarget(entry.target, targets);
+            revisions.set(saveTargetKey(target), entry.revision);
+        }
+    }
+    function block(item, error) {
+        blocked = error;
+        if (error.committed === false && !error.retryable) {
+            item.failed = true;
+            item.reject(error);
+        }
+        for (const flush of flushes)
+            flush.reject(error);
+        flushes = [];
+    }
+    function commit(item, receipt) {
+        queue.shift();
+        item.resolve(receipt);
+        flushes = flushes.filter((flush) => {
+            if (flush.last !== item)
+                return true;
+            flush.resolve();
+            return false;
+        });
+    }
+    async function drain() {
+        while (queue.length > 0 && !blocked) {
+            const item = queue[0];
+            try {
+                item.request ??= buildRequest(item.intent, access, revisions, writerTokens);
+                const receipt = await settle(api, item.request);
+                apply(receipt, item.request);
+                commit(item, receipt);
+            }
+            catch (failure) {
+                block(item, asSaveError(failure, item.intent.operationId));
+            }
+        }
+    }
+    // A save submitted while the last drain was finishing finds it still running,
+    // so the drain looks again once it is done.
+    function start() {
+        running ??= drain().finally(() => {
+            running = undefined;
+            if (queue.length > 0 && !blocked)
+                void start();
+        });
+        return running;
+    }
+    return {
+        get status() {
+            if (blocked)
+                return "blocked";
+            return queue.length > 0 ? "pending" : "saved";
+        },
+        get error() {
+            return blocked;
+        },
+        get pendingOperationIds() {
+            return queue
+                .filter((item) => !item.failed)
+                .map((item) => item.intent.operationId);
+        },
+        revision: (target) => revisions.get(saveTargetKey(target)),
+        submit(input) {
+            if (submittedIds.has(input.operationId)) {
+                return Promise.reject(new SaveError({
+                    code: "CAULDRON_STORAGE_OPERATION_MISMATCH",
+                    message: "This coordinator already has that operation id.",
+                    operationId: input.operationId,
+                    retryable: false,
+                    committed: false,
+                }));
+            }
+            // Encoding validates and copies the save, so later changes to the
+            // caller's objects do not reach it.
+            let intent;
+            try {
+                const encoded = encodeSaveInput("transaction", {
+                    operationId: input.operationId,
+                    expectedAccess: access,
+                    ...(input.checks ? { checks: input.checks } : {}),
+                    changes: input.changes.map((change) => ({
+                        ...change,
+                        expectedRevision: change.expectedRevision ?? null,
+                    })),
+                });
+                intent = {
+                    operationId: encoded.operationId,
+                    ...(encoded.checks ? { checks: encoded.checks } : {}),
+                    changes: encoded.changes.map((change, index) => ({
+                        ...change,
+                        expectedRevision: input.changes[index].expectedRevision,
+                    })),
+                };
+            }
+            catch (error) {
+                return Promise.reject(asSaveError(error, input.operationId));
+            }
+            submittedIds.add(input.operationId);
+            const promise = new Promise((resolve, reject) => {
+                queue.push({ intent, failed: false, resolve, reject });
+            });
+            // A deck may watch status or flush() instead of every save's promise.
+            promise.catch(() => { });
+            void start();
+            return promise;
+        },
+        flush() {
+            const last = queue.at(-1);
+            if (!last)
+                return Promise.resolve();
+            if (blocked)
+                return Promise.reject(blocked);
+            return new Promise((resolve, reject) => {
+                flushes.push({ last, resolve, reject });
+            });
+        },
+        async retry() {
+            await running;
+            if (!blocked)
+                return;
+            if (queue[0]?.failed)
+                throw blocked;
+            if (blocked.retryAfterMs !== undefined && blocked.retryAfterMs > 0) {
+                const delay = blocked.retryAfterMs;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            blocked = undefined;
+            return start().then(() => {
+                if (blocked)
+                    throw blocked;
+            });
+        },
+        discardUnsent() {
+            const error = new SaveError({
+                code: "CAULDRON_STORAGE_CANCELLED",
+                message: "The save was discarded before it was sent.",
+                retryable: false,
+                committed: false,
+            });
+            for (let index = queue.length - 1; index >= 0; index--) {
+                const item = queue[index];
+                if (item.request || item.failed)
+                    continue;
+                queue.splice(index, 1);
+                item.reject(error);
+            }
+            // A flush still waits for the sent save ahead of what was dropped.
+            flushes = flushes.filter((flush) => {
+                if (!flush.last || !queue.includes(flush.last))
+                    flush.last = queue[0];
+                if (flush.last)
+                    return true;
+                flush.resolve();
+                return false;
+            });
+        },
+    };
+}

package/dist/server/hub.d.ts

@@ -0,0 +1,169 @@
+import type { PlatformHandle, PlatformHubResultShape } from "./platformHandle";
+export type MultiplayerHubOutcome = "win" | "lose" | "draw";
+export type MultiplayerHubResultShape = PlatformHubResultShape;
+/** Where a player came in through a hub door: ghost's word, never a client's. */
+export interface MultiplayerHubArrival {
+    /** The deck of the place the player came from. */
+    readonly fromDeckId: string;
+    /** The door of this place the player arrived by, when the door row names one. */
+    readonly doorId: string | null;
+}
+export interface MultiplayerHubResultInput {
+    /** This session's place; refused when it names another. */
+    place?: string;
+    outcome: MultiplayerHubOutcome;
+    score?: number;
+    stats?: Record<string, number | string>;
+}
+export interface MultiplayerHubRecord {
+    deckId: string;
+    place: string;
+    title: string | null;
+    plays: number;
+    outcomes: {
+        win: number;
+        lose: number;
+        draw: number;
+    };
+    bestScore: number | null;
+    unit: string | null;
+    better: "higher" | "lower" | null;
+    winStreak: number;
+    lastOutcome: MultiplayerHubOutcome | null;
+    lastScore: number | null;
+    lastAt: string;
+}
+export interface MultiplayerHubResultRow {
+    deckId: string;
+    place: string;
+    title: string | null;
+    outcome: MultiplayerHubOutcome;
+    score: number | null;
+    unit: string | null;
+    better: "higher" | "lower" | null;
+    stats: Record<string, number | string>;
+    at: string;
+}
+export interface MultiplayerHubReportReceipt {
+    recorded: boolean;
+    /** Why nothing was recorded: ghost already holds this visit's result. */
+    reason?: "duplicate";
+    record?: MultiplayerHubRecord;
+}
+/**
+ * A wearable on the player's platform avatar, drawn by the hub kit in every hub
+ * place: `kind` matches /^[a-z][a-z0-9-]{0,23}$/ (the kit draws the kinds it
+ * knows), `color` is '#rrggbb', `rarity` an integer 0-9.
+ */
+export interface MultiplayerHubWearable {
+    kind: string;
+    color: string;
+    rarity: number;
+}
+export interface MultiplayerHubWearReceipt {
+    /** What the player now wears; null when cleared. */
+    wearable: MultiplayerHubWearable | null;
+}
+export interface MultiplayerHubPadUpdateInput {
+    /** A pad door of this place, from ghost's door table. */
+    doorId: string;
+    /** This gathering's id; a fired pad's group is fixed, so the next one needs a new id. */
+    padId: string;
+    /** Who stands on the pad. The host keeps only players connected to this session. */
+    memberUserIds: readonly string[];
+    /** Send the pad's players through the door now. */
+    fire?: boolean;
+}
+export interface MultiplayerHubPadUpdateResult {
+    status: "gathering" | "fired";
+    members: string[];
+}
+export interface MultiplayerHubResultsReadInput {
+    /** Players of this session to read; anyone not connected is dropped by the host. */
+    userIds?: readonly string[];
+    /** Doors of this place whose best scores to read, at most 16. */
+    doorIds?: readonly string[];
+}
+export interface MultiplayerHubPlayerResults {
+    /** Newest five results from the last hour. */
+    recent: MultiplayerHubResultRow[];
+    /** Newest twenty per-place records. */
+    records: MultiplayerHubRecord[];
+    /** The player's platform avatar, chosen or default; null when ghost has none to say. */
+    avatar: number | null;
+    /** The player's wearable; null when none. Absent from a ghost older than wearables. */
+    wearable?: MultiplayerHubWearable | null;
+}
+export interface MultiplayerHubBoard {
+    toDeckId: string;
+    title: string | null;
+    unit: string | null;
+    better: "higher" | "lower" | null;
+    top: {
+        userId: string;
+        username: string;
+        score: number;
+        at: string;
+    }[];
+    /** Featured today (the daily rotation, or set by hand). */
+    featured?: boolean;
+    /**
+     * The door row's group: the pad's minimum, the most that go through, and whether
+     * later arrivals join a running instance. Null where the row does not say; absent
+     * from a ghost older than these fields.
+     */
+    minPlayers?: number | null;
+    maxPlayers?: number | null;
+    lateJoin?: boolean;
+    /**
+     * Live presence behind the door, counts only and never who: players in the
+     * destination's public sessions from every town layer and entry, and how many of
+     * those sessions are open. Zero when nobody is inside; for an event gate, the
+     * current event's game. Absent from a ghost older than these fields.
+     */
+    playersInside?: number;
+    instancesOpen?: number;
+}
+export interface MultiplayerHubResultsRead {
+    players: Record<string, MultiplayerHubPlayerResults>;
+    boards: Record<string, MultiplayerHubBoard>;
+}
+/**
+ * The hub place this session runs, as ghost pinned it from the deck's published
+ * castle.json `hub` block. `session.hub` is null on a host without hub support
+ * and for a deck that declares no hub block.
+ */
+export interface MultiplayerServerHub {
+    readonly place: string | null;
+    readonly title: string | null;
+    readonly result: MultiplayerHubResultShape | null;
+    /** How this player came in, when ghost placed them through a door; null otherwise. */
+    arrival(playerId: string): MultiplayerHubArrival | null;
+    /**
+     * Records a signed-in player's result for this visit, once. The host checks it
+     * against the published shape; ghost keeps it only for a place behind a curated
+     * door. Rejects with the platform's `CAULDRON_HUB_*` code.
+     */
+    reportResult(playerId: string, result: MultiplayerHubResultInput): Promise<MultiplayerHubReportReceipt>;
+    /** Names who stands on a pad, and fires it. */
+    updatePad(input: MultiplayerHubPadUpdateInput): Promise<MultiplayerHubPadUpdateResult>;
+    /** Results, avatars and wearables of players here, and the boards of this place's doors. */
+    readResults(input?: MultiplayerHubResultsReadInput): Promise<MultiplayerHubResultsRead>;
+    /**
+     * Puts a wearable on a signed-in player's platform avatar in every hub place, or
+     * clears it with null; latest wins. Castle takes it only from a curated hub place.
+     * Rejects with a `CAULDRON_HUB_*` code (`CAULDRON_HUB_UNAVAILABLE` on a runtime
+     * without it).
+     */
+    wear(playerId: string, wearable: MultiplayerHubWearable | null): Promise<MultiplayerHubWearReceipt>;
+    /**
+     * Whether a block hides these two players from each other: either one blocked
+     * the other, in either direction. Symmetric. The block lists themselves stay
+     * with the host and this wrapper; a place server learns only the pair, and
+     * only for players who are both here. False on hosts that send none.
+     */
+    hiddenPair(playerIdA: string, playerIdB: string): boolean;
+}
+export declare function hubArrival(raw: unknown): MultiplayerHubArrival | null;
+export declare function recordHiddenUserIds(hidden: Map<string, ReadonlySet<string>>, playerId: string, raw: unknown): void;
+export declare function createServerHub(platformHandle: PlatformHandle, arrivals: ReadonlyMap<string, MultiplayerHubArrival>, hiddenPair?: (playerIdA: string, playerIdB: string) => boolean): MultiplayerServerHub | null;

package/dist/server/hub.js

@@ -0,0 +1,125 @@
+import { CastleError } from "../errors";
+const DOOR_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+export function hubArrival(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const { fromDeckId, doorId } = raw;
+    if (typeof fromDeckId !== "string" || fromDeckId.length === 0 || fromDeckId.length > 64) {
+        return null;
+    }
+    return Object.freeze({
+        fromDeckId,
+        doorId: typeof doorId === "string" && DOOR_ID.test(doorId) ? doorId : null,
+    });
+}
+// The co-present users a block hides from a joining hub player, as the host
+// sends them on the join (`player.hiddenUserIds`): decimal user ids, or null
+// when there are none or the list is malformed.
+const HIDDEN_USER_ID = /^\d{1,20}$/;
+const HIDDEN_USER_IDS_MAX = 1000;
+export function recordHiddenUserIds(hidden, playerId, raw) {
+    const ids = hubHiddenUserIds(raw);
+    if (ids) {
+        hidden.set(playerId, ids);
+    }
+    else {
+        hidden.delete(playerId);
+    }
+}
+function hubHiddenUserIds(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const list = raw.hiddenUserIds;
+    if (!Array.isArray(list) || list.length === 0)
+        return null;
+    const ids = new Set();
+    for (const id of list.slice(0, HIDDEN_USER_IDS_MAX)) {
+        if (typeof id === "string" && HIDDEN_USER_ID.test(id))
+            ids.add(id);
+    }
+    return ids.size > 0 ? ids : null;
+}
+export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
+    const pinned = platformHandle.hub;
+    if (!pinned ||
+        typeof platformHandle.hubResult !== "function" ||
+        typeof platformHandle.hubPadUpdate !== "function" ||
+        typeof platformHandle.hubResultsRead !== "function") {
+        return null;
+    }
+    const call = async (op, args) => {
+        const raw = await platformHandle[op](JSON.stringify(args));
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new CastleError({
+                code: "CAULDRON_HUB_INVALID_RESPONSE",
+                message: `The platform returned an invalid ${op} response.`,
+                operation: `session.hub.${op}`,
+            });
+        }
+        return parsed;
+    };
+    return Object.freeze({
+        place: typeof pinned.place === "string" ? pinned.place : null,
+        title: typeof pinned.title === "string" ? pinned.title : null,
+        result: pinned.result ?? null,
+        arrival(playerId) {
+            return arrivals.get(playerId) ?? null;
+        },
+        hiddenPair(playerIdA, playerIdB) {
+            return hiddenPair(playerIdA, playerIdB);
+        },
+        async reportResult(playerId, result) {
+            const { place, outcome, score, stats } = result ?? {};
+            return (await call("hubResult", {
+                playerId,
+                ...(place === undefined ? {} : { place }),
+                outcome,
+                ...(score === undefined || score === null ? {} : { score }),
+                ...(stats === undefined ? {} : { stats }),
+            }));
+        },
+        async updatePad(input) {
+            return (await call("hubPadUpdate", {
+                doorId: input?.doorId,
+                padId: input?.padId,
+                memberUserIds: [...(input?.memberUserIds ?? [])],
+                ...(input?.fire === true ? { fire: true } : {}),
+            }));
+        },
+        async readResults(input = {}) {
+            const read = await call("hubResultsRead", {
+                ...(input.userIds ? { userIds: [...input.userIds] } : {}),
+                ...(input.doorIds ? { doorIds: [...input.doorIds] } : {}),
+            });
+            return {
+                players: (read.players ?? {}),
+                boards: (read.boards ?? {}),
+            };
+        },
+        async wear(playerId, wearable) {
+            if (typeof platformHandle.hubWear !== "function") {
+                throw new CastleError({
+                    code: "CAULDRON_HUB_UNAVAILABLE",
+                    message: "This host's runtime cannot change wearables.",
+                    operation: "session.hub.hubWear",
+                });
+            }
+            const receipt = await call("hubWear", {
+                playerId,
+                wearable: wearable === null || wearable === undefined
+                    ? null
+                    : { kind: wearable.kind, color: wearable.color, rarity: wearable.rarity },
+            });
+            return {
+                wearable: (receipt.wearable ?? null),
+            };
+        },
+    });
+}

package/dist/server/platformHandle.d.ts

@@ -1,4 +1,5 @@
 import type { Json } from "../types";
+import type { MultiplayerWorldCharacterCommand } from "../multiplayer";
 export type MultiplayerSessionMode = "named" | "party" | "public";
 export interface PlayerIdentity {
     userId: string;
@@ -13,6 +14,16 @@ export interface PlatformSessionConfig {
     readonly tickRate: number;
     readonly maxPlayers: number;
     readonly world?: PlatformWorldSnapshot;
+    /**
+     * True when the host brokers a hub place's shared characters into this
+     * session without a world (a layer of the place). Absent on hosts that do not.
+     */
+    readonly placeCharacters?: boolean;
+    /**
+     * The place this session was started for, stamped by a host that placed it
+     * through a door (the hub's door table). Absent on hosts that do not.
+     */
+    readonly place?: string;
 }
 export interface PlatformWorldCheckpoint {
     version: number;
@@ -21,6 +32,11 @@ export interface PlatformWorldCheckpoint {
 export interface PlatformWorldSnapshot {
     revision: string;
     checkpoint: PlatformWorldCheckpoint | null;
+    /** Selected destination timing policy, stamped by hosts that support catch-up. */
+    worldTime?: PlatformWorldTimeConfig;
+}
+export interface PlatformWorldTimeConfig {
+    advance: "wallClock";
 }
 export interface PlatformHandle {
     send(connId: string, text: string): void;
@@ -28,7 +44,7 @@ export interface PlatformHandle {
     sendBinary?(connId: string, bytes: Uint8Array | ArrayBuffer): void;
     broadcastBinary?(bytes: Uint8Array | ArrayBuffer): void;
     disconnect(connId: string, code: string | number): void;
-    on(event: "join", callback: (connId: string, player: PlayerIdentity) => unknown): void;
+    on(event: "join", callback: (connId: string, player: PlayerIdentity, arrival?: PlatformHubArrival, experimentVariants?: Record<string, string>) => unknown): void;
     on(event: "leave", callback: (connId: string) => unknown): void;
     on(event: "message", callback: (connId: string, text: string) => unknown): void;
     on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
@@ -43,6 +59,8 @@ export interface PlatformHandle {
      *
      * 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.
+     * Persistent-world journal and participant operations share this broker; the
+     * host stamps their world binding and participant identity.
      */
     storage?(op: string, argsJson: string): Promise<string>;
     /** False when the host cannot broker storage, so a call can fail at once. */
@@ -56,8 +74,39 @@ export interface PlatformHandle {
     worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
     worldCharacterRuntimeList?(): Promise<string>;
     worldCharacterReject?(grantId: string, code?: string): void;
+    /**
+     * The hub place this session runs, as ghost pinned it from the published
+     * castle.json `hub` block. Present only when the host services the hub ops
+     * below, so a deck without a hub block never sees any of them.
+     */
+    readonly hub?: Readonly<PlatformHubPlace>;
+    hubResult?(argsJson: string): Promise<string>;
+    hubPadUpdate?(argsJson: string): Promise<string>;
+    hubResultsRead?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than wearables (contract v1.4). */
+    hubWear?(argsJson: string): Promise<string>;
     readonly config: PlatformSessionConfig;
 }
+export interface PlatformHubResultShape {
+    outcomes: ("win" | "lose" | "draw")[];
+    score: {
+        unit: "ms" | "s" | "points";
+        better: "higher" | "lower";
+        min: number;
+        max: number;
+    } | null;
+    stats: Record<string, "number" | "string">;
+}
+export interface PlatformHubPlace {
+    place?: string;
+    title?: string | null;
+    result?: PlatformHubResultShape | null;
+}
+/** Where a player came in, when ghost placed them through a hub door. Ghost's word, not a client's. */
+export interface PlatformHubArrival {
+    fromDeckId: string;
+    doorId?: string;
+}
 export interface PlatformWorldCharacterCommand {
     grantId: string;
     requestId: string;
@@ -65,7 +114,7 @@ export interface PlatformWorldCharacterCommand {
     speaker: PlayerIdentity & {
         playerId: string;
     };
-    command: unknown;
+    command: MultiplayerWorldCharacterCommand;
 }
 export interface PlatformWorldCharacterRead {
     grantId: string;