@net-mesh/browser 0.37.0

package/dist/world/handoff.js

@@ -0,0 +1,222 @@
+/**
+ * Entity handoff between region hosts — at-most-once, with a typed failure
+ * (browser plan §9 item 3, decision Q6).
+ *
+ * An entity crossing from region A to region B must never be live in both,
+ * and must never be applied twice. Exactly-once is not attempted; the
+ * failure a crash can cause is an entity that is **nowhere live for a
+ * while**, reported typed, never a duplicate.
+ *
+ * The protocol, over any lossy, duplicating, reordering carrier:
+ *
+ * 1. **A freezes.** The entity leaves A's live entities and waits in A's
+ *    `outgoing` under a fresh handoff id, with its state. A answers inputs for
+ *    it with `in-transit` (see {@link locate}).
+ * 2. **A offers** `{ id, entity, state }` to B, and repeats the offer until it
+ *    hears back. The id is the idempotence key.
+ * 3. **B decides once per id.** On the first offer it either admits the
+ *    entity (it is now live in B) or refuses it, and records the decision in
+ *    `handled`. Every later copy of that offer gets the SAME answer and
+ *    changes nothing.
+ * 4. **A settles.** `accept`: the frozen copy is dropped, and the entity is
+ *    B's. `refuse`: the entity returns to A's live entities. Only an explicit
+ *    refusal can bring it back to A, because silence proves nothing: B may
+ *    have admitted it and the answer been lost.
+ * 5. **No answer.** A keeps it frozen and keeps offering. After `giveUpMs`,
+ *    {@link retryHandoffs} reports it `unresolved` and stops offering. The
+ *    entity stays frozen, still nowhere live twice. Recovery (the destination
+ *    returning, an operator) re-offers with the same id through
+ *    {@link reofferHandoff}, which B answers from its record.
+ *
+ * **Durability is the caller's, and it is the whole correctness argument.**
+ * Every step here is a pure function from one {@link RegionState} to the
+ * next. The host MUST make the returned state durable (e.g.
+ * `persistStore(…).flush()`) BEFORE it sends the messages the step returns. A
+ * crash then either loses the step with its messages, which is the same as a
+ * lost message, or keeps both. B must also remember a decision for longer
+ * than any A keeps offering: `handledRetentionMs` > `giveUpMs`.
+ */
+/** An empty region. */
+export function regionState(region, entities = {}) {
+    return { region, entities, outgoing: {}, handled: {} };
+}
+function timing(options = {}) {
+    const retryMs = options.retryMs ?? 250;
+    const giveUpMs = options.giveUpMs ?? 60_000;
+    const handledRetentionMs = options.handledRetentionMs ?? 600_000;
+    if (!(handledRetentionMs > giveUpMs)) {
+        // A target that forgot a decision would admit a late re-offer a second
+        // time: the one way this protocol could duplicate.
+        throw new RangeError('handledRetentionMs must exceed giveUpMs, or a late offer could be admitted twice');
+    }
+    return { retryMs, giveUpMs, handledRetentionMs };
+}
+const has = (record, key) => Object.prototype.hasOwnProperty.call(record, key);
+function without(record, key) {
+    const out = {};
+    for (const k of Object.keys(record))
+        if (k !== key)
+            Object.defineProperty(out, k, { value: record[k], enumerable: true, writable: true, configurable: true });
+    return out;
+}
+function withEntry(record, key, value) {
+    const out = { ...record };
+    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+    return out;
+}
+/**
+ * Step 1–2 at the source: freeze `entity` and offer it to region `to`.
+ * Throws if the entity is not live here (frozen already, or unknown).
+ */
+export function beginHandoff(state, entity, to, id, now) {
+    if (!has(state.entities, entity))
+        throw new Error(`entity '${entity}' is not live in region '${state.region}'`);
+    if (has(state.outgoing, id) || has(state.handled, id))
+        throw new Error(`handoff id '${id}' is already in use`);
+    if (to === state.region)
+        throw new Error('a handoff needs another region');
+    const frozen = state.entities[entity];
+    const outgoing = { entity, state: frozen, to, since: now, sentAt: now, unresolved: false };
+    return {
+        state: { ...state, entities: without(state.entities, entity), outgoing: withEntry(state.outgoing, id, outgoing) },
+        send: [{ to, body: { k: 'offer', id, from: state.region, entity, state: frozen } }],
+        events: [],
+    };
+}
+/**
+ * Step 3 at the target: decide an offer once, and answer every copy of it
+ * the same way. `admit` is asked only the first time; it returns `true` or a
+ * refusal reason. An admitted entity whose id is already live here is
+ * refused (`occupied`), never overwritten.
+ */
+export function onHandoffOffer(state, offer, now, admit = () => true) {
+    const previous = has(state.handled, offer.id) ? state.handled[offer.id] : undefined;
+    if (previous !== undefined) {
+        return { state, send: [{ to: offer.from, body: replyOf(state.region, offer.id, previous) }], events: [] };
+    }
+    let decision;
+    if (has(state.entities, offer.entity)) {
+        decision = { decision: 'refuse', reason: 'occupied', at: now };
+    }
+    else {
+        let verdict;
+        try {
+            verdict = admit(offer.entity, offer.state);
+        }
+        catch (error) {
+            verdict = `admit threw: ${String(error)}`;
+        }
+        decision = verdict === true ? { decision: 'accept', at: now } : { decision: 'refuse', reason: verdict, at: now };
+    }
+    const entities = decision.decision === 'accept' ? withEntry(state.entities, offer.entity, offer.state) : state.entities;
+    return {
+        state: { ...state, entities, handled: withEntry(state.handled, offer.id, decision) },
+        send: [{ to: offer.from, body: replyOf(state.region, offer.id, decision) }],
+        events: decision.decision === 'accept' ? [{ type: 'admitted', id: offer.id, entity: offer.entity, from: offer.from }] : [],
+    };
+}
+function replyOf(region, id, handled) {
+    return handled.decision === 'accept'
+        ? { k: 'accept', id, from: region }
+        : { k: 'refuse', id, from: region, reason: handled.reason ?? 'refused' };
+}
+/**
+ * Step 4 at the source: settle on the target's answer. A reply for a handoff
+ * this region is not holding (already settled, or never begun) changes
+ * nothing: replies are duplicated and reordered like everything else.
+ */
+export function onHandoffReply(state, reply) {
+    if (!has(state.outgoing, reply.id))
+        return { state, send: [], events: [] };
+    const outgoing = state.outgoing[reply.id];
+    if (reply.from !== outgoing.to)
+        return { state, send: [], events: [] };
+    const rest = without(state.outgoing, reply.id);
+    if (reply.k === 'accept') {
+        return {
+            state: { ...state, outgoing: rest },
+            send: [],
+            events: [{ type: 'moved', id: reply.id, entity: outgoing.entity, to: outgoing.to }],
+        };
+    }
+    // Only an explicit refusal returns it. An entity that went live here again
+    // in the meantime (a restore, a new spawn) is kept, and the frozen copy is
+    // discarded rather than overwriting it.
+    const entities = has(state.entities, outgoing.entity)
+        ? state.entities
+        : withEntry(state.entities, outgoing.entity, outgoing.state);
+    return {
+        state: { ...state, entities, outgoing: rest },
+        send: [],
+        events: [{ type: 'refused', id: reply.id, entity: outgoing.entity, to: outgoing.to, reason: reply.reason }],
+    };
+}
+/**
+ * Step 2 and 5 at the source, on a timer: re-offer what is unanswered, and
+ * mark what has waited past `giveUpMs` as `unresolved` (reported once, still
+ * frozen, no longer offered).
+ */
+export function retryHandoffs(state, now, options) {
+    const { retryMs, giveUpMs } = timing(options);
+    let outgoing = null;
+    const send = [];
+    const events = [];
+    for (const [id, pending] of Object.entries(state.outgoing)) {
+        if (pending.unresolved)
+            continue;
+        if (now - pending.since >= giveUpMs) {
+            outgoing ??= { ...state.outgoing };
+            outgoing[id] = { ...pending, unresolved: true };
+            events.push({ type: 'unresolved', id, entity: pending.entity, to: pending.to });
+            continue;
+        }
+        if (now - pending.sentAt >= retryMs) {
+            outgoing ??= { ...state.outgoing };
+            outgoing[id] = { ...pending, sentAt: now };
+            send.push({ to: pending.to, body: { k: 'offer', id, from: state.region, entity: pending.entity, state: pending.state } });
+        }
+    }
+    return { state: outgoing === null ? state : { ...state, outgoing }, send, events };
+}
+/**
+ * Recovery: offer an `unresolved` handoff again, under the SAME id (the
+ * destination answers it from its record, so this cannot admit twice), and
+ * restart its give-up clock. Use it when the destination is known to be
+ * back. A no-op for a handoff that is not unresolved.
+ */
+export function reofferHandoff(state, id, now) {
+    if (!has(state.outgoing, id) || !state.outgoing[id].unresolved)
+        return { state, send: [], events: [] };
+    const pending = state.outgoing[id];
+    return {
+        state: { ...state, outgoing: withEntry(state.outgoing, id, { ...pending, unresolved: false, since: now, sentAt: now }) },
+        send: [{ to: pending.to, body: { k: 'offer', id, from: state.region, entity: pending.entity, state: pending.state } }],
+        events: [],
+    };
+}
+/** Forget target decisions older than `handledRetentionMs` (which must outlast any source's offers). */
+export function pruneHandled(state, now, options) {
+    const { handledRetentionMs } = timing(options);
+    let handled = null;
+    for (const [id, decision] of Object.entries(state.handled)) {
+        if (now - decision.at > handledRetentionMs) {
+            handled ??= { ...state.handled };
+            delete handled[id];
+        }
+    }
+    return handled === null ? state : { ...state, handled };
+}
+/**
+ * Where an entity is, from this region's point of view — what to answer an
+ * input for it: `here` (apply it), `in-transit` (frozen, on its way to
+ * `to`; refuse, never apply), or `unknown`.
+ */
+export function locate(state, entity) {
+    if (has(state.entities, entity))
+        return { at: 'here' };
+    for (const [id, pending] of Object.entries(state.outgoing)) {
+        if (pending.entity === entity)
+            return { at: 'in-transit', to: pending.to, id };
+    }
+    return { at: 'unknown' };
+}

