castle-web-sdk 0.4.45 → 0.4.47

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,256 @@
+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;
+}
+/** The classes of earned item a hub game may give (contract v1.53). */
+export type MultiplayerHubEarnedClass = "badge" | "pin" | "belt" | "sash" | "held";
+/** The home classes a hub game may give (contract v1.70/v1.73), never worn. */
+export type MultiplayerHubHomeClass = "furniture" | "deed" | "pet";
+/**
+ * An earned item: something a hub game gave a player for a stated deed, declared
+ * in that game's castle.json `hub.unlocks` and kept by Castle per account. It has
+ * no rarity. `deckId` is the game that declared it; `id` and `shape` match
+ * /^[a-z][a-z0-9-]{0,23}$/, `color` is '#rrggbb'.
+ */
+export interface MultiplayerHubEarnedItem {
+    deckId: string;
+    id: string;
+    class: MultiplayerHubEarnedClass;
+    shape: string;
+    name: string;
+    deed: string;
+    color: string;
+}
+/** A furniture piece, area deed or adopted pet owned for the house, never shown on an avatar. */
+export interface MultiplayerHubHomeItem {
+    deckId: string;
+    id: string;
+    class: MultiplayerHubHomeClass;
+    piece: string;
+    name: string;
+    deed: string;
+    color: string;
+}
+export interface MultiplayerHubUnlockReceipt {
+    unlocked: true;
+    /** True when this call gave the player the item for the first time. */
+    isNew: boolean;
+    /** What the player now shows in the earned slot (never a home item); null when none. */
+    earned: MultiplayerHubEarnedItem | null;
+}
+export interface MultiplayerHubWearEarnedReceipt {
+    /** What the player now shows in the earned slot; null when cleared. */
+    earned: MultiplayerHubEarnedItem | null;
+}
+export interface MultiplayerHubUnlocksRead {
+    /** Each player's owned wearable and home items, by user id. */
+    players: Record<string, {
+        owned: (MultiplayerHubEarnedItem | MultiplayerHubHomeItem)[];
+    }>;
+}
+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;
+    /** Account-wide door hearts, oldest first; absent on older ghosts. */
+    hearts?: string[];
+    /** The player's wearable; null when none. Absent from a ghost older than wearables. */
+    wearable?: MultiplayerHubWearable | null;
+    /** The earned item the player shows (contract v1.53); absent when none. */
+    earned?: MultiplayerHubEarnedItem;
+}
+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 {
+    /** The owner user id, only in an owner door instance. */
+    readonly owner?: string;
+    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>;
+    /**
+     * Gives a signed-in player one of this deck's declared earned items (castle.json
+     * `hub.unlocks`), by its id. Castle takes it only from a curated hub place, for a
+     * declared id; a first wearable unlock is also shown. Home items are never worn.
+     * Rejects with a `CAULDRON_HUB_*` code
+     * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    unlock(playerId: string, itemId: string): Promise<MultiplayerHubUnlockReceipt>;
+    /**
+     * Chooses which owned earned item a signed-in player shows, or none with null.
+     * Castle takes it only from the town; home items are refused.
+     * Rejects with a `CAULDRON_HUB_*` code
+     * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    wearEarned(playerId: string, earned: {
+        deckId: string;
+        id: string;
+    } | null): Promise<MultiplayerHubWearEarnedReceipt>;
+    /**
+     * The earned items players here own, by user id. Rejects with a `CAULDRON_HUB_*`
+     * code (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    readUnlocks(userIds: readonly string[]): Promise<MultiplayerHubUnlocksRead>;
+    /** The connected player's friends among these candidates; platform refusals reject. */
+    friendsAmong(playerId: string, userIds: readonly string[]): Promise<string[]>;
+    /**
+     * The connected player's mutual friends and follows in either direction among
+     * these candidates, in one host read. Missing lists are empty; refusals reject.
+     * These relations belong to this player only; never send them to another client.
+     */
+    relationsAmong(playerId: string, userIds: readonly string[]): Promise<{
+        friends: string[];
+        follows: string[];
+        followedBy: string[];
+    }>;
+    /**
+     * 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;