@net-mesh/browser 0.37.0

package/dist/store/patch.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Patch semantics, frozen (brief §1.13).
+ *
+ * A delta is a list of `{"o":"r","p":[…],"val":…}` (replace) and
+ * `{"o":"x","p":[…]}` (remove) operations over **own property-name
+ * segments**. There is no JSON Pointer escaping, no arbitrary
+ * operation, and nothing executable: the op set is two entries because
+ * a patch language is an interpreter, and an interpreter on untrusted
+ * input is a much larger promise than this protocol needs to make.
+ *
+ * Three properties carry the weight, and each is a witness rather than
+ * a comment:
+ *
+ * - **Atomicity.** The whole patch is validated, applied to a draft,
+ *   and the *final* state validated by the definition's `state()`
+ *   before anything is committed. A half-applied patch is never
+ *   published, and a refused patch leaves the previous revision
+ *   byte-for-byte intact — the caller then resynchronizes (§1.8),
+ *   because a replica whose view disagrees with the owner's must not
+ *   guess.
+ * - **Prototype safety.** `__proto__`, `constructor` and `prototype`
+ *   are refused as segments, traversal is own-property only, and every
+ *   node the patch builds has a **null prototype**. Refusing the names
+ *   alone would not be enough — a draft built from `{}` inherits a
+ *   `constructor` that `in` would find — so the two rules are both
+ *   present and both witnessed.
+ * - **Identity.** The committed state goes through
+ *   {@link reconcile}, so untouched subtrees keep their references and
+ *   a Three.js loop can diff by reference. An equivalent patch is a
+ *   no-op, not a whole-world change.
+ */
+import type { StoreErrorCode } from './errors.js';
+import type { Parse } from './types.js';
+import { type WireOp } from './wire.js';
+/** Segments that would reach the prototype chain. */
+export declare const FORBIDDEN_SEGMENTS: readonly string[];
+/** Why a patch was refused. Stable and countable. */
+export type PatchRefusal = 'ops-too-many' | 'path-too-deep' | 'segment-too-long' | 'segment-forbidden' | 'root-remove' | 'missing-parent' | 'parent-not-object' | 'missing-key' | 'invalid-state';
+export interface PatchRejected {
+    readonly ok: false;
+    readonly code: StoreErrorCode;
+    readonly reason: PatchRefusal;
+    /**
+     * Whether the replica should resynchronize. True for the divergence
+     * refusals (`missing-parent`, `missing-key`, `parent-not-object`,
+     * `invalid-state`): the views disagree and only the owner can settle
+     * it. False for the bound refusals, which are the sender's fault.
+     */
+    readonly resync: boolean;
+}
+export interface PatchApplied<S> {
+    readonly ok: true;
+    readonly next: S;
+    /**
+     * False when the patch moved nothing — `next === current`. An
+     * unchanged update must not create a revision or a notification
+     * (design §4), and that decision is made here, once.
+     */
+    readonly changed: boolean;
+}
+export type PatchOutcome<S> = PatchApplied<S> | PatchRejected;
+/**
+ * Apply a delta's operations atomically.
+ *
+ * `current` is never mutated, whatever the outcome: on refusal the
+ * caller still holds exactly the state it had, which is what makes
+ * "a failed patch leaves the previous revision intact" a property of
+ * this function rather than a rule its callers have to remember.
+ */
+export declare function applyPatch<S extends object>(current: S, ops: readonly WireOp[], validate: Parse<S>): PatchOutcome<S>;

package/dist/store/patch.js