package/dist/world/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@net-mesh/browser/world` — large worlds across region hosts: regions and
+ * their directory, a player's merged view (`joinWorld`), at-most-once entity
+ * handoff between region hosts, cross-border actions, and ghosting.
+ */
+export { beginHandoff, locate, onHandoffOffer, onHandoffReply, pruneHandled, regionState, reofferHandoff, retryHandoffs, } from './handoff.js';
+export type { Handled, HandoffEvent, HandoffId, HandoffMessage, HandoffOffer, HandoffReply, HandoffStep, HandoffTiming, Outgoing, RegionState, } from './handoff.js';
+export { BorderActionError, handoffLink, parseHandoffLedger, regionHandoffs, storeRegion } from './link.js';
+export { ghostTargets, onForwardedAction, pruneActs } from './border.js';
+export type { ActRecord, ActionResult, BorderAction, ForwardedAction, GhostFrame } from './border.js';
+export type { HandoffLedger, HandoffLink, HandoffLinkOptions, HandoffTransport, LinkBody, RegionHandoffs, RegionHandoffsOptions, } from './link.js';
+export { REGION_ANNOUNCE_MS, announceRegions, joinWorld, regionDirectory, regionOf, regionTag, regionsAround, } from './regions.js';
+export type { JoinWorldOptions, RegionDirectory, RegionDirectoryOptions, RegionLookup, WorldNode, WorldRegion, WorldView, } from './regions.js';

package/dist/world/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@net-mesh/browser/world` — large worlds across region hosts: regions and
+ * their directory, a player's merged view (`joinWorld`), at-most-once entity
+ * handoff between region hosts, cross-border actions, and ghosting.
+ */
+export { beginHandoff, locate, onHandoffOffer, onHandoffReply, pruneHandled, regionState, reofferHandoff, retryHandoffs, } from './handoff.js';
+export { BorderActionError, handoffLink, parseHandoffLedger, regionHandoffs, storeRegion } from './link.js';
+export { ghostTargets, onForwardedAction, pruneActs } from './border.js';
+export { REGION_ANNOUNCE_MS, announceRegions, joinWorld, regionDirectory, regionOf, regionTag, regionsAround, } from './regions.js';

