@arcadible/sdk 1.5.2-next.0 → 1.5.3-next.6

package/dist/tickets/client.js

@@ -0,0 +1,30 @@
+// The game's side of `tickets`: `arcadible.tickets`, a ticket for one of
+// the game's servers. The game sends it and never reads it; what it says is
+// its server's to check.
+import { ArcadibleError, Codes } from "../bus/protocol.js";
+import { isAnswer, Names, serverOf } from "./rules.js";
+// [function]
+export function createTicketsClient(bus) {
+    const tickets = {
+        async get(server) {
+            const origin = serverOf(server);
+            if (origin === null) {
+                throw new ArcadibleError(Codes.Invalid, "tickets.get takes a server's address, such as https://api.example.com.");
+            }
+            try {
+                const answer = await bus.request(Names.Get, { server: origin }, isAnswer);
+                return answer.ticket;
+            }
+            catch (err) {
+                // no page to ask (standing alone), one from before tickets, or one
+                // that didn't answer in time: there's no ticket now.
+                if (err instanceof ArcadibleError &&
+                    (err.code === Codes.Unsupported || err.code === Codes.Timeout)) {
+                    throw new ArcadibleError(Codes.Unavailable, "A ticket can't be had right now. Try again.");
+                }
+                throw err;
+            }
+        },
+    };
+    return { tickets };
+}

package/dist/tickets/rules.d.ts

@@ -0,0 +1,26 @@
+export declare const Names: {
+    readonly Get: "tickets.get";
+};
+export type TicketAnswer = {
+    ticket: string;
+};
+/**
+ * The origin of one of a game's servers, from any address of it the game
+ * fetches: `https://api.example.com/session` is `https://api.example.com`.
+ * A ticket is for the origin, so the path never matters. Any web address
+ * has one; which servers get a ticket is the page's to say (a play page
+ * takes `https` ones the game declared, a local one the developer's own
+ * machine too), so a game's copy of this never needs to change. `null` for
+ * what isn't a web address.
+ */
+export declare function serverOf(value: unknown): string | null;
+/** Whether a value is a ticket, as either end hands one over. */
+export declare function isTicket(value: unknown): value is string;
+/** Whether a value is the page's answer: a ticket. */
+export declare function isAnswer(value: unknown): value is TicketAnswer;
+/**
+ * How long a ticket is good for, in milliseconds, from its own `iat` and
+ * `exp`, read without checking it: the page only decides how long to keep
+ * it, and never trusts it. `null` when it doesn't say.
+ */
+export declare function lifetimeOf(ticket: string): number | null;

package/dist/tickets/rules.js

