castle-web-sdk 0.4.44 → 0.4.46

package/dist/save.js

@@ -0,0 +1,525 @@
+import { CastleError } from "./errors";
+import { encodeStorageValue } from "./storageJson";
+export class SaveError extends CastleError {
+    operationId;
+    retryable;
+    committed;
+    receipt;
+    retryAfterMs;
+    target;
+    constructor(envelope) {
+        super({
+            code: envelope.code,
+            message: envelope.message,
+            extensions: envelope,
+        });
+        this.name = "SaveError";
+        this.operationId = envelope.operationId;
+        this.retryable = envelope.retryable;
+        this.committed = envelope.committed;
+        this.receipt = envelope.receipt;
+        this.retryAfterMs = envelope.retryAfterMs;
+        this.target = envelope.target;
+    }
+}
+/**
+ * Reads the envelope out of whatever a host or platform threw. A failure that
+ * does not say whether it committed is treated as one that might have.
+ */
+export function asSaveError(error, operationId) {
+    if (error instanceof SaveError)
+        return error;
+    const { extensions, ...value } = error && typeof error === "object"
+        ? error
+        : {};
+    const details = {
+        ...value,
+        ...extensions,
+    };
+    const committed = details.committed;
+    return new SaveError({
+        ...details,
+        code: typeof details.code === "string"
+            ? details.code
+            : "CAULDRON_STORAGE_UNAVAILABLE",
+        message: error instanceof Error
+            ? error.message
+            : typeof details.message === "string"
+                ? details.message
+                : "Storage request failed.",
+        operationId: typeof details.operationId === "string"
+            ? details.operationId
+            : operationId,
+        retryable: details.retryable === true,
+        committed: committed === true || committed === false ? committed : "unknown",
+    });
+}
+// Copies of the platform's limits.
+const MAX_KEY_BYTES = 128;
+const MAX_SUBJECT_BYTES = 256;
+const MAX_VALUE_BYTES = 256 * 1024;
+const encoder = new TextEncoder();
+const byteLength = (text) => encoder.encode(text).length;
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+function invalid(message) {
+    throw new SaveError({
+        code: "CAULDRON_STORAGE_INVALID_ARGUMENT",
+        message,
+        retryable: false,
+        committed: false,
+    });
+}
+/** Nonempty text the platform can store: no NUL, no lone surrogate. */
+function checkText(value, field, maxBytes) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.includes("\0") ||
+        LONE_SURROGATE.test(value) ||
+        (maxBytes !== undefined && byteLength(value) > maxBytes)) {
+        invalid(`Invalid ${field}.`);
+    }
+    return value;
+}
+function checkKey(key, target) {
+    if (!checkText(key, "key", MAX_KEY_BYTES).startsWith(target.prefix)) {
+        invalid(`Key ${String(key)} is outside its target ${target.prefix}.`);
+    }
+    return key;
+}
+function checkList(value, field) {
+    if (!Array.isArray(value))
+        invalid(`${field} must be an array.`);
+    return value;
+}
+/**
+ * A session server has no current player, so it names a user target's player
+ * and cannot reach private storage.
+ */
+export function validateSaveTarget(target, server = false) {
+    if (!target || !["deck", "user", "private"].includes(target.scope)) {
+        invalid("Invalid storage scope.");
+    }
+    checkText(target.prefix, "target prefix", MAX_KEY_BYTES);
+    if (target.subject !== undefined) {
+        if (target.scope !== "user")
+            invalid("Only user targets take a subject.");
+        checkText(target.subject, "subject", MAX_SUBJECT_BYTES);
+    }
+    if (server && target.scope === "private") {
+        throw new SaveError({
+            code: "CAULDRON_STORAGE_FORBIDDEN",
+            message: "Session servers cannot access private storage.",
+            retryable: false,
+            committed: false,
+            target,
+        });
+    }
+    if (server && target.scope === "user" && target.subject === undefined) {
+        invalid("A session server's user target needs a subject.");
+    }
+    return {
+        scope: target.scope,
+        ...(target.subject === undefined ? {} : { subject: target.subject }),
+        prefix: target.prefix,
+    };
+}
+export function saveTargetKey(target) {
+    return JSON.stringify([target.scope, target.subject ?? null, target.prefix]);
+}
+/**
+ * Finds the caller's own target for one the platform names. The platform
+ * fills in the current player as a user target's subject, so a target the
+ * caller left without a subject matches any subject.
+ */
+export function matchSaveTarget(target, candidates) {
+    const scope = String(target.scope).toLowerCase();
+    const sameTarget = (candidate) => candidate.scope === scope && candidate.prefix === target.prefix;
+    const found = candidates.find((candidate) => sameTarget(candidate) && candidate.subject === target.subject) ??
+        candidates.find((candidate) => sameTarget(candidate) && candidate.subject === undefined);
+    if (found)
+        return found;
+    return {
+        scope,
+        ...(scope === "user" && target.subject ? { subject: target.subject } : {}),
+        prefix: target.prefix,
+    };
+}
+// Encoding a value also copies it, so later changes to the caller's object
+// cannot reach a request that is waiting to be sent.
+function encodeRows(rows, target) {
+    if (!rows || typeof rows !== "object" || Array.isArray(rows)) {
+        invalid("Rows must be an object of keys to JSON values.");
+    }
+    const encoded = {};
+    for (const [key, value] of Object.entries(rows)) {
+        checkKey(key, target);
+        let text;
+        try {
+            text = encodeStorageValue(value, "Store.save");
+        }
+        catch (error) {
+            throw new SaveError({
+                code: error instanceof CastleError
+                    ? error.code
+                    : "CAULDRON_STORAGE_INVALID_VALUE",
+                message: error instanceof Error ? error.message : "Invalid JSON value.",
+                retryable: false,
+                committed: false,
+            });
+        }
+        if (byteLength(text) > MAX_VALUE_BYTES) {
+            invalid(`The value of ${key} is over 256 KiB.`);
+        }
+        encoded[key] = JSON.parse(text);
+    }
+    return encoded;
+}
+function encodeReads(reads, server) {
+    return checkList(reads, "load").map((value) => {
+        const read = value;
+        const target = validateSaveTarget(read.target, server);
+        const select = read.select;
+        if (select === undefined)
+            return { target };
+        if ("prefix" in select === "keys" in select) {
+            invalid("A selection has either keys or a prefix.");
+        }
+        if ("prefix" in select) {
+            checkKey(select.prefix, target);
+            return { target, select: { prefix: select.prefix } };
+        }
+        const keys = checkList(select.keys, "selection keys");
+        return {
+            target,
+            select: { keys: keys.map((key) => checkKey(key, target)) },
+        };
+    });
+}
+function encodeInitial(initial, server) {
+    const seen = new Set();
+    return checkList(initial, "initial").map((value) => {
+        const entry = value;
+        const target = validateSaveTarget(entry.target, server);
+        if (seen.has(saveTargetKey(target))) {
+            invalid("Each initial target appears once.");
+        }
+        seen.add(saveTargetKey(target));
+        return { target, rows: encodeRows(entry.rows, target) };
+    });
+}
+function encodeChange(change, server) {
+    const target = validateSaveTarget(change.target, server);
+    if (change.expectedRevision !== null) {
+        checkText(change.expectedRevision, "expected revision");
+    }
+    if (change.writer !== undefined)
+        checkText(change.writer, "writer");
+    if (change.replace !== undefined) {
+        if (change.put !== undefined || change.remove !== undefined) {
+            invalid("replace cannot be combined with put or remove.");
+        }
+        return {
+            target,
+            expectedRevision: change.expectedRevision,
+            ...(change.writer === undefined ? {} : { writer: change.writer }),
+            replace: encodeRows(change.replace, target),
+        };
+    }
+    const put = change.put === undefined ? undefined : encodeRows(change.put, target);
+    const remove = change.remove === undefined
+        ? undefined
+        : checkList(change.remove, "remove").map((key) => checkKey(key, target));
+    if (remove?.some((key) => put && Object.hasOwn(put, key))) {
+        invalid("A key cannot be both put and removed.");
+    }
+    return {
+        target,
+        expectedRevision: change.expectedRevision,
+        ...(change.writer === undefined ? {} : { writer: change.writer }),
+        ...(put === undefined ? {} : { put }),
+        ...(remove === undefined ? {} : { remove }),
+    };
+}
+function encodeCheck(check, server) {
+    const target = validateSaveTarget(check.target, server);
+    if (check.expectedRevision === undefined && check.writer === undefined) {
+        invalid("A check needs an expected revision or a writer.");
+    }
+    if (check.expectedRevision !== undefined) {
+        checkText(check.expectedRevision, "expected revision");
+    }
+    if (check.writer !== undefined)
+        checkText(check.writer, "writer");
+    return {
+        target,
+        ...(check.expectedRevision === undefined
+            ? {}
+            : { expectedRevision: check.expectedRevision }),
+        ...(check.writer === undefined ? {} : { writer: check.writer }),
+    };
+}
+function encodeTransaction(input, server) {
+    const changes = checkList(input.changes, "changes").map((change) => encodeChange(change, server));
+    const keys = changes.map((change) => saveTargetKey(change.target));
+    if (new Set(keys).size !== keys.length) {
+        invalid("Each changed target appears once.");
+    }
+    return {
+        operationId: input.operationId,
+        expectedAccess: checkText(input.expectedAccess, "expected access"),
+        ...(input.checks === undefined
+            ? {}
+            : {
+                checks: checkList(input.checks, "checks").map((check) => encodeCheck(check, server)),
+            }),
+        changes,
+    };
+}
+/** Validates and copies a request; the result is what goes on the wire. */
+export function encodeSaveInput(verb, input, server = false) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        invalid("Save input must be an object.");
+    }
+    if (verb === "snapshot")
+        return { targets: encodeReads(input.targets, server) };
+    checkText(input.operationId, "operation id", MAX_KEY_BYTES);
+    if (verb === "operation")
+        return { operationId: input.operationId };
+    if (verb === "transaction") {
+        return {
+            ...encodeTransaction(input, server),
+        };
+    }
+    if (input.expectedAccess !== undefined) {
+        checkText(input.expectedAccess, "expected access");
+    }
+    if (verb === "initialize" && input.initial === undefined) {
+        invalid("initialize needs initial targets.");
+    }
+    return {
+        operationId: input.operationId,
+        ...(input.expectedAccess === undefined
+            ? {}
+            : { expectedAccess: input.expectedAccess }),
+        ...(verb === "claim"
+            ? { target: validateSaveTarget(input.target, server) }
+            : {}),
+        ...(input.initial === undefined
+            ? {}
+            : { initial: encodeInitial(input.initial, server) }),
+        ...(input.load === undefined
+            ? {}
+            : { load: encodeReads(input.load, server) }),
+    };
+}
+function invalidResponse() {
+    throw new SaveError({
+        code: "CAULDRON_STORAGE_INVALID_RESPONSE",
+        message: "Storage returned an invalid save response.",
+        retryable: false,
+        committed: "unknown",
+    });
+}
+function isPlatformTarget(target) {
+    const value = target;
+    return (!!value &&
+        typeof value.scope === "string" &&
+        ["deck", "user", "private"].includes(value.scope.toLowerCase()) &&
+        typeof value.prefix === "string" &&
+        value.prefix.length > 0);
+}
+// Snapshot targets come back in the order they were read, which is how each
+// is matched to the caller's own target.
+function decodeSnapshot(value, reads) {
+    const snapshot = value;
+    if (!snapshot ||
+        typeof snapshot.access !== "string" ||
+        !Array.isArray(snapshot.targets) ||
+        snapshot.targets.length !== reads.length) {
+        invalidResponse();
+    }
+    return {
+        access: snapshot.access,
+        targets: snapshot.targets.map((entry, index) => {
+            const read = reads[index].target;
+            if (!entry ||
+                !isPlatformTarget(entry.target) ||
+                entry.target.prefix !== read.prefix ||
+                entry.target.scope.toLowerCase() !== read.scope ||
+                (entry.revision !== null && typeof entry.revision !== "string") ||
+                typeof entry.complete !== "boolean" ||
+                !entry.rows ||
+                typeof entry.rows !== "object" ||
+                Array.isArray(entry.rows)) {
+                invalidResponse();
+            }
+            return {
+                target: read,
+                revision: entry.revision,
+                rows: entry.rows,
+                complete: entry.complete,
+            };
+        }),
+    };
+}
+function decodeReceipt(value, operationId, targets) {
+    const receipt = value;
+    if (!receipt ||
+        receipt.operationId !== operationId ||
+        typeof receipt.access !== "string" ||
+        !Array.isArray(receipt.revisions) ||
+        receipt.revisions.some((entry) => !isPlatformTarget(entry?.target) || typeof entry.revision !== "string")) {
+        invalidResponse();
+    }
+    return {
+        operationId: receipt.operationId,
+        access: receipt.access,
+        revisions: receipt.revisions.map((entry) => ({
+            target: matchSaveTarget(entry.target, targets),
+            revision: entry.revision,
+        })),
+        ...(typeof receipt.writer === "string" ? { writer: receipt.writer } : {}),
+    };
+}
+function decodeOpened(value, operationId, targets, reads) {
+    const opened = value;
+    if (!opened)
+        invalidResponse();
+    return {
+        receipt: decodeReceipt(opened.receipt, operationId, targets),
+        snapshot: decodeSnapshot(opened.snapshot, reads),
+        ...(typeof opened.writer === "string" ? { writer: opened.writer } : {}),
+    };
+}
+function defaultLoad(targets) {
+    const unique = new Map(targets.map((target) => [saveTargetKey(target), target]));
+    return [...unique.values()].map((target) => ({ target }));
+}
+export function createSaveApi(call, server = false) {
+    async function send(verb, input) {
+        const operationId = typeof input?.operationId === "string" ? input.operationId : undefined;
+        let encoded;
+        try {
+            encoded = encodeSaveInput(verb, input, server);
+        }
+        catch (error) {
+            // Nothing was sent.
+            const failure = asSaveError(error);
+            throw new SaveError({
+                ...failure.extensions,
+                code: failure.code,
+                message: failure.message,
+                operationId,
+                retryable: false,
+                committed: false,
+            });
+        }
+        try {
+            return await call(verb, encoded);
+        }
+        catch (error) {
+            throw asSaveError(error, operationId);
+        }
+    }
+    return {
+        async snapshot(input) {
+            return decodeSnapshot(await send("snapshot", { ...input }), input.targets);
+        },
+        async transaction(input) {
+            const result = await send("transaction", { ...input });
+            return decodeReceipt(result, input.operationId, input.changes.map((change) => change.target));
+        },
+        async claim(input) {
+            const initial = (input.initial ?? []).map((entry) => entry.target);
+            const load = input.load ?? defaultLoad([input.target, ...initial]);
+            const result = await send("claim", { ...input, load });
+            const opened = decodeOpened(result, input.operationId, [input.target, ...initial], load);
+            if (opened.writer === undefined)
+                invalidResponse();
+            return { ...opened, writer: opened.writer };
+        },
+        async initialize(input) {
+            const initial = input.initial.map((entry) => entry.target);
+            const load = input.load ?? defaultLoad(initial);
+            const result = await send("initialize", { ...input, load });
+            const { receipt, snapshot } = decodeOpened(result, input.operationId, initial, load);
+            return { receipt, snapshot };
+        },
+        async operation(operationId) {
+            const result = (await send("operation", {
+                operationId,
+            }));
+            if (result?.state === "unknown")
+                return { state: "unknown" };
+            if (result?.state !== "committed")
+                invalidResponse();
+            return {
+                state: "committed",
+                receipt: decodeReceipt(result.receipt, operationId, []),
+            };
+        },
+    };
+}
+export function createSaveBucket(api, scope, subject) {
+    const target = (prefix) => ({
+        scope,
+        ...(subject === undefined ? {} : { subject }),
+        prefix,
+    });
+    const read = ({ prefix, select }) => ({
+        target: target(prefix),
+        ...(select ? { select } : {}),
+    });
+    const initial = (entries) => entries.map(({ prefix, rows }) => ({ target: target(prefix), rows }));
+    return {
+        target,
+        snapshot: (input) => api.snapshot({ targets: [read(input)] }),
+        transaction: ({ checks, changes, ...input }) => api.transaction({
+            ...input,
+            ...(checks
+                ? {
+                    checks: checks.map(({ prefix, ...check }) => ({
+                        ...check,
+                        target: target(prefix),
+                    })),
+                }
+                : {}),
+            changes: changes.map(({ prefix, ...change }) => ({
+                ...change,
+                target: target(prefix),
+            })),
+        }),
+        claim: ({ prefix, initial: entries, load, ...input }) => api.claim({
+            ...input,
+            target: target(prefix),
+            ...(entries ? { initial: initial(entries) } : {}),
+            ...(load ? { load: load.map(read) } : {}),
+        }),
+        initialize: ({ initial: entries, load, ...input }) => api.initialize({
+            ...input,
+            initial: initial(entries),
+            ...(load ? { load: load.map(read) } : {}),
+        }),
+        operation: (operationId) => api.operation(operationId),
+    };
+}
+/**
+ * Refuses a request bigger than a transport carries. An atomic save is never
+ * split, so the whole encoded request has to fit.
+ */
+export function preflightSaveRequest(verb, request, limitBytes) {
+    const encodedBytes = byteLength(JSON.stringify(request));
+    if (encodedBytes <= limitBytes)
+        return;
+    const wire = request;
+    const operationId = wire.input?.operationId ?? wire.operationId;
+    throw new SaveError({
+        code: "CAULDRON_STORAGE_TOO_LARGE",
+        message: `The ${verb} request is ${encodedBytes} bytes, over this transport's ${limitBytes}.`,
+        operationId: typeof operationId === "string" ? operationId : undefined,
+        retryable: false,
+        committed: false,
+        encodedBytes,
+        limitBytes,
+    });
+}