package/dist/world/link.d.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 { type ActRecord, type ActionResult, type BorderAction, type ForwardedAction, type GhostFrame } from './border.js';
+import { type HandoffEvent, type HandoffId, type HandoffMessage, type HandoffOffer, type HandoffReply, type HandoffTiming, type Outgoing, type Handled, type RegionState, locate } from './handoff.js';
+/** The structural transport a link uses: `BrowserNode`, a local-mesh node, `meshStoreTransport`. */
+export interface HandoffTransport {
+    openStream(options: {
+        reliability: 'reliable' | 'fireAndForget';
+        peer?: string;
+        label?: string;
+    }): {
+        send(payload: Uint8Array): unknown;
+        close(): unknown;
+    } | Promise<{
+        send(payload: Uint8Array): unknown;
+        close(): unknown;
+    }>;
+    onEvent(handler: (event: {
+        readonly type: string;
+        readonly peerNode?: string | null;
+        readonly payload?: Uint8Array;
+    }) => void): () => void;
+}
+/** {@link handoffLink}'s argument. */
+export interface HandoffLinkOptions {
+    readonly transport: HandoffTransport;
+    /** Names the world's handoff channel; every region host uses the same one. */
+    readonly label: string;
+    /**
+     * The node (16 hex) hosting `region`, or `null` if unknown — the region
+     * directory (e.g. from `query`). Also the AUTHENTICATION: a message that
+     * says it comes from region X is accepted only from `peerOf(X)`.
+     */
+    peerOf(region: string): string | null;
+    /**
+     * Refresh what `peerOf` knows about a region (e.g. `directory.lookup`).
+     * Called, at most once a second per region, when a message is for a region
+     * `peerOf` cannot place, or from a sender `peerOf` does not name as that
+     * region's host (the directory may be stale). The message itself is still
+     * dropped; the protocol's retry finds the refreshed answer.
+     */
+    refresh?(region: string): unknown;
+}
+/** The running link. */
+export interface HandoffLink<E> {
+    /** Send one step's message to the host of `message.to`. Best effort: the protocol retries. */
+    send(message: HandoffMessage<E>): void;
+    /** Receive authenticated offers, replies, forwarded actions and their results. */
+    onMessage(handler: (body: LinkBody<E>) => void): () => void;
+    /** Messages refused, by reason. */
+    readonly dropped: Readonly<Record<string, number>>;
+    close(): void;
+}
+/** Everything a link carries. */
+export type LinkBody<E> = HandoffOffer<E> | HandoffReply | ForwardedAction | ActionResult | GhostFrame<E>;
+/** Carry handoff messages between region hosts over `transport`. */
+export declare function handoffLink<E>(options: HandoffLinkOptions): HandoffLink<E>;
+/** {@link regionHandoffs}'s argument. */
+export interface RegionHandoffsOptions<E> {
+    readonly link: HandoffLink<E>;
+    /** This host's region. */
+    readonly region: string;
+    /** The region's current state (entities + ledger). */
+    load(): RegionState<E>;
+    /** Make `next` the region's state (e.g. commit it to the store). */
+    commit(next: RegionState<E>): void;
+    /**
+     * Make the committed state DURABLE. Awaited after every change and before
+     * that step's messages are sent — the protocol's one requirement. Omit
+     * only for a world that need not survive a host restart.
+     */
+    persist?(): void | Promise<void>;
+    /** Asked once per incoming entity: `true` to admit, or a refusal reason. */
+    admit?(entity: string, state: E): true | string;
+    /**
+     * Cross-border actions this region serves, by name: applied ONCE per
+     * action id, their effect and record committed and made durable before
+     * the answer goes back.
+     */
+    readonly actions?: Readonly<Record<string, BorderAction<E>>>;
+    /**
+     * Ghosting (plan §9 item 5): send each neighbouring region this region's
+     * entities within `margin` of their shared border, read-only, every
+     * `everyMs` (default 100). Regions are `r:<rx>:<rz>` squares of `size`.
+     * What neighbours send here is read with {@link RegionHandoffs.ghosts}.
+     */
+    readonly ghosting?: {
+        readonly size: number;
+        readonly margin: number;
+        positionOf(entity: E): {
+            readonly x: number;
+            readonly z: number;
+        } | null;
+        readonly everyMs?: number;
+    };
+    /** Outcomes: `moved`, `refused`, `unresolved` (source), `admitted` (target). */
+    onEvent?(event: HandoffEvent): void;
+    readonly timing?: HandoffTiming;
+    /** How often to re-offer and prune, ms. Default 100. */
+    readonly tickMs?: number;
+    readonly now?: () => number;
+    /** Handoff id source. Default: region plus 64 random bits. */
+    readonly newId?: () => HandoffId;
+}
+/** The running handoff driver. */
+export interface RegionHandoffs<E = unknown> {
+    /**
+     * Hand `entity` to region `to`: frozen here now, live there once it
+     * accepts. Resolves with the handoff id after the freeze is durable and the
+     * offer sent. Rejects if the entity is not live here.
+     */
+    handoff(entity: string, to: string): Promise<HandoffId>;
+    /** Where an entity is from this region's view: `here`, `in-transit`, `unknown`. */
+    locate(entity: string): ReturnType<typeof locate>;
+    /** Re-offer an `unresolved` handoff under its own id (the destination is back). */
+    reoffer(id: HandoffId): Promise<void>;
+    /**
+     * Ask region `to` to run action `name` on something it owns; resolves
+     * with its answer. Rejects with {@link BorderActionError}: `refused` (it
+     * decided no — the reason), or `unresolved` (no answer within `giveUpMs`:
+     * it may have happened, never twice).
+     */
+    forward(to: string, name: string, input: unknown): Promise<unknown>;
+    /**
+     * Neighbours' entities near this region's borders, read-only — the latest
+     * each neighbour sent, until it goes quiet. Not authoritative here: act on
+     * them with {@link forward}.
+     */
+    ghosts(): Readonly<Record<string, E>>;
+    /** Called when a neighbour's ghosts change. */
+    onGhosts(listener: () => void): () => void;
+    close(): void;
+}
+/** Why a forwarded action did not produce an answer. */
+export declare class BorderActionError extends Error {
+    readonly code: 'refused' | 'unresolved';
+    constructor(code: 'refused' | 'unresolved', message: string);
+}
+/** Run handoffs for one region host. */
+export declare function regionHandoffs<E>(options: RegionHandoffsOptions<E>): RegionHandoffs<E>;
+/** Where {@link storeRegion} keeps the handoff ledger in the document. */
+export interface HandoffLedger<E> {
+    readonly outgoing: Readonly<Record<HandoffId, Outgoing<E>>>;
+    readonly handled: Readonly<Record<HandoffId, Handled>>;
+    readonly acts?: Readonly<Record<string, ActRecord>>;
+}
+/**
+ * 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 declare function storeRegion<S extends object, E>(host: {
+    getState(): S;
+    setState(next: S): void;
+}, options: {
+    readonly region: string;
+    readonly collection: string;
+    readonly ledger: string;
+}): Pick<RegionHandoffsOptions<E>, 'load' | 'commit'>;
+/** Validate a handoff ledger read from a store document; `parseEntity` validates the frozen entities. */
+export declare function parseHandoffLedger<E>(value: unknown, parseEntity: (value: unknown) => E): HandoffLedger<E>;