@@ -0,0 +1,76 @@
+// `tickets` on the bus, shared by both ends: a ticket for one of the game's
+// servers, asked for by its address.
+// [import]
+import { isObject } from "../bus/protocol.js";
+// [declare]
+export const Names = {
+    // a ticket, a request with `{ server }`, an origin, answered `{ ticket }`.
+    Get: "tickets.get",
+};
+// The longest address a game asks with, and the largest ticket a page
+// hands over: a ticket is a few hundred bytes.
+const MAX_SERVER = 2048;
+const MAX_TICKET = 4096;
+// A ticket is a JWT: three base64url parts.
+const TICKET = /^[\w-]+\.[\w-]+\.[\w-]+$/u;
+// [function]
+/**
+ * The origin of one of a game's servers, from any address of it the game
+ * fetches: `https://api.example.com/session` is `https://api.example.com`.
+ * A ticket is for the origin, so the path never matters. Any web address
+ * has one; which servers get a ticket is the page's to say (a play page
+ * takes `https` ones the game declared, a local one the developer's own
+ * machine too), so a game's copy of this never needs to change. `null` for
+ * what isn't a web address.
+ */
+export function serverOf(value) {
+    if (typeof value !== "string" || value.length > MAX_SERVER)
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.username !== "" || url.password !== "")
+        return null;
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    return url.origin;
+}
+// [function]
+/** Whether a value is a ticket, as either end hands one over. */
+export function isTicket(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_TICKET &&
+        TICKET.test(value));
+}
+// [function]
+/** Whether a value is the page's answer: a ticket. */
+export function isAnswer(value) {
+    return isObject(value) && isTicket(value["ticket"]);
+}
+// [function]
+/**
+ * How long a ticket is good for, in milliseconds, from its own `iat` and
+ * `exp`, read without checking it: the page only decides how long to keep
+ * it, and never trusts it. `null` when it doesn't say.
+ */
+export function lifetimeOf(ticket) {
+    try {
+        const part = (ticket.split(".")[1] ?? "")
+            .replace(/-/gu, "+")
+            .replace(/_/gu, "/");
+        const claims = JSON.parse(atob(part));
+        if (!isObject(claims))
+            return null;
+        const { exp, iat } = claims;
+        if (typeof exp !== "number" || typeof iat !== "number")
+            return null;
+        return exp > iat ? (exp - iat) * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/tickets/server.d.ts

@@ -0,0 +1,7 @@
+import type { Module } from "../bus/server.js";
+export type TicketsHost = {
+    mint(server: string): Promise<string>;
+    now?: () => number;
+};
+export declare const TICKET_MARGIN = 60000;
+export declare function ticketsServer(host: TicketsHost): () => Module;

package/dist/tickets/server.js

@@ -0,0 +1,76 @@
+// The page's side of `tickets`: a ticket for one of the game's servers,
+// from wherever the page gets them (`mint`), kept while it's good. The page
+// holds no key and reads no ticket: it asks, and hands over what came back.
+// [import]
+import { ArcadibleError, Codes, isObject, log, } from "../bus/protocol.js";
+import { isTicket, lifetimeOf, Names, serverOf } from "./rules.js";
+// A ticket is let go this long before it expires, so one handed over is
+// still good when it reaches the game's server.
+export const TICKET_MARGIN = 60_000;
+// The codes a page's `mint` may refuse with, which reach the game as they
+// are; anything else is `unavailable`.
+const REFUSALS = new Set([
+    Codes.Busy,
+    Codes.Invalid,
+    Codes.Unavailable,
+]);
+const REFUSED = "The play page couldn't give a ticket.";
+// [function]
+export function ticketsServer(host) {
+    const now = host.now ?? (() => Date.now());
+    // by server, for the page's life: who's playing never changes under a
+    // page, so a game that reloads in its frame is handed the same ticket.
+    const kept = new Map();
+    const asked = new Map();
+    const mint = async function (server) {
+        let ticket;
+        const at = now();
+        try {
+            ticket = await host.mint(server);
+        }
+        catch (err) {
+            if (err instanceof ArcadibleError)
+                throw err;
+            const refused = isObject(err) ? err["code"] : undefined;
+            if (typeof refused === "string" && REFUSALS.has(refused)) {
+                throw new ArcadibleError(refused, REFUSED);
+            }
+            log("warn", "a ticket couldn't be made.", err);
+            throw new ArcadibleError(Codes.Unavailable, "A ticket can't be had right now. Try again.");
+        }
+        if (!isTicket(ticket)) {
+            log("error", "the page's ticket isn't one.");
+            throw new ArcadibleError(Codes.Unavailable, "A ticket can't be had right now. Try again.");
+        }
+        // kept by its own lifetime, counted from when it was asked for, so the
+        // device's clock never matters; one that doesn't say isn't kept.
+        const lifetime = lifetimeOf(ticket);
+        if (lifetime !== null && lifetime > TICKET_MARGIN) {
+            kept.set(server, { ticket, until: at + lifetime - TICKET_MARGIN });
+        }
+        return ticket;
+    };
+    const get = async function (params) {
+        const server = serverOf(params["server"]);
+        if (server === null || server !== params["server"]) {
+            throw new ArcadibleError(Codes.Invalid, "tickets.get takes a server's origin.");
+        }
+        const held = kept.get(server);
+        if (held && now() < held.until)
+            return { ticket: held.ticket };
+        kept.delete(server);
+        // calls made at once are one mint.
+        let asking = asked.get(server);
+        if (!asking) {
+            asking = mint(server).finally(() => asked.delete(server));
+            asked.set(server, asking);
+        }
+        return { ticket: await asking };
+    };
+    return () => ({
+        handlers: {
+            // beside the queue: it waits on the network, not on storage.
+            [Names.Get]: { run: get, parallel: true },
+        },
+    });
+}

package/dist/values/client.d.ts

@@ -0,0 +1,67 @@
+import type { Bus } from "../bus/client.js";
+import type { Player } from "../players/rules.js";
+import { type Entry, type Item, type Listed, type ListOptions, type Value, type Written } from "./rules.js";
+/**
+ * Whose the values are: `"developer"`, what the game's developer published,
+ * and `"game"`, what the game shares with every player, each to read; or a
+ * player, `arcadible.players.primary`, whose own the game reads and writes.
+ */
+export type Scope = "developer" | "game" | Player;
+/** A scope's values to read: `values`' calls, with the scope already named. */
+export interface ReadableValues {
+    read(key: string): Promise<Value | null>;
+    read(keys: readonly string[]): Promise<(Value | null)[]>;
+    list(options?: ListOptions): Promise<Listed>;
+}
+/** A player's values to read and write: `values`' calls, with the player already named. */
+export interface ScopedValues extends ReadableValues {
+    write(key: string, value: unknown, options?: {
+        revision?: number;
+    }): Promise<Written>;
+    write(items: readonly Item[]): Promise<Written[]>;
+    remove(key: string | readonly string[]): Promise<void>;
+}
+/** The game's data kept on Arcadible. */
+export interface Values {
+    /**
+     * The value under a key, with its revision, or `null` for a key with
+     * none. Rejects with `denied` for a player's values while a guest plays,
+     * or for a player who isn't `players.primary`; `busy` (too many calls);
+     * or `unavailable` (offline, or off Arcadible; worth trying again).
+     */
+    read(scope: Scope, key: string): Promise<Value | null>;
+    /** The values under the keys, in their order, in one trip: each `null` for a key with none. */
+    read(scope: Scope, keys: readonly string[]): Promise<(Value | null)[]>;
+    /**
+     * Replaces a key's value, whole, in the player's own values. With
+     * `revision`, only if it's the value's now (`0`: only if there's none);
+     * otherwise it rejects with `conflict`. Also rejects with `too_large` (a
+     * value past 64 KB) and `full` (the player's storage is used up).
+     */
+    write(scope: Player, key: string, value: unknown, options?: {
+        revision?: number;
+    }): Promise<Written>;
+    /** Writes several of the player's values in one trip, all of them or none. */
+    write(scope: Player, items: readonly Item[]): Promise<Written[]>;
+    /** Removes what the key, or each of the keys, holds in the player's values, if anything. */
+    remove(scope: Player, key: string | readonly string[]): Promise<void>;
+    /**
+     * A scope's keys in order, by byte, each with its revision, time, and
+     * size, never its value: those that start with `prefix`, after the key
+     * `after`, 50 by default and 100 at most. `next` is the key to pass as
+     * `after` for the following page, or `null` at the end.
+     */
+    list(scope: Scope, options?: ListOptions): Promise<Listed>;
+    /**
+     * The same calls for one scope, named once:
+     * `values.scope(player).read(key)` is `values.read(player, key)`. The
+     * developer's and the game's have only `read` and `list`.
+     */
+    scope(scope: "developer" | "game"): ReadableValues;
+    scope(scope: Player): ScopedValues;
+}
+export type ValuesClient = {
+    values: Values;
+};
+export type { Entry, Item, Listed, ListOptions, Value, Written };
+export declare function createValuesClient(bus: Bus): ValuesClient;

package/dist/values/client.js

@@ -0,0 +1,184 @@
+// The game's side of `values`: `arcadible.values`, the game's data kept on
+// Arcadible, JSON under a key, in a scope. A game reads what its developer
+// published and what the game shares, and reads and writes its own
+// player's, wherever they play.
+import { ArcadibleError, Codes, isObject } from "../bus/protocol.js";
+import { KEY, LIST_DEFAULT, listedOf, MAX_KEYS, MAX_LIST, Names, PREFIX, valuesOf, writtenOf, } from "./rules.js";
+const UNAVAILABLE = "The game's values can't be reached right now. Try again.";
+// [function]
+function invalid(message) {
+    return new ArcadibleError(Codes.Invalid, message);
+}
+// [function]
+// what a call says of its scope: its name, and the player's id for a
+// player's.
+function scopeOf(scope) {
+    if (scope === "developer" || scope === "game")
+        return { scope };
+    if (isObject(scope) && typeof scope["id"] === "string") {
+        return { player: scope["id"], scope: "player" };
+    }
+    throw invalid('A scope is "developer", "game", or a player: arcadible.players.primary.');
+}
+// [function]
+// a call's keys: at least one, no more than a call takes, each a key, none
+// twice.
+function keysOf(keys) {
+    if (keys.length === 0)
+        throw invalid("A call names at least one key.");
+    if (keys.length > MAX_KEYS) {
+        throw new ArcadibleError(Codes.TooMany, `A call names up to ${MAX_KEYS} keys.`);
+    }
+    for (const key of keys) {
+        if (typeof key !== "string" || !KEY.test(key)) {
+            throw invalid("A key is 1 to 128 letters, digits, -, _, ., and /: " +
+                JSON.stringify(key));
+        }
+    }
+    if (new Set(keys).size !== keys.length) {
+        throw invalid("A call names each key once.");
+    }
+    return keys;
+}
+// [function]
+// a value as JSON keeps it: `undefined`, a function, or a number that isn't
+// one would be dropped or changed on the way, so each is refused here.
+function jsonOf(key, value) {
+    let text;
+    try {
+        text = JSON.stringify(value, (_, each) => {
+            if (typeof each === "number" && !Number.isFinite(each)) {
+                throw new TypeError("not finite");
+            }
+            return each;
+        });
+    }
+    catch {
+        text = undefined;
+    }
+    if (text === undefined) {
+        throw invalid(`The value for ${JSON.stringify(key)} isn't JSON.`);
+    }
+    return JSON.parse(text);
+}
+// [function]
+// the page's answer: `{ text }`, its server's answer as JSON text.
+function isAnswer(value) {
+    return isObject(value) && typeof value["text"] === "string";
+}
+// [function]
+export function createValuesClient(bus) {
+    // a call on the bus, answered with the page's server's data. With no page
+    // to ask (standing alone), one from before values, or one that didn't
+    // answer in time, the values can't be reached now.
+    const ask = async function (name, params) {
+        let text;
+        try {
+            // as text, so the call's size on the bus is its JSON's
+            text = (await bus.request(name, { body: JSON.stringify(params) }, isAnswer)).text;
+        }
+        catch (err) {
+            if (err instanceof ArcadibleError &&
+                (err.code === Codes.Unsupported || err.code === Codes.Timeout)) {
+                throw new ArcadibleError(Codes.Unavailable, UNAVAILABLE);
+            }
+            throw err;
+        }
+        // the page's server's answer, `{ data }`
+        let answer;
+        try {
+            answer = JSON.parse(text);
+        }
+        catch {
+            answer = null;
+        }
+        if (!isObject(answer) || !("data" in answer)) {
+            throw new ArcadibleError(Codes.Unavailable, UNAVAILABLE);
+        }
+        return answer["data"];
+    };
+    const unreadable = () => new ArcadibleError(Codes.Unavailable, UNAVAILABLE);
+    const read = async function (scope, key) {
+        const many = Array.isArray(key);
+        const keys = keysOf(many ? key : [key]);
+        const values = valuesOf(await ask(Names.Read, { ...scopeOf(scope), keys }), keys.length);
+        if (!values)
+            throw unreadable();
+        return many ? values : (values[0] ?? null);
+    };
+    const write = async function (scope, first, value, options) {
+        const many = Array.isArray(first);
+        const given = many
+            ? first
+            : [
+                {
+                    key: first,
+                    value,
+                    ...(options?.revision === undefined
+                        ? {}
+                        : { revision: options.revision }),
+                },
+            ];
+        if (!given.every(isObject)) {
+            throw invalid("An item to write is { key, value }, with a revision or not.");
+        }
+        const keys = keysOf(given.map((item) => item.key));
+        const items = given.map((item, at) => {
+            const { revision } = item;
+            if (revision !== undefined &&
+                (!Number.isSafeInteger(revision) || revision < 0)) {
+                throw invalid("A revision is a value's own, from a read or a write, or 0.");
+            }
+            return {
+                key: keys[at] ?? "",
+                value: jsonOf(keys[at] ?? "", item.value),
+                ...(revision === undefined ? {} : { revision }),
+            };
+        });
+        const written = writtenOf(await ask(Names.Write, { ...scopeOf(scope), items }), items.length);
+        const [only] = written ?? [];
+        if (!written || !only)
+            throw unreadable();
+        return many ? written : only;
+    };
+    const remove = async function (scope, key) {
+        const keys = keysOf(Array.isArray(key) ? key : [key]);
+        await ask(Names.Remove, { ...scopeOf(scope), keys });
+    };
+    const list = async function (scope, options = {}) {
+        const { after = "", limit = LIST_DEFAULT, prefix = "" } = options;
+        if (typeof prefix !== "string" || !PREFIX.test(prefix)) {
+            throw invalid("A prefix is what a key starts with: a key's letters.");
+        }
+        if (typeof after !== "string" || !PREFIX.test(after)) {
+            throw invalid("`after` is a key: a list's `next`.");
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST) {
+            throw invalid(`A list gives 1 to ${MAX_LIST} keys.`);
+        }
+        const listed = listedOf(await ask(Names.List, { ...scopeOf(scope), after, limit, prefix }));
+        if (!listed)
+            throw unreadable();
+        return listed;
+    };
+    // the same calls with the scope named once: nothing of its own. Every
+    // scope's has all four at run time, and the types leave `write` and
+    // `remove` off the developer's and the game's, which Arcadible refuses a
+    // game anyway.
+    const scoped = function (scope) {
+        return {
+            list: (options) => list(scope, options),
+            read: ((key) => read(scope, key)),
+            remove: (key) => remove(scope, key),
+            write: ((first, value, options) => write(scope, first, value, options)),
+        };
+    };
+    const values = {
+        list,
+        read: read,
+        remove,
+        scope: scoped,
+        write: write,
+    };
+    return { values };
+}

package/dist/values/rules.d.ts

@@ -0,0 +1,55 @@
+export declare const Names: {
+    readonly List: "values.list";
+    readonly Read: "values.read";
+    readonly Remove: "values.remove";
+    readonly Write: "values.write";
+};
+/** A value, with the revision a write may name to replace it. */
+export type Value = {
+    key: string;
+    value: unknown;
+    revision: number;
+    /** When it was written, as an ISO time. */
+    updatedAt: string;
+};
+/** What a write left: the value's new revision. */
+export type Written = {
+    key: string;
+    revision: number;
+    updatedAt: string;
+};
+/** A key in a list, without its value: its size is the value's, in bytes. */
+export type Entry = {
+    key: string;
+    revision: number;
+    updatedAt: string;
+    size: number;
+};
+/** A value to write. With `revision`, only if it's the value's now; `0`, only if there's none. */
+export type Item = {
+    key: string;
+    value: unknown;
+    revision?: number;
+};
+/** What a list takes: a prefix, the key to go on after, and how many. */
+export type ListOptions = {
+    prefix?: string;
+    after?: string;
+    limit?: number;
+};
+/** A list's page: `next` is the key to pass as `after`, or `null` at the end. */
+export type Listed = {
+    entries: Entry[];
+    next: string | null;
+};
+export declare const KEY: RegExp;
+export declare const PREFIX: RegExp;
+export declare const MAX_KEYS = 32;
+export declare const MAX_LIST = 100;
+export declare const LIST_DEFAULT = 50;
+/** A read's answer for `count` keys: each a value or `null`, or `null` for what isn't one. */
+export declare function valuesOf(data: unknown, count: number): (Value | null)[] | null;
+/** A write's answer for `count` items, or `null` for what isn't one. */
+export declare function writtenOf(data: unknown, count: number): Written[] | null;
+/** A list's answer, or `null` for what isn't one. */
+export declare function listedOf(data: unknown): Listed | null;

package/dist/values/rules.js

@@ -0,0 +1,104 @@
+// `values` on the bus, shared by both ends: a game's data kept on
+// Arcadible, JSON under a key, in a scope. A game reads the developer's
+// and the game's, and reads and writes its own player's.
+// [import]
+import { isObject } from "../bus/protocol.js";
+// [declare]
+export const Names = {
+    // each a request with `{ body }`, the call as JSON text: its scope
+    // (`scope`, and `player`, an id, for a player's), and its keys, items, or
+    // a list's options; answered `{ text }`, the page's server's answer as it
+    // came. As text, a call's size on the bus is its JSON's, which is what
+    // the limits count, and the page reads neither.
+    List: "values.list",
+    Read: "values.read",
+    Remove: "values.remove",
+    Write: "values.write",
+};
+// A key: 1 to 128 letters, digits, `-`, `_`, `.`, and `/`; and what one may
+// start with.
+export const KEY = /^[A-Za-z0-9_./-]{1,128}$/u;
+export const PREFIX = /^[A-Za-z0-9_./-]{0,128}$/u;
+// The most keys one call names, and one list gives.
+export const MAX_KEYS = 32;
+export const MAX_LIST = 100;
+export const LIST_DEFAULT = 50;
+// [function]
+// a row of an answer, as the page's server sends it, in the game's words:
+// `null` for one that isn't a row.
+function rowOf(entry) {
+    if (!isObject(entry) ||
+        typeof entry["key"] !== "string" ||
+        typeof entry["revision"] !== "number" ||
+        typeof entry["updated_at"] !== "string") {
+        return null;
+    }
+    return {
+        key: entry["key"],
+        revision: entry["revision"],
+        size: typeof entry["size"] === "number" ? entry["size"] : 0,
+        updatedAt: entry["updated_at"],
+        value: entry["value"],
+    };
+}
+// [function]
+/** A read's answer for `count` keys: each a value or `null`, or `null` for what isn't one. */
+export function valuesOf(data, count) {
+    if (!Array.isArray(data) || data.length !== count)
+        return null;
+    const values = [];
+    for (const entry of data) {
+        if (entry === null) {
+            values.push(null);
+            continue;
+        }
+        const row = rowOf(entry);
+        if (!row)
+            return null;
+        values.push({
+            key: row.key,
+            revision: row.revision,
+            updatedAt: row.updatedAt,
+            value: row.value,
+        });
+    }
+    return values;
+}
+// [function]
+/** A write's answer for `count` items, or `null` for what isn't one. */
+export function writtenOf(data, count) {
+    if (!Array.isArray(data) || data.length !== count)
+        return null;
+    const written = [];
+    for (const entry of data) {
+        const row = rowOf(entry);
+        if (!row)
+            return null;
+        written.push({
+            key: row.key,
+            revision: row.revision,
+            updatedAt: row.updatedAt,
+        });
+    }
+    return written;
+}
+// [function]
+/** A list's answer, or `null` for what isn't one. */
+export function listedOf(data) {
+    if (!isObject(data) || !Array.isArray(data["entries"]))
+        return null;
+    const entries = [];
+    for (const entry of data["entries"]) {
+        const row = rowOf(entry);
+        if (!row)
+            return null;
+        entries.push({
+            key: row.key,
+            revision: row.revision,
+            size: row.size,
+            updatedAt: row.updatedAt,
+        });
+    }
+    const next = data["next"];
+    return { entries, next: typeof next === "string" ? next : null };
+}

package/dist/values/server.d.ts

@@ -0,0 +1,7 @@
+import type { Module } from "../bus/server.js";
+/** A call's verb, as the page's server names its routes. */
+export type Verb = "list" | "read" | "remove" | "write";
+export type ValuesHost = {
+    call(verb: Verb, body: string): Promise<string>;
+};
+export declare function valuesServer(host: ValuesHost): () => Module;