@@ -0,0 +1,166 @@
+/**
+ * Patch semantics, frozen (brief §1.13).
+ *
+ * A delta is a list of `{"o":"r","p":[…],"val":…}` (replace) and
+ * `{"o":"x","p":[…]}` (remove) operations over **own property-name
+ * segments**. There is no JSON Pointer escaping, no arbitrary
+ * operation, and nothing executable: the op set is two entries because
+ * a patch language is an interpreter, and an interpreter on untrusted
+ * input is a much larger promise than this protocol needs to make.
+ *
+ * Three properties carry the weight, and each is a witness rather than
+ * a comment:
+ *
+ * - **Atomicity.** The whole patch is validated, applied to a draft,
+ *   and the *final* state validated by the definition's `state()`
+ *   before anything is committed. A half-applied patch is never
+ *   published, and a refused patch leaves the previous revision
+ *   byte-for-byte intact — the caller then resynchronizes (§1.8),
+ *   because a replica whose view disagrees with the owner's must not
+ *   guess.
+ * - **Prototype safety.** `__proto__`, `constructor` and `prototype`
+ *   are refused as segments, traversal is own-property only, and every
+ *   node the patch builds has a **null prototype**. Refusing the names
+ *   alone would not be enough — a draft built from `{}` inherits a
+ *   `constructor` that `in` would find — so the two rules are both
+ *   present and both witnessed.
+ * - **Identity.** The committed state goes through
+ *   {@link reconcile}, so untouched subtrees keep their references and
+ *   a Three.js loop can diff by reference. An equivalent patch is a
+ *   no-op, not a whole-world change.
+ */
+import { reconcile } from './state.js';
+import { MAX_PATCH_OPS, MAX_PATH_SEGMENTS, MAX_PATH_SEGMENT_BYTES, utf8Length } from './wire.js';
+/** Segments that would reach the prototype chain. */
+export const FORBIDDEN_SEGMENTS = ['__proto__', 'constructor', 'prototype'];
+const FORBIDDEN = new Set(FORBIDDEN_SEGMENTS);
+function reject(reason, resync, code = 'invalid-data') {
+    return { ok: false, code, reason, resync };
+}
+/**
+ * Apply a delta's operations atomically.
+ *
+ * `current` is never mutated, whatever the outcome: on refusal the
+ * caller still holds exactly the state it had, which is what makes
+ * "a failed patch leaves the previous revision intact" a property of
+ * this function rather than a rule its callers have to remember.
+ */
+export function applyPatch(current, ops, validate) {
+    // Bounds first, and over the whole list: nothing is applied until
+    // every operation is admissible, so a patch cannot be half-refused.
+    if (ops.length > MAX_PATCH_OPS)
+        return reject('ops-too-many', false, 'capacity');
+    for (const op of ops) {
+        if (op.p.length > MAX_PATH_SEGMENTS)
+            return reject('path-too-deep', false, 'capacity');
+        for (const segment of op.p) {
+            if (utf8Length(segment) > MAX_PATH_SEGMENT_BYTES) {
+                return reject('segment-too-long', false, 'capacity');
+            }
+            // Prototype-named segments are refused outright. Traversal below
+            // is own-property only as well; either alone would be a hole.
+            if (FORBIDDEN.has(segment))
+                return reject('segment-forbidden', false);
+        }
+        // A state must exist: replacing the root is permitted, removing it
+        // is not.
+        if (op.o === 'x' && op.p.length === 0)
+            return reject('root-remove', false);
+    }
+    // Apply to a draft. Nodes are copied along the touched path only, so
+    // an untouched subtree is the *same object* in the draft and is then
+    // recognised by `reconcile` as unchanged.
+    let draft = current;
+    const copied = new WeakSet();
+    for (const op of ops) {
+        if (op.p.length === 0) {
+            // Root replace; root remove was refused above.
+            if (op.o === 'r')
+                draft = op.val;
+            continue;
+        }
+        if (!isTraversable(draft))
+            return reject('parent-not-object', true);
+        const root = copyOnce(draft, copied);
+        draft = root;
+        const parent = descend(root, op.p.slice(0, -1), copied);
+        if (parent === MISSING)
+            return reject('missing-parent', true);
+        if (parent === NOT_OBJECT)
+            return reject('parent-not-object', true);
+        const container = parent;
+        const leaf = op.p[op.p.length - 1];
+        if (op.o === 'x') {
+            // A remove whose target is absent means the views have already
+            // diverged: refuse the whole patch and resynchronize.
+            if (!Object.prototype.hasOwnProperty.call(container, leaf)) {
+                return reject('missing-key', true);
+            }
+            delete container[leaf];
+            continue;
+        }
+        container[leaf] = op.val;
+    }
+    // The definition validates the **final** state, not each step: an
+    // intermediate shape may legitimately be invalid, and a patch is one
+    // transition.
+    let validated;
+    try {
+        validated = validate(draft);
+    }
+    catch {
+        return reject('invalid-state', true);
+    }
+    const next = reconcile(current, validated);
+    return { ok: true, next, changed: !Object.is(next, current) };
+}
+const MISSING = Symbol('missing-parent');
+const NOT_OBJECT = Symbol('parent-not-object');
+/**
+ * Walk to the parent of the target, copying each node on the way.
+ *
+ * `root` is already a draft copy. Each child is copied once and written
+ * back into its (copied) holder, so a second operation through the same
+ * parent mutates the draft's node instead of copying it again — which
+ * is what makes overlapping operations apply in array order with the
+ * later one winning.
+ */
+function descend(root, path, copied) {
+    let node = root;
+    for (const segment of path) {
+        const holder = node;
+        // Own-property only: the prototype chain is never followed, so a
+        // path segment can never resolve to an inherited member.
+        if (!Object.prototype.hasOwnProperty.call(holder, segment))
+            return MISSING;
+        const child = holder[segment];
+        if (!isTraversable(child))
+            return NOT_OBJECT;
+        const fresh = copyOnce(child, copied);
+        holder[segment] = fresh;
+        node = fresh;
+    }
+    return node;
+}
+/**
+ * Arrays are replaced whole in v1, so they are not traversable: a path
+ * that descends into one is a refusal, not an index.
+ */
+function isTraversable(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Copy a node into the draft once.
+ *
+ * The clone has a **null prototype**: refusing `__proto__`,
+ * `constructor` and `prototype` as segments stops the names, and this
+ * stops the inheritance, so no patched node can reach `Object.prototype`
+ * at all.
+ */
+function copyOnce(node, copied) {
+    if (copied.has(node))
+        return node;
+    const clone = Object.assign(Object.create(null), node);
+    copied.add(clone);
+    return clone;
+}

package/dist/store/player.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `hostPlayer` — the hosting node's own player, as a replica-shaped
+ * handle.
+ *
+ * A node cannot join its own store: `openStream({peer})` needs a
+ * session with that peer and a node has none with itself, so
+ * `joinStore({ host: self })` is refused `invalid-data`. Every game
+ * whose host is also a player therefore wrote the same wrapper — the
+ * fleet demo's was forty lines — and each one had to remember to hold
+ * the host's player to the same `authorize` a replica gets.
+ *
+ * This is that wrapper, made part of the store, with parity as its
+ * contract rather than a habit:
+ *
+ * - **The same policy.** Reads, actions and inputs go to the host's
+ *   `authorize` with the host's own node id as `peer`, in the same
+ *   16-hex spelling a replica's frames are handed.
+ * - **The same transaction.** Input parse, handler, output validation
+ *   and the result's message budget run in one transaction on the
+ *   owner, exactly as for a replica's `act` after the wire
+ *   (`StoreOwner.localAct`), and the change reaches every replica.
+ * - **The same values.** Inputs are refused and normalized by the
+ *   wire's own rules (`encodeMessage`, then `parseStoreJson`), so a
+ *   value that works for the host works for its players.
+ * - **The same view.** `getState()` is the projection for this
+ *   handle's audience, not the authoritative document: game code that
+ *   renders from a replica renders the same thing on the host.
+ *
+ * What is NOT the same, deliberately: there is no wire, so no handle,
+ * lease, sequence or replay ledger, and no `reconnect` to perform.
+ * Calls still settle asynchronously, as a replica's do, so a handler
+ * never runs nested inside the caller's own code.
+ *
+ * **The trust boundary is unchanged.** The hosting player's page holds
+ * the authoritative document; the projection here keeps the host's
+ * own UI honest, it does not hide anything from a player who opens the
+ * developer tools. Games with real stakes need a dedicated host.
+ */
+import { type HostedStoreHandle } from './host.js';
+import type { JoinedStoreHandle } from './join.js';
+import type { ActionSpec, InputSpec } from './types.js';
+/** What the host's own player reads as. */
+export interface HostPlayerOptions {
+    /**
+     * The audience this player reads, as a replica's `joinStore({
+     * audience })`. Authorized by the host's policy like any other read.
+     */
+    readonly audience: readonly string[];
+    /** The interest set, as `joinStore({ interest })`. Omit it to see every entity. */
+    readonly interest?: readonly string[];
+}
+/**
+ * The hosting node's own player on `host`.
+ *
+ * ```ts
+ * const host = hostStore({ definition: world, transport: node, … });
+ * const me = hostPlayer(host, { audience: ['crew'] });
+ * await me.ready();
+ * await me.act('enlist', { colour: 2 });   // same authorize, same handler
+ * ```
+ *
+ * Game code can then treat `me` and a `joinStore` replica the same way.
+ * Throws `invalid-data` for a handle `hostStore` did not return.
+ */
+export declare function hostPlayer<S extends object, A extends ActionSpec, I extends InputSpec>(host: HostedStoreHandle<S, A, I>, options: HostPlayerOptions): JoinedStoreHandle<S, A, I>;

package/dist/store/player.js

@@ -0,0 +1,261 @@
+/**
+ * `hostPlayer` — the hosting node's own player, as a replica-shaped
+ * handle.
+ *
+ * A node cannot join its own store: `openStream({peer})` needs a
+ * session with that peer and a node has none with itself, so
+ * `joinStore({ host: self })` is refused `invalid-data`. Every game
+ * whose host is also a player therefore wrote the same wrapper — the
+ * fleet demo's was forty lines — and each one had to remember to hold
+ * the host's player to the same `authorize` a replica gets.
+ *
+ * This is that wrapper, made part of the store, with parity as its
+ * contract rather than a habit:
+ *
+ * - **The same policy.** Reads, actions and inputs go to the host's
+ *   `authorize` with the host's own node id as `peer`, in the same
+ *   16-hex spelling a replica's frames are handed.
+ * - **The same transaction.** Input parse, handler, output validation
+ *   and the result's message budget run in one transaction on the
+ *   owner, exactly as for a replica's `act` after the wire
+ *   (`StoreOwner.localAct`), and the change reaches every replica.
+ * - **The same values.** Inputs are refused and normalized by the
+ *   wire's own rules (`encodeMessage`, then `parseStoreJson`), so a
+ *   value that works for the host works for its players.
+ * - **The same view.** `getState()` is the projection for this
+ *   handle's audience, not the authoritative document: game code that
+ *   renders from a replica renders the same thing on the host.
+ *
+ * What is NOT the same, deliberately: there is no wire, so no handle,
+ * lease, sequence or replay ledger, and no `reconnect` to perform.
+ * Calls still settle asynchronously, as a replica's do, so a handler
+ * never runs nested inside the caller's own code.
+ *
+ * **The trust boundary is unchanged.** The hosting player's page holds
+ * the authoritative document; the projection here keeps the host's
+ * own UI honest, it does not hide anything from a player who opens the
+ * developer tools. Games with real stakes need a dedicated host.
+ */
+import { StoreCore } from './core.js';
+import { StoreError } from './errors.js';
+import { hostInternals } from './host.js';
+import { parseStoreJson } from './json.js';
+import { encodeMessage } from './wire.js';
+const PLACEHOLDER_Q = '0'.repeat(16);
+const PLACEHOLDER_H = '0'.repeat(32);
+/**
+ * The wire's admission for one caller value: refused exactly as a
+ * replica's `encodeMessage` refuses it, and parsed back exactly as the
+ * owner's parser hands it to a handler.
+ */
+function admit(name, value, kind) {
+    let frame;
+    try {
+        frame =
+            kind === 'act'
+                ? encodeMessage({ k: 'act', q: PLACEHOLDER_Q, h: PLACEHOLDER_H, s: '1', name, in: value })
+                : encodeMessage({ k: 'in', h: PLACEHOLDER_H, s: '1', name, in: value });
+    }
+    catch (error) {
+        throw new StoreError('invalid-data', `the input for '${name}' cannot be encoded`, { cause: error });
+    }
+    const parsed = parseStoreJson(frame);
+    if (!parsed.ok || typeof parsed.value !== 'object' || parsed.value === null || Array.isArray(parsed.value)) {
+        throw new StoreError('invalid-data', `the input for '${name}' cannot be encoded`);
+    }
+    return parsed.value.in;
+}
+/** A value as a replica would receive it: JSON, detached from the host's objects. */
+function detach(value) {
+    const parsed = parseStoreJson(JSON.stringify(value));
+    return parsed.ok ? parsed.value : value;
+}
+/**
+ * The hosting node's own player on `host`.
+ *
+ * ```ts
+ * const host = hostStore({ definition: world, transport: node, … });
+ * const me = hostPlayer(host, { audience: ['crew'] });
+ * await me.ready();
+ * await me.act('enlist', { colour: 2 });   // same authorize, same handler
+ * ```
+ *
+ * Game code can then treat `me` and a `joinStore` replica the same way.
+ * Throws `invalid-data` for a handle `hostStore` did not return.
+ */
+export function hostPlayer(host, options) {
+    const inner = hostInternals(host);
+    if (inner === undefined) {
+        throw new StoreError('invalid-data', 'hostPlayer needs a handle returned by hostStore');
+    }
+    const { owner, peer } = inner;
+    const definition = host.definition;
+    const view = new StoreCore({ definition, initialState: definition.empty(), phase: 'syncing' });
+    let audience = [...options.audience];
+    let interest = options.interest === undefined ? null : [...options.interest];
+    let closed = false;
+    /** Terminal: the read was refused, the projection failed, or the host closed. */
+    let ended = false;
+    const pendingInputs = new Map();
+    function end(phase, error) {
+        ended = true;
+        if (error?.code === 'forbidden')
+            queueMicrotask(() => depart('refused'));
+        // As a replica does on a terminal refusal: the view is cleared, so
+        // a revoked read stops showing what it no longer may.
+        view.applySnapshot(definition.empty());
+        view.setStatus({ phase, stale: false, error });
+    }
+    /** Re-read the view — authorized afresh, as a replica's feed is. */
+    function refresh() {
+        if (closed || ended)
+            return;
+        if (inner.isClosed()) {
+            end('closed', null);
+            return;
+        }
+        if (!owner.localRead(peer, audience)) {
+            end('failed', new StoreError('forbidden', 'the store refused: forbidden'));
+            return;
+        }
+        const projected = owner.localView(peer, audience, interest);
+        if (projected === null) {
+            end('failed', new StoreError('capacity', 'the store refused: capacity'));
+            return;
+        }
+        view.applySnapshot(projected);
+        view.setStatus({ phase: 'ready', stale: false, error: null });
+    }
+    const stopWatching = owner.subscribe(() => {
+        refresh();
+    });
+    inner.onClose(() => {
+        stopWatching();
+        if (!closed && !ended)
+            end('closed', null);
+    });
+    refresh();
+    // A player, as far as `onEvent` is concerned: `join` now if the read
+    // was granted, `leave` when this handle ends.
+    let joined = false;
+    if (view.getStatus().phase === 'ready') {
+        joined = true;
+        owner.localPresence(peer, true, audience);
+        inner.dispatched({ out: [], refused: null, deferred: null });
+    }
+    function depart(reason) {
+        if (!joined || inner.isClosed())
+            return;
+        joined = false;
+        owner.localPresence(peer, false, audience, reason);
+        inner.dispatched({ out: [], refused: null, deferred: null });
+    }
+    function refusal() {
+        if (closed)
+            return new StoreError('closed', 'this store handle is closed');
+        if (inner.isClosed())
+            return new StoreError('owner-lost', 'the store owner closed this handle');
+        if (ended)
+            return view.getStatus().error ?? new StoreError('owner-lost', 'the store owner closed this handle');
+        return null;
+    }
+    function flushInputs() {
+        const batch = [...pendingInputs];
+        pendingInputs.clear();
+        if (refusal() !== null)
+            return;
+        for (const [name, value] of batch)
+            inner.dispatched(owner.localInput(name, value, peer));
+    }
+    function subscribe(first, second, selectorOptions) {
+        return second === undefined
+            ? view.subscribe(first)
+            : view.subscribe(first, second, selectorOptions);
+    }
+    return {
+        getState: () => view.getState(),
+        subscribe,
+        getStatus: () => view.getStatus(),
+        subscribeStatus: listener => view.subscribeStatus(listener),
+        ready: () => {
+            const status = view.getStatus();
+            if (status.phase === 'ready')
+                return Promise.resolve();
+            return Promise.reject(status.error ?? new StoreError(closed ? 'closed' : 'owner-lost', 'this store handle is not ready'));
+        },
+        act: async (name, input) => {
+            const early = refusal();
+            if (early !== null)
+                throw early;
+            const value = admit(name, input, 'act');
+            // A turn later, as a replica's answer is: a handler never runs
+            // inside the caller's own frame — including inside another
+            // handler, where it would nest a transaction.
+            await Promise.resolve();
+            const late = refusal();
+            if (late !== null)
+                throw late;
+            const { outcome, dispatched } = owner.localAct(name, value, peer);
+            inner.dispatched(dispatched);
+            if (outcome.kind === 'refusal') {
+                throw new StoreError(outcome.code, `the store refused: ${outcome.code}`);
+            }
+            return detach(outcome.out);
+        },
+        input: (name, value) => {
+            if (refusal() !== null || view.getStatus().phase !== 'ready') {
+                return { type: 'dropped', reason: 'not-ready' };
+            }
+            const admitted = admit(name, value, 'in');
+            // Newest wins, as a replica's inputs do: one pending value per
+            // name, applied a turn later.
+            const idle = pendingInputs.size === 0;
+            const replaced = pendingInputs.has(name);
+            pendingInputs.set(name, admitted);
+            if (idle)
+                queueMicrotask(flushInputs);
+            return { type: replaced ? 'replaced' : 'queued' };
+        },
+        setAudience: async (names) => {
+            const early = refusal();
+            if (early !== null)
+                throw early;
+            try {
+                encodeMessage({ k: 'aud', q: PLACEHOLDER_Q, h: PLACEHOLDER_H, aud: [...names] });
+            }
+            catch (error) {
+                throw new StoreError('invalid-data', 'the audience cannot be encoded', { cause: error });
+            }
+            await Promise.resolve();
+            const late = refusal();
+            if (late !== null)
+                throw late;
+            if (!owner.localRead(peer, names)) {
+                throw new StoreError('forbidden', 'the store refused: forbidden');
+            }
+            audience = [...names];
+            refresh();
+        },
+        setInterest: async (keys) => {
+            const early = refusal();
+            if (early !== null)
+                throw early;
+            const next = [...keys];
+            await Promise.resolve();
+            interest = next;
+            refresh();
+        },
+        // Nothing to resume: there is no session under this handle.
+        reconnect: () => Promise.resolve(),
+        close: () => {
+            if (!closed) {
+                closed = true;
+                depart('left');
+                pendingInputs.clear();
+                stopWatching();
+                view.close();
+            }
+            return Promise.resolve();
+        },
+    };
+}