@net-mesh/browser 0.37.0

package/dist/world/link.js

@@ -0,0 +1,476 @@
+/**
+ * Handoff between real region hosts: the messages {@link handoff.ts}'s steps
+ * produce, carried over the mesh, and a driver that runs the steps in the
+ * order their correctness needs — commit, make durable, THEN send.
+ *
+ * ```ts
+ * const link = handoffLink({ transport: node, label: 'my-world.handoff', peerOf: region => directory[region] });
+ * const region = storeRegion(host, { region: 'r:4:7', collection: 'ships', ledger: 'handoff' });
+ * const handoffs = regionHandoffs({
+ *   link, region: 'r:4:7', ...region,
+ *   persist: () => { saving.flush(); },        // persistStore(host, …): durable before any send
+ *   onEvent: event => …,                       // moved / refused / unresolved / admitted
+ * });
+ * handoffs.handoff('ship-7', 'r:4:8');         // when the ship crosses the border
+ * ```
+ */
+import { peerHexOf } from '../store/host.js';
+import { ghostTargets, onForwardedAction, pruneActs, } from './border.js';
+import { beginHandoff, locate, onHandoffOffer, onHandoffReply, pruneHandled, reofferHandoff, retryHandoffs, } from './handoff.js';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+function isBody(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const body = value;
+    if (typeof body.from !== 'string')
+        return false;
+    if (body.k !== 'ghost' && typeof body.id !== 'string')
+        return false;
+    switch (body.k) {
+        case 'offer':
+            return typeof body.entity === 'string' && 'state' in body;
+        case 'accept':
+            return true;
+        case 'refuse':
+            return typeof body.reason === 'string';
+        case 'act':
+            return typeof body.name === 'string' && 'input' in body;
+        case 'result':
+            return body.ok === true ? 'output' in body : body.ok === false && typeof body.reason === 'string';
+        case 'ghost':
+            return (Number.isSafeInteger(body.seq) &&
+                typeof body.entities === 'object' &&
+                body.entities !== null &&
+                !Array.isArray(body.entities));
+        default:
+            return false;
+    }
+}
+/** Carry handoff messages between region hosts over `transport`. */
+export function handoffLink(options) {
+    const { label } = options;
+    const streams = new Map();
+    const opening = new Map();
+    const handlers = new Set();
+    const dropped = {};
+    const drop = (reason) => {
+        dropped[reason] = (dropped[reason] ?? 0) + 1;
+    };
+    let closed = false;
+    const refreshedAt = new Map();
+    const refresh = (region) => {
+        if (options.refresh === undefined)
+            return;
+        const at = Date.now();
+        if (at - (refreshedAt.get(region) ?? -Infinity) < 1_000)
+            return;
+        refreshedAt.set(region, at);
+        try {
+            void Promise.resolve(options.refresh(region)).catch(() => undefined);
+        }
+        catch {
+            // A failing refresh leaves the directory as it was.
+        }
+    };
+    const retire = (peer, stream) => {
+        if (streams.get(peer) === stream)
+            streams.delete(peer);
+        try {
+            stream.close();
+        }
+        catch {
+            // Already unusable.
+        }
+    };
+    const deliver = (peer, payload) => {
+        const stream = streams.get(peer);
+        if (stream !== undefined) {
+            try {
+                void Promise.resolve(stream.send(payload)).catch(() => retire(peer, stream));
+            }
+            catch {
+                retire(peer, stream);
+            }
+            return;
+        }
+        // Open once per peer; a message sent meanwhile is dropped (the
+        // protocol re-sends), never queued without bound.
+        if (opening.has(peer)) {
+            drop('opening');
+            return;
+        }
+        opening.set(peer, Promise.resolve()
+            .then(() => options.transport.openStream({ reliability: 'reliable', peer, label }))
+            .then(opened => {
+            if (closed) {
+                opened.close();
+                return;
+            }
+            streams.set(peer, opened);
+            try {
+                void Promise.resolve(opened.send(payload)).catch(() => retire(peer, opened));
+            }
+            catch {
+                retire(peer, opened);
+            }
+        })
+            .catch(() => drop('open-failed'))
+            .finally(() => opening.delete(peer)));
+    };
+    const stop = options.transport.onEvent(event => {
+        if (closed || event.type !== 'stream_data' || event.payload === undefined)
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(decoder.decode(event.payload));
+        }
+        catch {
+            return; // not ours
+        }
+        if (typeof frame !== 'object' || frame === null || frame.n !== label)
+            return;
+        if (!isBody(frame.b)) {
+            drop('malformed');
+            return;
+        }
+        const body = frame.b;
+        // A region speaks only from the node that hosts it: a player (or any
+        // other node) cannot offer an entity into a region or settle a
+        // handoff on another region's behalf.
+        const sender = typeof event.peerNode === 'string' ? peerHexOf(event.peerNode) : null;
+        const expected = options.peerOf(body.from);
+        if (sender === null || expected === null || peerHexOf(expected) !== sender) {
+            drop('unauthenticated');
+            refresh(body.from);
+            return;
+        }
+        for (const handler of [...handlers])
+            handler(body);
+    });
+    return {
+        send(message) {
+            if (closed)
+                return;
+            const peer = options.peerOf(message.to);
+            const hex = peer === null ? null : peerHexOf(peer);
+            if (hex === null) {
+                drop('unknown-region');
+                refresh(message.to);
+                return;
+            }
+            deliver(hex, encoder.encode(JSON.stringify({ n: label, b: message.body })));
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            return () => {
+                handlers.delete(handler);
+            };
+        },
+        get dropped() {
+            return { ...dropped };
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            stop();
+            for (const [peer, stream] of [...streams])
+                retire(peer, stream);
+        },
+    };
+}
+/** Why a forwarded action did not produce an answer. */
+export class BorderActionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BorderActionError';
+    }
+}
+function randomId(region) {
+    const bytes = new Uint8Array(8);
+    globalThis.crypto.getRandomValues(bytes);
+    return `${region}:${[...bytes].map(b => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/** Run handoffs for one region host. */
+export function regionHandoffs(options) {
+    const now = options.now ?? Date.now;
+    const newId = options.newId ?? (() => randomId(options.region));
+    let closed = false;
+    // Steps run one at a time: each loads the state the previous one
+    // committed, and a slow `persist` cannot let a later step's messages
+    // overtake an earlier step's durability.
+    let queue = Promise.resolve();
+    const run = (step, result) => {
+        const next = queue.then(async () => {
+            const before = options.load();
+            const done = step(before);
+            if (done.state !== before) {
+                options.commit(done.state);
+                if (options.persist)
+                    await options.persist();
+            }
+            for (const message of done.send)
+                options.link.send(message);
+            for (const event of done.events)
+                options.onEvent?.(event);
+            return result();
+        });
+        queue = next.catch(() => undefined);
+        return next;
+    };
+    // Actions this host forwarded, awaiting an answer. In memory only: see
+    // `border.ts` for why that keeps at-most-once.
+    const forwarded = new Map();
+    // Ghosts: what each neighbour last sent (with when), and what we send.
+    const received = new Map();
+    const ghostListeners = new Set();
+    let ghostSeq = 0;
+    let ghostSentAt = -Infinity;
+    const ghostEvery = options.ghosting?.everyMs ?? 100;
+    const sendGhosts = (at) => {
+        const ghosting = options.ghosting;
+        if (ghosting === undefined || at - ghostSentAt < ghostEvery)
+            return;
+        ghostSentAt = at;
+        const byNeighbour = new Map();
+        // Every neighbour hears from us each round, even with nothing near its
+        // border: an empty frame is how ghosts that left get cleared.
+        const match = /^r:(-?\d+):(-?\d+)$/.exec(options.region);
+        if (match !== null) {
+            for (let dx = -1; dx <= 1; dx += 1) {
+                for (let dz = -1; dz <= 1; dz += 1) {
+                    if (dx !== 0 || dz !== 0)
+                        byNeighbour.set(`r:${Number(match[1]) + dx}:${Number(match[2]) + dz}`, {});
+                }
+            }
+        }
+        for (const [id, entity] of Object.entries(options.load().entities)) {
+            const at2 = ghosting.positionOf(entity);
+            if (at2 === null)
+                continue;
+            for (const target of ghostTargets(options.region, at2.x, at2.z, ghosting.size, ghosting.margin)) {
+                const bucket = byNeighbour.get(target);
+                if (bucket !== undefined) {
+                    Object.defineProperty(bucket, id, { value: entity, enumerable: true, writable: true, configurable: true });
+                }
+            }
+        }
+        ghostSeq += 1;
+        for (const [to, entities] of byNeighbour) {
+            const frame = { k: 'ghost', from: options.region, seq: ghostSeq, entities };
+            options.link.send({ to, body: frame });
+        }
+    };
+    const retryMs = options.timing?.retryMs ?? 250;
+    const giveUpMs = options.timing?.giveUpMs ?? 60_000;
+    const retentionMs = options.timing?.handledRetentionMs ?? 600_000;
+    const stop = options.link.onMessage(body => {
+        if (closed)
+            return;
+        switch (body.k) {
+            case 'offer':
+                void run(state => onHandoffOffer(state, body, now(), options.admit), () => undefined);
+                return;
+            case 'accept':
+            case 'refuse':
+                void run(state => onHandoffReply(state, body), () => undefined);
+                return;
+            case 'act': {
+                let reply = null;
+                void run(state => {
+                    const done = onForwardedAction(state, body, now(), options.actions ?? {});
+                    reply = done.reply;
+                    return { state: done.state, send: [{ to: body.from, body: done.reply }], events: [] };
+                }, () => reply);
+                return;
+            }
+            case 'ghost': {
+                const known = received.get(body.from);
+                if (known !== undefined && known.seq >= body.seq)
+                    return; // reordered or repeated
+                received.set(body.from, { seq: body.seq, entities: body.entities, at: now() });
+                for (const listener of [...ghostListeners])
+                    listener();
+                return;
+            }
+            case 'result': {
+                const pending = forwarded.get(body.id);
+                if (pending === undefined || pending.to !== body.from)
+                    return;
+                forwarded.delete(body.id);
+                if (body.ok)
+                    pending.resolve(body.output);
+                else
+                    pending.reject(new BorderActionError('refused', body.reason));
+                return;
+            }
+        }
+    });
+    const timer = setInterval(() => {
+        if (closed)
+            return;
+        const at = now();
+        sendGhosts(at);
+        // A neighbour gone quiet: its ghosts are stale, so they go.
+        let expired = false;
+        for (const [from, frame] of received) {
+            if (at - frame.at > ghostEvery * 5) {
+                received.delete(from);
+                expired = true;
+            }
+        }
+        if (expired)
+            for (const listener of [...ghostListeners])
+                listener();
+        for (const [id, pending] of forwarded) {
+            if (at - pending.since >= giveUpMs) {
+                forwarded.delete(id);
+                pending.reject(new BorderActionError('unresolved', `no answer from ${pending.to} for action ${id}; it may have run, never twice`));
+            }
+            else if (at - pending.sentAt >= retryMs) {
+                pending.sentAt = at;
+                options.link.send({ to: pending.to, body: pending.body });
+            }
+        }
+        void run(state => {
+            const retried = retryHandoffs(state, now(), options.timing);
+            const pruned = pruneActs(pruneHandled(retried.state, now(), options.timing), now(), retentionMs);
+            return { ...retried, state: pruned };
+        }, () => undefined);
+    }, options.tickMs ?? 100);
+    timer.unref?.();
+    return {
+        handoff(entity, to) {
+            const id = newId();
+            return run(state => beginHandoff(state, entity, to, id, now()), () => id);
+        },
+        locate: entity => locate(options.load(), entity),
+        reoffer: id => run(state => reofferHandoff(state, id, now()), () => undefined),
+        ghosts() {
+            const out = {};
+            for (const frame of received.values()) {
+                for (const [id, entity] of Object.entries(frame.entities)) {
+                    Object.defineProperty(out, id, { value: entity, enumerable: true, writable: true, configurable: true });
+                }
+            }
+            return out;
+        },
+        onGhosts(listener) {
+            ghostListeners.add(listener);
+            return () => {
+                ghostListeners.delete(listener);
+            };
+        },
+        forward(to, name, input) {
+            if (closed)
+                return Promise.reject(new BorderActionError('unresolved', 'the handoff driver is closed'));
+            const id = newId();
+            const body = { k: 'act', id, from: options.region, name, input };
+            return new Promise((resolve, reject) => {
+                const at = now();
+                forwarded.set(id, { body, to, since: at, sentAt: at, resolve, reject });
+                options.link.send({ to, body });
+            });
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(timer);
+            stop();
+            for (const [id, pending] of forwarded) {
+                forwarded.delete(id);
+                pending.reject(new BorderActionError('unresolved', 'the handoff driver closed before an answer'));
+            }
+        },
+    };
+}
+/**
+ * A region whose entities are a hosted store's collection, with the handoff
+ * ledger under another top-level key of the SAME document — so the store's
+ * persistence (`persistStore`) makes both durable as one unit.
+ *
+ * The definition must accept the ledger key (an object of `outgoing` and
+ * `handled` records; {@link parseHandoffLedger} validates one) and should
+ * hide it from players (`visibility: { [ledger]: 'nobody' }`).
+ */
+export function storeRegion(host, options) {
+    return {
+        load: () => {
+            const doc = host.getState();
+            const entities = (doc[options.collection] ?? {});
+            const ledger = (doc[options.ledger] ?? { outgoing: {}, handled: {} });
+            return {
+                region: options.region,
+                entities,
+                outgoing: ledger.outgoing,
+                handled: ledger.handled,
+                acts: ledger.acts ?? {},
+            };
+        },
+        commit: next => {
+            const doc = host.getState();
+            host.setState({
+                ...doc,
+                [options.collection]: next.entities,
+                [options.ledger]: { outgoing: next.outgoing, handled: next.handled, acts: next.acts ?? {} },
+            });
+        },
+    };
+}
+/** Validate a handoff ledger read from a store document; `parseEntity` validates the frozen entities. */
+export function parseHandoffLedger(value, parseEntity) {
+    const record = (v, what) => {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            throw new Error(`${what} is not a record`);
+        return v;
+    };
+    // An id is data from another host: `__proto__` must stay a key.
+    const define = (target, key, entry) => {
+        Object.defineProperty(target, key, { value: entry, enumerable: true, writable: true, configurable: true });
+    };
+    if (value === undefined)
+        return { outgoing: {}, handled: {} };
+    const ledger = record(value, 'the handoff ledger');
+    const outgoing = {};
+    for (const [id, raw] of Object.entries(record(ledger.outgoing ?? {}, 'outgoing'))) {
+        const o = record(raw, `outgoing ${id}`);
+        if (typeof o.entity !== 'string' || typeof o.to !== 'string')
+            throw new Error(`outgoing ${id} is malformed`);
+        define(outgoing, id, {
+            entity: o.entity,
+            state: parseEntity(o.state),
+            to: o.to,
+            since: Number(o.since),
+            sentAt: Number(o.sentAt),
+            unresolved: o.unresolved === true,
+        });
+    }
+    const handled = {};
+    for (const [id, raw] of Object.entries(record(ledger.handled ?? {}, 'handled'))) {
+        const h = record(raw, `handled ${id}`);
+        if (h.decision !== 'accept' && h.decision !== 'refuse')
+            throw new Error(`handled ${id} is malformed`);
+        define(handled, id, {
+            decision: h.decision,
+            at: Number(h.at),
+            ...(typeof h.reason === 'string' ? { reason: h.reason } : {}),
+        });
+    }
+    const acts = {};
+    for (const [id, raw] of Object.entries(record(ledger.acts ?? {}, 'acts'))) {
+        const a = record(raw, `act ${id}`);
+        if (typeof a.ok !== 'boolean')
+            throw new Error(`act ${id} is malformed`);
+        define(acts, id, {
+            at: Number(a.at),
+            ok: a.ok,
+            ...('output' in a ? { output: a.output } : {}),
+            ...(typeof a.reason === 'string' ? { reason: a.reason } : {}),
+        });
+    }
+    return { outgoing, handled, acts };
+}

package/dist/world/regions.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Large worlds: regions, their directory, and a player's merged view
+ * (browser plan §9 items 1–2).
+ *
+ * The map is cut into square regions of `size` units; region `r:<rx>:<rz>`
+ * covers `rx*size <= x < (rx+1)*size`, the same for z. Each region is its
+ * own store, hosted by whichever node announces it:
+ *
+ * ```ts
+ * // A region host (usually a dedicated Node host):
+ * hostStore({ definition: world, store: 'r:4:7', transport, … });
+ * announceRegions(node, 'my-world', ['r:4:7', 'r:4:8']);
+ *
+ * // A player:
+ * const view = joinWorld({ node, world: 'my-world', definition: world, collection: 'ships',
+ *                          position: { x, z }, size: 256, key: 'player', maxEventBytes: 8104 });
+ * bindEntities({ store: view, select: entities => entities, … });
+ * view.setPosition(x, z);                  // as the player moves
+ * await view.act('fire', { … });           // to the region the player is in
+ * ```
+ *
+ * **The directory is discovery, not a root of trust.** Any node can
+ * announce any tag. {@link regionDirectory} therefore takes `trustedHosts`,
+ * the node ids that may host this world's regions. Without that list, a
+ * region two nodes claim is `ambiguous` and is NOT joined, rather than
+ * joining whichever answered first. A handoff link that authenticates by this
+ * directory (`handoffLink({ peerOf: directory.peerOf })`) needs the list:
+ * otherwise a node that announces a region could also send offers as it.
+ */
+import type { NodeDescriptor } from '../node.js';
+import type { StoreTransport } from '../store/host.js';
+import type { ActionSpec, Cancel, InputSpec, StoreDefinition } from '../store/types.js';
+/** A node that can join stores and use the directory. */
+export interface WorldNode extends StoreTransport {
+    announce(capabilities: readonly string[]): Promise<void>;
+    query(capability: string): Promise<NodeDescriptor[]>;
+}
+/** Region `r:<rx>:<rz>` for a position, with regions `size` units square. */
+export declare function regionOf(x: number, z: number, size: number): string;
+/** The regions within `radius` regions of a position (a square, `(2r+1)²`). */
+export declare function regionsAround(x: number, z: number, options: {
+    readonly size: number;
+    readonly radius?: number;
+}): string[];
+/** The directory tag a region host announces. */
+export declare function regionTag(world: string, region: string): string;
+/** How often region hosts re-announce: an announcement is a lease. */
+export declare const REGION_ANNOUNCE_MS = 2000;
+/**
+ * Announce that this node hosts `regions` of `world`, and keep announcing
+ * (an announcement is a lease). `announce` replaces a node's tags, so pass
+ * any other tags this node carries in `tags`. Returns a stop function.
+ */
+export declare function announceRegions(node: Pick<WorldNode, 'announce'>, world: string, regions: readonly string[], options?: {
+    readonly tags?: readonly string[];
+    readonly everyMs?: number;
+}): Cancel;
+/** What the directory knows about a region. */
+export type RegionLookup = {
+    readonly status: 'hosted';
+    readonly host: string;
+} | {
+    readonly status: 'unhosted';
+} | {
+    readonly status: 'ambiguous';
+    readonly hosts: readonly string[];
+};
+/** A cached view of which node hosts which region. */
+export interface RegionDirectory {
+    /** Ask the mesh now (and cache the answer). */
+    lookup(region: string): Promise<RegionLookup>;
+    /** The cached host of a region, 16 hex, or `null` — synchronous, for `handoffLink`'s `peerOf`. */
+    peerOf(region: string): string | null;
+}
+/** {@link regionDirectory}'s argument. */
+export interface RegionDirectoryOptions {
+    readonly node: Pick<WorldNode, 'query'>;
+    readonly world: string;
+    /**
+     * The node ids (16 hex) that may host this world's regions. Announcements
+     * from any other node are ignored. Omit, and a region more than one node
+     * claims is `ambiguous`.
+     */
+    readonly trustedHosts?: readonly string[];
+}
+/** A region directory over the mesh's signed announcements. */
+export declare function regionDirectory(options: RegionDirectoryOptions): RegionDirectory;
+/** One region of a player's world view. */
+export interface WorldRegion {
+    readonly region: string;
+    /** `looking` (directory lookup pending), `unhosted`, `ambiguous`, `joining`, `ready`, or `failed`. */
+    readonly phase: 'looking' | 'unhosted' | 'ambiguous' | 'joining' | 'ready' | 'failed';
+    readonly host: string | null;
+}
+/** {@link joinWorld}'s argument. */
+export interface JoinWorldOptions<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly node: WorldNode;
+    readonly world: string;
+    /** Every region's store definition (one definition, one store per region). */
+    readonly definition: StoreDefinition<S, A, I>;
+    /** The top-level entity map the view merges across regions. */
+    readonly collection: string;
+    readonly position: {
+        readonly x: number;
+        readonly z: number;
+    };
+    /** Region size, the same the hosts use. */
+    readonly size: number;
+    /** Regions kept around the player's. Default 1 (a 3×3 block). Regions beyond `radius + 1` are released. */
+    readonly radius?: number;
+    readonly key: string;
+    readonly audience?: readonly string[];
+    readonly maxEventBytes: number;
+    /** The directory to use; default one over `node` (with `trustedHosts`). */
+    readonly directory?: RegionDirectory;
+    readonly trustedHosts?: readonly string[];
+    /**
+     * An entity's position, to break a tie when it shows in two regions at
+     * once (a handoff's source and destination replicas can briefly both hold
+     * it): the copy from the region containing it wins. Default: the first
+     * region's copy.
+     */
+    readonly positionOf?: (entity: unknown) => {
+        readonly x: number;
+        readonly z: number;
+    } | null;
+    /** Retry an unhosted or failed region this often, ms. Default 2000. */
+    readonly retryMs?: number;
+    /**
+     * How long an entity that vanishes from a region the view still holds
+     * stays in the view at its last state, ms. Default 500. A handoff freezes
+     * an entity at its source before the destination's replica shows it, and
+     * without this it would blink out at the border. It stops lingering as
+     * soon as it appears in any region. `0` disables. Entities of a region
+     * released because the player moved away go at once.
+     */
+    readonly lingerMs?: number;
+}
+/** A player's view of a world across regions. */
+export interface WorldView<E, A extends ActionSpec> {
+    /** Every entity in the regions held, merged by id. Satisfies `bindEntities`' store. */
+    getState(): Readonly<Record<string, E>>;
+    subscribe(listener: (entities: Readonly<Record<string, E>>, previous: Readonly<Record<string, E>>) => void): Cancel;
+    /** Move: regions come into and go out of the view. */
+    setPosition(x: number, z: number): void;
+    /** The region the player is in. */
+    currentRegion(): string;
+    regions(): readonly WorldRegion[];
+    /** An action, sent to the region the player is in. Rejects if that region is not ready. */
+    act<K extends keyof A & string>(name: K, input: A[K]['input']): Promise<A[K]['output']>;
+    close(): Promise<void>;
+}
+/** Join a world: the player's region and its neighbours, merged into one view. */
+export declare function joinWorld<S extends object, A extends ActionSpec, I extends InputSpec, E = unknown>(options: JoinWorldOptions<S, A, I>): WorldView<E, A>;