@net-mesh/browser 0.37.0

package/dist/lobby.js

@@ -0,0 +1,504 @@
+/**
+ * Lobbies: host a game others can find, list the open ones, join by
+ * code or link.
+ *
+ * ```ts
+ * const lobby = await createLobby({ node, game: 'arena', name: 'Friday arena', capacity: 8,
+ *   definition, initialState, actions, inputs, project });
+ * lobby.code;            // 'K7QP2M' — say it out loud, or share lobby.link()
+ * const me = lobby.self; // the host's own player, same shape as a joined one
+ *
+ * const open = await listLobbies({ node, game: 'arena' });
+ * const world = await joinLobby({ node, definition, code: 'K7QP2M' });
+ * ```
+ *
+ * A thin layer over what already exists — `hostStore`, `hostPlayer`,
+ * `joinStore`, `announce` and `query` — and no new protocol. A lobby is
+ * found through capability tags, which are free-form strings the mesh
+ * carries in a node's signed announcement:
+ *
+ * - `net-lobby:<game>` — the listing tag; public lobbies only.
+ * - `net-lobby:<game>:rec:<base64url JSON>` — the record a list shows:
+ *   code, name, players, capacity, store version and the game's own
+ *   `info`. Public lobbies only.
+ * - `net-lobby:<game>:seek:<host hex>` — announced by a player joining that
+ *   host. A browser node accepts a relayed handshake only from a peer whose
+ *   signed announcement it holds, and the anchor delivers announcements to
+ *   its peers — so a joiner that announces nothing cannot reach the host
+ *   (measured: `examples/anchor-acceptance`). The tag says why this player
+ *   announces at all.
+ * - `net-lobby:<game>:code:<32 hex>` — the code, hashed; how a code is
+ *   looked up. Both kinds announce it.
+ *
+ * **What a listing is.** Anyone on the mesh can announce any tag, so a
+ * record is a claim. The host id beside it is not: it comes from the
+ * signed announcement. Records are validated and bounded before they
+ * are shown, and joining connects to the announcing node, whose store
+ * then answers for itself.
+ *
+ * **Unlisted is not secret.** An unlisted lobby publishes no record, so
+ * it never appears in a list — but a 6-character code can be guessed
+ * against its hash, and the anchor relays every announcement. Who may
+ * join is decided by `authorize`, as for any store.
+ *
+ * **One lobby per node.** `announce` replaces a node's tags, so the
+ * lobby owns its node's announcement while it is open; pass any other
+ * tags the node should keep announcing as `tags`.
+ */
+import { StoreError } from './store/errors.js';
+import { hostInternals, hostStore, } from './store/host.js';
+import { joinStore } from './store/join.js';
+import { hostPlayer } from './store/player.js';
+export class LobbyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LobbyError';
+    }
+}
+/** Bounds on what a lobby may publish (Q4 in the lobbies plan). */
+export const MAX_LOBBY_NAME_CHARS = 64;
+export const MAX_LOBBY_INFO_BYTES = 256;
+export const MAX_LOBBY_RECORD_TAG_BYTES = 512;
+export const MAX_LOBBY_CAPACITY = 256;
+/** Characters a code is made of: no 0/O, 1/I/L, so a code survives being read aloud. */
+export const LOBBY_CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+export const LOBBY_CODE_LENGTH = 6;
+/** How often a lobby re-announces itself. */
+export const LOBBY_ANNOUNCE_MS = 2_000;
+/** The frame bound the package's own tests and demo use. */
+const DEFAULT_MAX_EVENT_BYTES = 8104;
+const GAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const RECORD_VERSION = 1;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function checkGame(game) {
+    if (!GAME.test(game)) {
+        throw new LobbyError('invalid', `a game name is 1-64 of a-z 0-9 . _ - (starting with a letter or digit), got ${JSON.stringify(game)}`);
+    }
+}
+/** A code as typed: case, spaces and dashes forgiven. */
+export function normalizeLobbyCode(code) {
+    const cleaned = code.toUpperCase().replace(/[\s-]/g, '');
+    if (cleaned.length !== LOBBY_CODE_LENGTH || [...cleaned].some(c => !LOBBY_CODE_ALPHABET.includes(c))) {
+        throw new LobbyError('invalid', `not a lobby code: ${JSON.stringify(code)}`);
+    }
+    return cleaned;
+}
+function randomCode() {
+    // Rejection sampling, so every character is equally likely.
+    const limit = 256 - (256 % LOBBY_CODE_ALPHABET.length);
+    let code = '';
+    while (code.length < LOBBY_CODE_LENGTH) {
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        for (const byte of bytes) {
+            if (byte < limit && code.length < LOBBY_CODE_LENGTH)
+                code += LOBBY_CODE_ALPHABET[byte % LOBBY_CODE_ALPHABET.length];
+        }
+    }
+    return code;
+}
+/** A player joining `host` announces this, so the host can discover it. */
+function seekTag(game, host) {
+    return `net-lobby:${game}:seek:${host}`;
+}
+function listingTag(game) {
+    return `net-lobby:${game}`;
+}
+function recordPrefix(game) {
+    return `net-lobby:${game}:rec:`;
+}
+async function codeTag(game, code) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(`net-lobby\u001f${game}\u001f${code}`)));
+    let hex = '';
+    for (const byte of digest.subarray(0, 16))
+        hex += byte.toString(16).padStart(2, '0');
+    return `net-lobby:${game}:code:${hex}`;
+}
+function base64url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64url(text) {
+    if (!/^[A-Za-z0-9_-]*$/.test(text))
+        return null;
+    try {
+        const binary = atob(text.replace(/-/g, '+').replace(/_/g, '/'));
+        return Uint8Array.from(binary, c => c.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+function checkInfo(info) {
+    if (typeof info !== 'object' || info === null || Array.isArray(info)) {
+        throw new LobbyError('invalid', 'lobby info is a flat object of strings, numbers and booleans');
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(info)) {
+        if (typeof value === 'number' ? !Number.isFinite(value) : typeof value !== 'string' && typeof value !== 'boolean') {
+            throw new LobbyError('invalid', `lobby info.${key} must be a string, a finite number or a boolean`);
+        }
+        out[key] = value;
+    }
+    if (encoder.encode(JSON.stringify(out)).length > MAX_LOBBY_INFO_BYTES) {
+        throw new LobbyError('invalid', `lobby info is over ${MAX_LOBBY_INFO_BYTES} bytes of JSON`);
+    }
+    return Object.freeze(out);
+}
+function checkName(name) {
+    if (typeof name !== 'string' || name.trim().length === 0 || [...name].length > MAX_LOBBY_NAME_CHARS) {
+        throw new LobbyError('invalid', `a lobby name is 1-${MAX_LOBBY_NAME_CHARS} characters`);
+    }
+    return name;
+}
+function checkCapacity(capacity) {
+    if (typeof capacity !== 'number' || !Number.isInteger(capacity) || capacity < 1 || capacity > MAX_LOBBY_CAPACITY) {
+        throw new LobbyError('invalid', `capacity is a whole number from 1 to ${MAX_LOBBY_CAPACITY}`);
+    }
+    return capacity;
+}
+function encodeRecord(game, record) {
+    const json = JSON.stringify({
+        v: RECORD_VERSION,
+        c: record.code,
+        n: record.name,
+        p: record.players,
+        m: record.capacity,
+        s: record.store,
+        i: record.info,
+    });
+    const tag = recordPrefix(game) + base64url(encoder.encode(json));
+    if (encoder.encode(tag).length > MAX_LOBBY_RECORD_TAG_BYTES) {
+        throw new LobbyError('invalid', `the lobby record is over ${MAX_LOBBY_RECORD_TAG_BYTES} bytes: shorten the name or info`);
+    }
+    return tag;
+}
+/** A record from someone else's announcement: every field checked, or nothing. */
+function decodeRecord(game, tag) {
+    if (encoder.encode(tag).length > MAX_LOBBY_RECORD_TAG_BYTES)
+        return null;
+    const bytes = fromBase64url(tag.slice(recordPrefix(game).length));
+    if (bytes === null)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(decoder.decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    try {
+        if (r.v !== RECORD_VERSION || typeof r.c !== 'string' || typeof r.s !== 'string' || r.s.length > 200)
+            return null;
+        const capacity = checkCapacity(r.m);
+        const players = r.p;
+        if (typeof players !== 'number' || !Number.isInteger(players) || players < 0 || players > capacity)
+            return null;
+        return {
+            code: normalizeLobbyCode(r.c),
+            name: checkName(r.n),
+            players,
+            capacity,
+            store: r.s,
+            info: checkInfo(r.i ?? {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function hexPeer(peer) {
+    const raw = peer.startsWith('0x') ? peer.slice(2) : peer;
+    if (/^[0-9a-fA-F]{1,16}$/.test(raw))
+        return raw.toLowerCase().padStart(16, '0');
+    throw new LobbyError('invalid', `not a peer id: ${JSON.stringify(peer)}`);
+}
+/**
+ * Open a lobby: host the store on `node`, give the host its own
+ * player, and announce the lobby until it closes.
+ */
+export async function createLobby(options) {
+    const { node, game } = options;
+    checkGame(game);
+    const name = checkName(options.name);
+    const capacity = checkCapacity(options.capacity);
+    const info = checkInfo(options.info ?? {});
+    const visibility = options.visibility ?? 'public';
+    const code = randomCode();
+    const store = `${options.definition.id}@${options.definition.version}`;
+    const lookup = await codeTag(game, code);
+    // Refuse an unpublishable record now, where the mistake is legible,
+    // rather than from inside the first announcement.
+    encodeRecord(game, { code, name, players: capacity, capacity, store, info });
+    const self = node.nodeIdHex();
+    if (self === null)
+        throw new LobbyError('invalid', 'the node has no id yet: connect it before opening a lobby');
+    const selfHex = hexPeer(self);
+    const kicked = new Set();
+    const policy = options.authorize ?? (() => true);
+    // Assigned right after the store exists; `authorize` is not called
+    // before a join arrives.
+    let peersNow = () => [];
+    const authorize = (request) => {
+        const peer = request.peer;
+        if (kicked.has(peer))
+            return false;
+        if (request.type === 'read' && peer !== selfHex && !peersNow().includes(peer)) {
+            // A NEW player: is there room? The host is one of `capacity`.
+            const others = peersNow().filter(existing => existing !== selfHex).length;
+            if (1 + others >= capacity)
+                return false;
+        }
+        return policy(request);
+    };
+    const { audience, tags, announceEveryMs, maxEventBytes } = options;
+    // The store's own options pass through untouched; the lobby's are
+    // not the store's business.
+    const { node: _node, game: _game, name: _name, capacity: _capacity, visibility: _visibility, info: _info, audience: _audience, tags: _tags, announceEveryMs: _every, maxEventBytes: _max, authorize: _policy, ...storeOptions } = options;
+    const host = hostStore({
+        ...storeOptions,
+        transport: node,
+        maxEventBytes: maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES,
+        authorize,
+    });
+    const inner = hostInternals(host);
+    peersNow = () => inner.owner.peers();
+    const me = hostPlayer(host, { audience: audience ?? [] });
+    function players() {
+        return [selfHex, ...inner.owner.peers().filter(peer => peer !== selfHex)];
+    }
+    const listeners = new Set();
+    let closed = false;
+    let announcing = null;
+    let again = false;
+    function currentTags() {
+        const list = [...(tags ?? []), lookup];
+        if (visibility === 'public') {
+            list.push(listingTag(game), encodeRecord(game, { code, name, players: players().length, capacity, store, info }));
+        }
+        return list;
+    }
+    /** One announcement at a time; a change during one is announced after it. */
+    function announce() {
+        if (closed)
+            return;
+        if (announcing !== null) {
+            again = true;
+            return;
+        }
+        announcing = node
+            .announce(currentTags())
+            .catch(() => {
+            // The next tick tries again; a lobby that cannot announce is
+            // simply not found, which the joiner reports as `not-found`.
+        })
+            .finally(() => {
+            announcing = null;
+            if (again) {
+                again = false;
+                announce();
+            }
+        });
+    }
+    let last = players().join();
+    const stopMembership = inner.owner.onMembership(() => {
+        // Inside the owner's frame: read, compare, and defer everything
+        // else to a later turn.
+        queueMicrotask(() => {
+            if (closed)
+                return;
+            const now = players();
+            if (now.join() === last)
+                return;
+            last = now.join();
+            announce();
+            for (const listener of [...listeners]) {
+                try {
+                    listener(now);
+                }
+                catch {
+                    // A UI listener's failure is not the lobby's.
+                }
+            }
+        });
+    });
+    announce();
+    const timer = setInterval(announce, announceEveryMs ?? LOBBY_ANNOUNCE_MS);
+    return {
+        code,
+        game,
+        visibility,
+        host,
+        self: me,
+        players,
+        subscribePlayers: listener => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        link: base => {
+            const url = new URL(base ?? globalThis.location?.href ?? 'about:blank');
+            url.searchParams.set('lobby', code);
+            return url.toString();
+        },
+        kick: peer => {
+            const target = hexPeer(peer);
+            if (target === selfHex)
+                throw new LobbyError('invalid', 'the host cannot kick itself; close the lobby instead');
+            kicked.add(target);
+            inner.dispatched(inner.owner.reauthorize());
+        },
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(timer);
+            stopMembership();
+            listeners.clear();
+            await me.close();
+            await host.close();
+            // Withdraw the lobby: announce only what the node keeps.
+            await node.announce([...(tags ?? [])]).catch(() => { });
+        },
+    };
+}
+/** The open public lobbies of `game`, as their hosts last announced them. */
+export async function listLobbies(options) {
+    checkGame(options.game);
+    const prefix = recordPrefix(options.game);
+    const found = [];
+    const seen = new Set();
+    for (const descriptor of await options.node.query(listingTag(options.game))) {
+        if (seen.has(descriptor.peerIdHex))
+            continue;
+        const tag = descriptor.capabilities.find(candidate => candidate.startsWith(prefix));
+        if (tag === undefined)
+            continue;
+        const record = decodeRecord(options.game, tag);
+        if (record === null)
+            continue;
+        seen.add(descriptor.peerIdHex);
+        found.push({ ...record, host: descriptor.peerIdHex });
+    }
+    return found;
+}
+/**
+ * Join a lobby by code or by listing. Resolves once the host is found
+ * and the join is sent; await `ready()` on the result for the world.
+ */
+export async function joinLobby(options) {
+    checkGame(options.game);
+    let host;
+    if (options.lobby !== undefined) {
+        host = hexPeer(options.lobby.host);
+    }
+    else if (options.code !== undefined) {
+        const tag = await codeTag(options.game, normalizeLobbyCode(options.code));
+        const deadline = Date.now() + (options.timeoutMs ?? 20_000);
+        let hosts = [];
+        for (;;) {
+            hosts = [...new Set((await options.node.query(tag)).map(descriptor => descriptor.peerIdHex))];
+            if (hosts.length > 0 || Date.now() >= deadline)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+        if (hosts.length === 0)
+            throw new LobbyError('not-found', `no lobby answered to code ${options.code}`);
+        if (hosts.length > 1) {
+            // Anyone can announce any tag. Two nodes claiming one code is
+            // either a collision or an impersonation, and joining either
+            // could hand this player to the wrong host.
+            throw new LobbyError('ambiguous', `${hosts.length} nodes claim code ${options.code}; join from the list instead`);
+        }
+        host = hosts[0];
+    }
+    else {
+        throw new LobbyError('invalid', 'joinLobby needs a code or a lobby');
+    }
+    const self = options.node.nodeIdHex();
+    if (self !== null && hexPeer(self) === host) {
+        throw new StoreError('invalid-data', 'this node hosts that lobby: use lobby.self to play in it');
+    }
+    // Announce, so the host holds this player's signed key: its node
+    // refuses a relayed handshake from a peer it has no announcement for.
+    // Kept up while playing — a re-handshake (a reconnect, a replaced
+    // channel) needs the key again after the old announcement lapses.
+    const node = options.node;
+    const keep = [...(options.tags ?? [])];
+    const seeking = [...keep, seekTag(options.game, host)];
+    let stopped = false;
+    const announce = () => {
+        if (!stopped)
+            node.announce(seeking).catch(() => { });
+    };
+    announce();
+    const timer = setInterval(announce, LOBBY_ANNOUNCE_MS);
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        node.announce(keep).catch(() => { });
+    };
+    // Reach the host before joining. Until this player's announcement has
+    // reached the host, the host refuses the handshake — so a refusal here
+    // is "not yet", retried until the deadline, and naming the host is
+    // better than the store's later `no session with 0x…`.
+    if (node.connectPeer !== undefined) {
+        const deadline = Date.now() + (options.timeoutMs ?? 20_000);
+        for (;;) {
+            try {
+                await node.connectPeer(host);
+                break;
+            }
+            catch (error) {
+                if (Date.now() >= deadline) {
+                    stop();
+                    throw new LobbyError('not-found', `could not reach the lobby's host ${host}: ${String(error?.message ?? error)}`);
+                }
+                await new Promise(resolve => setTimeout(resolve, 500));
+            }
+        }
+    }
+    let joined;
+    try {
+        joined = joinStore({
+            definition: options.definition,
+            transport: node,
+            host,
+            audience: options.audience ?? [],
+            key: options.key ?? 'player',
+            maxEventBytes: options.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES,
+            ...(options.interest === undefined ? {} : { interest: options.interest }),
+        });
+    }
+    catch (error) {
+        stop();
+        throw error;
+    }
+    const close = joined.close.bind(joined);
+    joined.close = async () => {
+        stop();
+        await close();
+    };
+    return joined;
+}
+/** The lobby code in a link made by `lobby.link()`, or `null`. Default: this page. */
+export function lobbyCodeFromUrl(url) {
+    try {
+        const value = new URL(url ?? globalThis.location?.href ?? '').searchParams.get('lobby');
+        return value === null ? null : normalizeLobbyCode(value);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/local.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `@net-mesh/browser/local` — a mesh in one page, for developing a game
+ * without an anchor.
+ *
+ * ```ts
+ * import { createLocalMesh } from '@net-mesh/browser/local';
+ *
+ * const mesh = createLocalMesh();
+ * const hostNode = mesh.node();
+ * const playerNode = mesh.node();
+ * const host = hostStore({ definition, transport: hostNode, … });
+ * const player = joinStore({ definition, transport: playerNode, host: hostNode.nodeIdHex(), … });
+ * ```
+ *
+ * A local node satisfies the same structural type `connect()`'s node
+ * does for the store, so `hostStore`, `joinStore` and `hostPlayer` are
+ * the real ones and every frame is really encoded, parsed, chunked,
+ * assembled and dispatched. What is NOT real is the network: delivery
+ * is a function call in this page, and the peer on each frame is
+ * assigned by this module rather than proved by a handshake.
+ *
+ * So a game that works here has working game logic and working store
+ * wiring. It is not evidence that two browsers can reach each other —
+ * that takes an anchor and `connect()`.
+ *
+ * Discovery works too: `announce(tags)` and `query(tag)` behave like
+ * the real node's, including the announcement expiring, so a lobby
+ * list or a find-the-host loop can be built offline as well.
+ *
+ * Nothing here loads the wasm node: importing this subpath costs no
+ * download.
+ */
+import type { NodeDescriptor } from './node.js';
+import type { StoreTransport } from './store/host.js';
+/**
+ * How long an announcement stays discoverable: the leaf's default,
+ * 300 s (`net-mesh-leaf` `DEFAULT_TTL_SECS`). A node that announces
+ * once and never again drops out of `query` after it, as on the mesh.
+ */
+export declare const LOCAL_ANNOUNCEMENT_TTL_MS = 300000;
+/** Options for {@link createLocalMesh}. */
+export interface LocalMeshOptions {
+    /** Announcement lifetime, milliseconds. Default {@link LOCAL_ANNOUNCEMENT_TTL_MS}. */
+    readonly announcementTtlMs?: number;
+    /** The clock announcements are judged against. Default `Date.now`. */
+    readonly now?: () => number;
+}
+/** A node on a local mesh. Pass it wherever the store takes a `transport`. */
+export interface LocalNode extends StoreTransport {
+    /** This node's id: 16 lowercase hex, as `connect()`'s node reports it. */
+    nodeIdHex(): string;
+    /**
+     * Publish this node's capability tags, replacing any it announced
+     * before — as `connect()`'s node does. Discoverable by the OTHER
+     * nodes on this mesh until the announcement expires.
+     */
+    announce(capabilities: readonly string[]): Promise<void>;
+    /**
+     * The other nodes whose fresh announcement carries `capability`, in
+     * the same descriptor shape `connect()`'s node returns. This node's
+     * own announcement is not included, as a leaf does not hear itself.
+     */
+    query(capability: string): Promise<NodeDescriptor[]>;
+    /** Take this node off the mesh: frames to it fail, and it hears nothing. */
+    close(): void;
+}
+/** One page's worth of mesh. Meshes are independent of each other. */
+export interface LocalMesh {
+    /**
+     * Add a node. `id` is 16 hex digits; omitted, one is chosen at
+     * random. Refuses an id already on this mesh.
+     */
+    node(id?: string): LocalNode;
+    /** The ids of the nodes currently on this mesh. */
+    nodes(): readonly string[];
+    /** Take every node off the mesh. */
+    close(): void;
+}
+/** Create an empty local mesh. */
+export declare function createLocalMesh(options?: LocalMeshOptions): LocalMesh;