@net-mesh/browser 0.37.0

package/dist/leader/wasm.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The `wasm_bindgen` boundary for §8's session surface.
+ *
+ * `src/wasm.ts` describes the *direct* surface (`LeafNode`) and types
+ * `MeshSession` as `unknown` so the two cannot drift into two
+ * spellings of one contract. This file is the one place the session's
+ * shape is declared, in the snake_case `wasm-bindgen` emits from the
+ * Rust method names; every camelCase name a page sees is added by
+ * {@link MeshSession} one layer up.
+ */
+import type { LeafWasmConnectOptions, LeafWasmModule, LeafWasmOrgAccess, LeafWasmOrgCallOptions, LeafWasmOrgClientStreamHandler, LeafWasmOrgDuplexHandler, LeafWasmOrgServeHandle, LeafWasmOrgServeOptions, LeafWasmOrgStreamingHandler, LeafWasmOrgUnaryHandler, LeafWasmOrgUploadCallHandle, LeafWasmOrgByteStreamHandle, LeafWasmOrgDuplexCallHandle, LeafWasmProxyStream, LeafWasmStreamOptions } from '../wasm.js';
+/**
+ * `MeshSession.open`'s argument: everything `LeafNode.connect` reads,
+ * plus what leader election needs.
+ */
+export interface LeafWasmSessionOptions extends LeafWasmConnectOptions {
+    /**
+     * Capabilities to announce, and to **re-announce** whenever this tab
+     * becomes the leader. They live on the session rather than on a
+     * method call because a new leader has to re-publish them without
+     * being asked.
+     */
+    capabilities?: readonly string[];
+    /**
+     * Channels this tab depends on. The leader keeps the union of every
+     * follower's declaration subscribed, and a new leader restores it.
+     */
+    subscriptions?: readonly string[];
+    /** The IndexedDB database holding the identity. Defaults to `net-mesh-leaf`. */
+    dbName?: string;
+    /**
+     * Override the Web Lock and `BroadcastChannel` name. Defaults to
+     * `net-mesh/<origin>/<identity-fingerprint>`, which is the scope
+     * one-node-per-origin means; overriding it is for tests that need
+     * two independent elections in one origin.
+     */
+    lockScope?: string;
+}
+/** The session object `MeshSession.open` resolves to. */
+export interface LeafWasmSession {
+    /** `"leader"` or `"follower"`. */
+    role(): string;
+    /** The generation in force for this tab, as an exact decimal string. */
+    generation(): string;
+    /** The node's id, 16 lowercase hex digits, once one is known. */
+    node_id_hex(): string | undefined;
+    /** The identity fingerprint the lock is named after. */
+    fingerprint(): string;
+    /** The lock and channel name. */
+    scope(): string;
+    /** The measured handoff for a promoted tab; `undefined` on the first leader. */
+    interruption_ms(): number | undefined;
+    call(service: string, payload: Uint8Array, timeout_ms?: number): Promise<Uint8Array>;
+    call_org(service: string, payload: Uint8Array, options: LeafWasmOrgCallOptions): Promise<Uint8Array>;
+    call_org_streaming(service: string, payload: Uint8Array, options: LeafWasmOrgCallOptions): Promise<LeafWasmOrgByteStreamHandle>;
+    call_org_client_stream(service: string, options: LeafWasmOrgCallOptions): Promise<LeafWasmOrgUploadCallHandle>;
+    call_org_duplex(service: string, options: LeafWasmOrgCallOptions): Promise<LeafWasmOrgDuplexCallHandle>;
+    serve_org(service: string, access: LeafWasmOrgAccess, handler: LeafWasmOrgUnaryHandler, options: LeafWasmOrgServeOptions): LeafWasmOrgServeHandle;
+    serve_org_streaming(service: string, access: LeafWasmOrgAccess, handler: LeafWasmOrgStreamingHandler, options: LeafWasmOrgServeOptions): LeafWasmOrgServeHandle;
+    serve_org_client_stream(service: string, access: LeafWasmOrgAccess, handler: LeafWasmOrgClientStreamHandler, options: LeafWasmOrgServeOptions): LeafWasmOrgServeHandle;
+    serve_org_duplex(service: string, access: LeafWasmOrgAccess, handler: LeafWasmOrgDuplexHandler, options: LeafWasmOrgServeOptions): LeafWasmOrgServeHandle;
+    subscribe(channel: string): Promise<void>;
+    /**
+     * Release this tab's claim on a channel. The membership survives
+     * while another tab still declares it.
+     */
+    unsubscribe(channel: string): Promise<void>;
+    publish(channel: string, payload: Uint8Array): Promise<void>;
+    announce(capabilities: string[]): Promise<void>;
+    query(capability: string): Promise<string>;
+    /** Every counter as JSON. A promise: on a follower the node is elsewhere. */
+    counters_json(): Promise<string>;
+    /** Proxied, so a follower's `enroll()` works — one node per origin. */
+    enroll(): Promise<void>;
+    /** A promise, where `LeafNode.is_enrolled` is synchronous. */
+    is_enrolled(): Promise<boolean>;
+    signal(peer_hex: string, dialog_hex: string, kind: string, payload: Uint8Array): Promise<void>;
+    /**
+     * The four peer-attempt primitives, proxied. `peer_candidate` and
+     * `peer_handshake` take the dialog because the leaf requires it:
+     * a proxied request is served after crossing a channel, so the
+     * attempt it named may have been replaced, and it is refused
+     * before it can drive the replacement.
+     */
+    peer_offer(peer_hex: string): Promise<string>;
+    /**
+     * The live attempt's dialog when the pair is already direct and open on
+     * the leader, else `undefined`. An older leader refuses the op.
+     */
+    peer_direct_dialog(peer_hex: string): Promise<string | undefined>;
+    peer_accept_offer(peer_hex: string): Promise<string>;
+    peer_candidate(peer_hex: string, dialog_hex: string): Promise<string>;
+    peer_handshake(peer_hex: string, dialog_hex: string): Promise<string>;
+    /**
+     * A promise, where `LeafNode.open_stream` is synchronous: on a
+     * follower the stream is opened by the tab that owns the
+     * DataChannel.
+     */
+    open_stream(options: LeafWasmStreamOptions): Promise<LeafWasmProxyStream>;
+    on_event(callback: (eventJson: string) => void): void;
+    close(): void;
+}
+/**
+ * The generated module, with `MeshSession` refined.
+ *
+ * A bundle built before Stage 5 slice 3 does not carry it, which is
+ * why the base type leaves it optional and this narrows rather than
+ * assumes.
+ */
+export interface LeafWasmSessionModule extends LeafWasmModule {
+    MeshSession: {
+        open(options: LeafWasmSessionOptions): Promise<LeafWasmSession>;
+    };
+}
+/**
+ * Narrow a loaded module to one that carries the session surface.
+ *
+ * A named refusal rather than a cast: a page bundling an older
+ * `net_leaf.js` would otherwise get `undefined is not a constructor`
+ * from inside the wrapper, which says nothing about what is actually
+ * wrong.
+ */
+export declare function asSessionModule(module: LeafWasmModule): LeafWasmSessionModule;