package/dist/saveCoordinator.d.ts

@@ -0,0 +1,39 @@
+import { SaveError } from "./save";
+import type { SaveApi, SaveChange, SaveCheck, SaveReceipt, SaveRevision, SaveSnapshot, SaveTarget, SaveWriter } from "./save";
+export type SaveStatus = "pending" | "saved" | "blocked";
+export type CoordinatedChange = Omit<SaveChange, "expectedRevision"> & {
+    /** Omitted takes the target's revision from the latest receipt. */
+    expectedRevision?: SaveRevision | null;
+};
+export interface CoordinatedSave {
+    operationId: string;
+    changes: CoordinatedChange[];
+    checks?: SaveCheck[];
+}
+export interface SaveCoordinator {
+    readonly status: SaveStatus;
+    /** The failure that blocks the queue. */
+    readonly error: SaveError | undefined;
+    readonly pendingOperationIds: readonly string[];
+    /** The latest revision this coordinator knows for a target. */
+    revision(target: SaveTarget): SaveRevision | null | undefined;
+    /** Resolves with the receipt once the save commits. */
+    submit(input: CoordinatedSave): Promise<SaveReceipt>;
+    /**
+     * Resolves once every save submitted before this call has committed, and
+     * rejects if the queue blocks first. Later saves do not hold it up.
+     */
+    flush(): Promise<void>;
+    /** Sends the blocking save again, with its original id and input. */
+    retry(): Promise<void>;
+    /** Drops queued saves that have not been sent. A sent save still settles. */
+    discardUnsent(): void;
+}
+/**
+ * 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 declare function createSaveCoordinator(api: SaveApi, snapshot: SaveSnapshot, writers?: {
+    target: SaveTarget;
+    writer: SaveWriter;
+}[]): SaveCoordinator;