package/dist/leader/wasm.js

@@ -0,0 +1,39 @@
+/**
+ * The `wasm_bindgen` boundary for §8's session surface.
+ *
+ * `src/wasm.ts` describes the *direct* surface (`LeafNode`) and types
+ * `MeshSession` as `unknown` so the two cannot drift into two
+ * spellings of one contract. This file is the one place the session's
+ * shape is declared, in the snake_case `wasm-bindgen` emits from the
+ * Rust method names; every camelCase name a page sees is added by
+ * {@link MeshSession} one layer up.
+ */
+/**
+ * Narrow a loaded module to one that carries the session surface.
+ *
+ * A named refusal rather than a cast: a page bundling an older
+ * `net_leaf.js` would otherwise get `undefined is not a constructor`
+ * from inside the wrapper, which says nothing about what is actually
+ * wrong.
+ */
+export function asSessionModule(module) {
+    const candidate = module.MeshSession;
+    // `wasm-bindgen` emits `export class MeshSession { static open(…) }`,
+    // and a class is a FUNCTION, not an object — so the shape check has
+    // to admit both. It used to test `typeof === 'object'` only, which
+    // rejected every real bundle and reported the pre-slice-3 message
+    // for a module that carried the session all along.
+    const usable = candidate !== null &&
+        (typeof candidate === 'object' || typeof candidate === 'function') &&
+        'open' in candidate &&
+        typeof candidate.open === 'function';
+    if (!usable) {
+        throw new Error('this net-mesh-leaf bundle has no MeshSession: leader election and the ' +
+            'follower proxy need a wasm build from Stage 5 slice 3 or later');
+    }
+    // Checked above: `MeshSession.open` exists and is callable. The
+    // argument and return types are the wasm-bindgen contract this file
+    // declares, and no runtime check can establish those.
+    const narrowed = module;
+    return narrowed;
+}

package/dist/lobby.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 type { NodeDescriptor } from './node.js';
+import { type HostedStoreHandle, type HostProjection, type HostStoreBaseOptions, type StoreTransport } from './store/host.js';
+import { type JoinedStoreHandle } from './store/join.js';
+import type { AccessRequest, ActionSpec, Cancel, InputSpec, StoreDefinition } from './store/types.js';
+/** A node a lobby can run on: a store transport that can announce and query. */
+export interface LobbyNode extends StoreTransport {
+    announce(capabilities: readonly string[]): Promise<void>;
+    query(capability: string): Promise<NodeDescriptor[]>;
+}
+/** Game-defined fields shown in a lobby list: small, flat, public. */
+export type LobbyInfo = Readonly<Record<string, string | number | boolean>>;
+/** Why a lobby call failed. */
+export type LobbyErrorCode = 
+/** No lobby answered to that code before the deadline. */
+'not-found'
+/** More than one node claims the code; joining either could be the wrong one. */
+ | 'ambiguous'
+/** A game name, code, record or option is not usable. */
+ | 'invalid';
+export declare class LobbyError extends Error {
+    readonly code: LobbyErrorCode;
+    constructor(code: LobbyErrorCode, message: string);
+}
+/** One open lobby, as a list shows it. */
+export interface LobbyListing {
+    readonly code: string;
+    readonly name: string;
+    /** Players in it, the host included, as the host last announced. */
+    readonly players: number;
+    readonly capacity: number;
+    /** The store it serves, `id@version`. */
+    readonly store: string;
+    readonly info: LobbyInfo;
+    /** The announcing node, 16 hex — from its signed announcement, not from the record. */
+    readonly host: string;
+}
+/** Bounds on what a lobby may publish (Q4 in the lobbies plan). */
+export declare const MAX_LOBBY_NAME_CHARS = 64;
+export declare const MAX_LOBBY_INFO_BYTES = 256;
+export declare const MAX_LOBBY_RECORD_TAG_BYTES = 512;
+export declare 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 declare const LOBBY_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export declare const LOBBY_CODE_LENGTH = 6;
+/** How often a lobby re-announces itself. */
+export declare const LOBBY_ANNOUNCE_MS = 2000;
+/** A code as typed: case, spaces and dashes forgiven. */
+export declare function normalizeLobbyCode(code: string): string;
+/** What `createLobby` takes: a store's host options, minus the transport, plus the lobby. */
+export type CreateLobbyOptions<S extends object, A extends ActionSpec, I extends InputSpec> = Omit<HostStoreBaseOptions<S, A, I>, 'transport' | 'authorize' | 'maxEventBytes'> & HostProjection<S> & {
+    readonly node: LobbyNode;
+    /** Your game's name on the mesh: lobbies are listed per game. */
+    readonly game: string;
+    readonly name: string;
+    /** Most players at once, the host included. */
+    readonly capacity: number;
+    /** `'public'` (default) is listed; `'unlisted'` is joined by code or link only. */
+    readonly visibility?: 'public' | 'unlisted';
+    /** Small public fields a list shows — map, mode. At most 256 bytes of JSON. */
+    readonly info?: LobbyInfo;
+    /** The audience the host's own player reads. Default `[]`. */
+    readonly audience?: readonly string[];
+    /**
+     * Your game's policy, as `hostStore`'s. Default: allow. The lobby
+     * applies capacity and kicks BEFORE it, so it never sees a refused
+     * join.
+     */
+    readonly authorize?: (request: AccessRequest<A, I>) => boolean;
+    readonly maxEventBytes?: number;
+    /** Other tags this node should keep announcing while the lobby is open. */
+    readonly tags?: readonly string[];
+    /** Re-announce interval. Default {@link LOBBY_ANNOUNCE_MS}. */
+    readonly announceEveryMs?: number;
+};
+/** An open lobby, on the node hosting it. */
+export interface Lobby<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly code: string;
+    readonly game: string;
+    readonly visibility: 'public' | 'unlisted';
+    /** The authoritative store. */
+    readonly host: HostedStoreHandle<S, A, I>;
+    /** The host's own player — the same handle shape `joinLobby` returns. */
+    readonly self: JoinedStoreHandle<S, A, I>;
+    /** Who is in: the host first, then each joined peer, 16 hex. */
+    players(): readonly string[];
+    /** Called with the new list whenever someone joins or leaves. */
+    subscribePlayers(listener: (players: readonly string[]) => void): Cancel;
+    /** A shareable link: `base` with `?lobby=<code>`. Default base: this page. */
+    link(base?: string): string;
+    /** Remove a player now and refuse them from here on. */
+    kick(peer: string): void;
+    /** Stop announcing, close the store and the host's player. */
+    close(): Promise<void>;
+}
+/**
+ * Open a lobby: host the store on `node`, give the host its own
+ * player, and announce the lobby until it closes.
+ */
+export declare function createLobby<S extends object, A extends ActionSpec, I extends InputSpec>(options: CreateLobbyOptions<S, A, I>): Promise<Lobby<S, A, I>>;
+/** The open public lobbies of `game`, as their hosts last announced them. */
+export declare function listLobbies(options: {
+    readonly node: LobbyNode;
+    readonly game: string;
+}): Promise<LobbyListing[]>;
+/** What `joinLobby` takes. */
+export interface JoinLobbyOptions<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly node: LobbyNode;
+    readonly definition: StoreDefinition<S, A, I>;
+    readonly game: string;
+    /** A code, as typed or from a link — or a listing from `listLobbies`. */
+    readonly code?: string;
+    readonly lobby?: LobbyListing;
+    /** The audience to read. Default `[]`. */
+    readonly audience?: readonly string[];
+    /** The interest set to join with (see `joinStore`). Default: every entity. */
+    readonly interest?: readonly string[];
+    /** The opaque join token. Default `'player'`. */
+    readonly key?: string;
+    readonly maxEventBytes?: number;
+    /** How long to look for the code, and to reach the host. Default 20 s. */
+    readonly timeoutMs?: number;
+    /**
+     * Tags this node keeps announcing while it plays. Joining announces a
+     * `seek` tag so the host can discover this player, and an announcement
+     * replaces the node's whole tag set — so anything else the page
+     * announces goes here. The same option as `createLobby`'s.
+     */
+    readonly tags?: readonly string[];
+}
+/**
+ * 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 declare function joinLobby<S extends object, A extends ActionSpec, I extends InputSpec>(options: JoinLobbyOptions<S, A, I>): Promise<JoinedStoreHandle<S, A, I>>;
+/** The lobby code in a link made by `lobby.link()`, or `null`. Default: this page. */
+export declare function lobbyCodeFromUrl(url?: string): string | null;