@net-mesh/browser 0.37.0

package/dist/stream.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Streams, as a page wants them: an async iterable of payloads with a
+ * `send` that rejects with a typed error.
+ */
+import { SessionError } from './errors.js';
+import type { StreamReliability } from './wasm.js';
+/**
+ * Whether a stream must be able to name its peer.
+ *
+ * `'required'` for every stream this package builds — both the direct
+ * and the proxied wasm handle report one. `'optional'` exists for a
+ * host-supplied wrapper in a test or an embedding that has no peer to
+ * report, and it keeps the pre-repair id-only behaviour, which is why
+ * nothing in `src/` passes it.
+ */
+export type StreamIdentity = 'required' | 'optional';
+/**
+ * A stream could not name its peer, so its frames are unattributable.
+ *
+ * Thrown at construction rather than tolerated: a stream that cannot
+ * filter by peer admits any peer's frame carrying a matching id.
+ */
+export declare class StreamIdentityError extends SessionError {
+    constructor(message: string);
+}
+/** Options for {@link BrowserNode.openStream}. */
+export interface OpenStreamOptions {
+    /**
+     * `reliable` retransmits and reorders by `seq`; `fireAndForget`
+     * neither, which is the point of it — a dropped frame stays dropped
+     * and the consumer sees the gap.
+     */
+    reliability: StreamReliability;
+    /** A human label for logs. */
+    label?: string;
+    /**
+     * Used verbatim when present, so a stream can match a publish
+     * contract a native handler dispatches on.
+     */
+    streamId?: string;
+    /**
+     * Likewise verbatim: the `u16` channel hash the stream rides.
+     * A number — see {@link LeafWasmStreamOptions.channelHash} for
+     * why it is not a string.
+     */
+    channelHash?: number;
+    /**
+     * The node this stream addresses — **16 hex digits**, the spelling
+     * {@link BrowserNode.nodeId} hands out and
+     * {@link BrowserNode.connectPeer} takes. Absent, it is the anchor,
+     * which is what every caller got before this option existed.
+     *
+     * This is the page-facing half of §9: `connectPeer` installs a
+     * direct leaf ↔ leaf session and this is what puts application
+     * bytes on it. The addressing is the leaf's, not a second path —
+     * a stream to a peer whose session is still ROUTED rides the
+     * anchor, and needs no second call to start riding the
+     * DataChannel.
+     *
+     * **The handle does not survive the direct upgrade, though.** §9
+     * step 4 installs a *replacement* session, and a stream handle is
+     * fenced to the incarnation it was opened on — so `send` on a
+     * stream opened while the pair was routed rejects with
+     * {@link SessionError} ("stale stream handle … reopen the
+     * stream") once the direct session lands. Reopening is one call
+     * with the same `peer` and the same `streamId`; a page driving a
+     * peer across the upgrade should reopen on that rejection rather
+     * than assume continuity.
+     *
+     * A peer with no session at all rejects typed from `send`.
+     *
+     * Accepted by {@link MeshSession.openStream} as well. A follower's
+     * stream is opened by the leader tab's node, and the request
+     * carries this peer, so a follower addresses a direct
+     * leaf-to-leaf session exactly as the leader tab does. It used to
+     * be refused by name there, because the proxy request had no peer
+     * field to carry.
+     */
+    peer?: string;
+    /**
+     * **Ride the lossy carrier** — for high-rate state where only the newest
+     * value matters (positions, inputs). With `reliability: 'fireAndForget'`
+     * only; `true` with `'reliable'` throws.
+     *
+     * Every stream normally shares one ordered, fully retransmitted
+     * DataChannel, so one lost packet delays everything behind it. A lossy
+     * stream's packets ride a second, unordered channel with no
+     * retransmits: each arrives promptly or not at all, and none delays
+     * anything else. A packet that would queue behind a backed-up buffer is
+     * dropped instead (it would be stale on arrival). The receiver sees a
+     * fire-and-forget stream as always: gaps are skipped and anything older
+     * than what it already delivered is dropped — the newest value wins.
+     *
+     * Direct `connect()` nodes only for now: {@link MeshSession.openStream}
+     * refuses it. A peer or anchor that opens no lossy channel still gets
+     * the packets, on the reliable one.
+     */
+    lossy?: boolean;
+}
+/**
+ * One open stream.
+ *
+ * Inbound payloads are delivered to `for await` consumers and to
+ * {@link LeafStream.onMessage} listeners. Payloads that arrive before
+ * anyone consumes them are buffered in arrival order, so a page that
+ * opens a stream and awaits it a tick later loses nothing.
+ */
+export declare class LeafStream implements AsyncIterable<Uint8Array> {
+    private readonly inner;
+    private readonly onClosed?;
+    private readonly queues;
+    private readonly listeners;
+    private readonly pending;
+    private closed;
+    /**
+     * This stream's wire id as a number, or `null` when the inner
+     * object's `stream_id_hex()` was not hex.
+     *
+     * The event JSON spells the id in **decimal** while the handle
+     * spells it in **hex**; comparing the two textually would drop
+     * every payload, so the comparison is numeric. Rust filters the
+     * event stream too — this is the exact check behind its substring
+     * one, and the reason a mismatch is a dropped payload here rather
+     * than someone else's bytes.
+     */
+    private readonly wireId;
+    /**
+     * The peer this stream addresses, as a number, or `null` when the
+     * inner object does not spell one.
+     *
+     * **The other half of a stream's identity, and the reason the id
+     * alone was not one.** A stream id is an application label scoped
+     * to a session, so two streams to two peers under the same id is
+     * the ordinary case — `openStream({ peer, streamId })` invites it
+     * — and the callback is handed the NODE-WIDE event vector. Keyed
+     * on the id alone, two wrappers both admitted whichever peer's
+     * frame arrived, so a page echoing what it received amplified one
+     * peer's payload onto the other's stream (R4-10). The key is
+     * `(peer, id)`.
+     *
+     * Read in the same hex spelling as the id and compared against the
+     * event's decimal `peer_node` the same way, so there is one
+     * conversion idiom in this file rather than two — a mismatch in
+     * either would fail the id comparison too, loudly.
+     */
+    private readonly peerId;
+    /** The authenticated peer this stream is with, 16 lowercase hex. */
+    get peerNode(): string;
+    /**
+     * Whether this stream retransmits. Read from the leaf rather than
+     * from the options it was asked for, so it is the stream's own
+     * answer.
+     */
+    get reliability(): StreamReliability;
+    /** The stream's wire id, hex. */
+    get streamId(): string;
+    /** Send one payload. Fragmentation at `MAX_PAYLOAD_SIZE` is the leaf's. */
+    send(payload: Uint8Array): Promise<void>;
+    /** Listen for payloads. Returns a cancel handle. */
+    onMessage(listener: (payload: Uint8Array) => void): () => void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Uint8Array>;
+    /** Close the stream and end every consumer. */
+    close(): void;
+    /**
+     * One callback from the wasm boundary.
+     *
+     * Rust emits the node's `stream_data` event JSON; this is where
+     * it becomes the `Uint8Array` the public API promises. Bytes are
+     * taken as an already-decoded payload, which is what a
+     * host-supplied {@link LeafWasmStreamLike} may deliver.
+     */
+    private receive;
+    private decode;
+}

package/dist/stream.js

@@ -0,0 +1,238 @@
+/**
+ * Streams, as a page wants them: an async iterable of payloads with a
+ * `send` that rejects with a typed error.
+ */
+import { AsyncQueue } from './async-queue.js';
+import { fromWasmError, SessionError } from './errors.js';
+import { parseEvent } from './events.js';
+/**
+ * A stream could not name its peer, so its frames are unattributable.
+ *
+ * Thrown at construction rather than tolerated: a stream that cannot
+ * filter by peer admits any peer's frame carrying a matching id.
+ */
+export class StreamIdentityError extends SessionError {
+    constructor(message) {
+        super(message);
+        this.name = 'StreamIdentityError';
+    }
+}
+/**
+ * One open stream.
+ *
+ * Inbound payloads are delivered to `for await` consumers and to
+ * {@link LeafStream.onMessage} listeners. Payloads that arrive before
+ * anyone consumes them are buffered in arrival order, so a page that
+ * opens a stream and awaits it a tick later loses nothing.
+ */
+export class LeafStream {
+    inner;
+    onClosed;
+    queues = new Set();
+    listeners = new Set();
+    pending = [];
+    closed = false;
+    /**
+     * This stream's wire id as a number, or `null` when the inner
+     * object's `stream_id_hex()` was not hex.
+     *
+     * The event JSON spells the id in **decimal** while the handle
+     * spells it in **hex**; comparing the two textually would drop
+     * every payload, so the comparison is numeric. Rust filters the
+     * event stream too — this is the exact check behind its substring
+     * one, and the reason a mismatch is a dropped payload here rather
+     * than someone else's bytes.
+     */
+    wireId;
+    /**
+     * The peer this stream addresses, as a number, or `null` when the
+     * inner object does not spell one.
+     *
+     * **The other half of a stream's identity, and the reason the id
+     * alone was not one.** A stream id is an application label scoped
+     * to a session, so two streams to two peers under the same id is
+     * the ordinary case — `openStream({ peer, streamId })` invites it
+     * — and the callback is handed the NODE-WIDE event vector. Keyed
+     * on the id alone, two wrappers both admitted whichever peer's
+     * frame arrived, so a page echoing what it received amplified one
+     * peer's payload onto the other's stream (R4-10). The key is
+     * `(peer, id)`.
+     *
+     * Read in the same hex spelling as the id and compared against the
+     * event's decimal `peer_node` the same way, so there is one
+     * conversion idiom in this file rather than two — a mismatch in
+     * either would fail the id comparison too, loudly.
+     */
+    peerId;
+    /**
+     * @internal — built by `BrowserNode.openStream` (a leader-local
+     * stream, whose `send` is synchronous) or by
+     * `MeshSession.openStream` (a proxied one, whose `send` is a
+     * promise because another tab puts the packet on the wire). A page
+     * writes `await stream.send(bytes)` either way.
+     *
+     * `onClosed` tells the owner it may forget this stream — the same
+     * shape {@link AsyncQueue} uses for a departing consumer. A node
+     * has to retain the streams it handed out to end them on its own
+     * close, and `BrowserNode` passes this so a page that opens and
+     * closes a stream per frame does not grow that set for the node's
+     * lifetime.
+     */
+    constructor(inner, onClosed, identity = 'required') {
+        this.inner = inner;
+        this.onClosed = onClosed;
+        this.wireId = u64FromHex(() => inner.stream_id_hex());
+        this.peerId = u64FromHex(() => inner.peer_node_hex());
+        if (identity === 'required' && this.peerId === null) {
+            // **Fail closed.** Every stream this package builds comes from
+            // its own wasm, where both the direct and the proxied handle
+            // report a peer, so an unreadable one is a broken build or a
+            // substituted object — not a stream with no peer. Admitting it
+            // would restore the id-only filter below, which is the R4-10
+            // cross-peer admixture, and it would do so silently.
+            throw new StreamIdentityError('the stream did not report a readable peer, so its frames cannot be attributed');
+        }
+        inner.on_message((event) => this.receive(event));
+    }
+    /** The authenticated peer this stream is with, 16 lowercase hex. */
+    get peerNode() {
+        return this.inner.peer_node_hex();
+    }
+    /**
+     * Whether this stream retransmits. Read from the leaf rather than
+     * from the options it was asked for, so it is the stream's own
+     * answer.
+     */
+    get reliability() {
+        return this.inner.is_reliable() ? 'reliable' : 'fireAndForget';
+    }
+    /** The stream's wire id, hex. */
+    get streamId() {
+        return this.inner.stream_id_hex();
+    }
+    /** Send one payload. Fragmentation at `MAX_PAYLOAD_SIZE` is the leaf's. */
+    async send(payload) {
+        if (this.closed)
+            throw new SessionError('the stream is closed');
+        try {
+            await this.inner.send(payload);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /** Listen for payloads. Returns a cancel handle. */
+    onMessage(listener) {
+        this.listeners.add(listener);
+        const buffered = this.pending.splice(0, this.pending.length);
+        for (const payload of buffered)
+            listener(payload);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    [Symbol.asyncIterator]() {
+        const queue = new AsyncQueue(() => this.queues.delete(queue));
+        this.queues.add(queue);
+        const buffered = this.pending.splice(0, this.pending.length);
+        for (const payload of buffered)
+            queue.push(payload);
+        if (this.closed)
+            queue.end();
+        return queue;
+    }
+    /** Close the stream and end every consumer. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const queue of [...this.queues])
+            queue.end();
+        this.queues.clear();
+        this.listeners.clear();
+        // Before the boundary call, so an owner's bookkeeping is correct
+        // even if a host-supplied wrapper's `close` throws.
+        this.onClosed?.();
+        this.inner.close();
+    }
+    /**
+     * One callback from the wasm boundary.
+     *
+     * Rust emits the node's `stream_data` event JSON; this is where
+     * it becomes the `Uint8Array` the public API promises. Bytes are
+     * taken as an already-decoded payload, which is what a
+     * host-supplied {@link LeafWasmStreamLike} may deliver.
+     */
+    receive(event) {
+        const payload = this.decode(event);
+        if (payload === null || this.closed)
+            return;
+        if (this.queues.size === 0 && this.listeners.size === 0) {
+            this.pending.push(payload);
+            return;
+        }
+        for (const listener of this.listeners) {
+            try {
+                listener(payload);
+            }
+            catch (error) {
+                // Same rule as the event hub: a listener's bug must not unwind
+                // through the wasm callback frame that called us.
+                console.error('[@net-mesh/browser] stream listener threw', error);
+            }
+        }
+        for (const queue of this.queues)
+            queue.push(payload);
+    }
+    decode(event) {
+        if (event instanceof Uint8Array)
+            return event;
+        if (typeof event !== 'string') {
+            console.error('[@net-mesh/browser] stream callback received', typeof event, 'not the leaf event JSON');
+            return null;
+        }
+        const parsed = parseEvent(event);
+        // The node's event stream carries more than this stream: Rust
+        // pre-filters, but the id it filters on is a substring match, so
+        // the exact one lives here.
+        if (parsed.type !== 'stream_data' || !/^\d+$/.test(parsed.streamId))
+            return null;
+        if (this.wireId !== null && BigInt(parsed.streamId) !== this.wireId)
+            return null;
+        // And the peer, because the id is only half of the identity. A
+        // frame whose peer is unattributable is dropped by a stream that
+        // knows its own: "some peer's bytes under my id" is precisely
+        // what this stream must not deliver. A stream whose HANDLE does
+        // not spell a peer keeps the id-only behaviour instead of
+        // dropping everything — the same disposition an unreadable id
+        // gets, one line above.
+        if (this.peerId !== null) {
+            if (!/^\d+$/.test(parsed.peerNode))
+                return null;
+            if (BigInt(parsed.peerNode) !== this.peerId)
+                return null;
+        }
+        return parsed.payload;
+    }
+}
+/**
+ * A `u64` the inner object spells in hex, as a number — or `null`
+ * when it does not spell one.
+ *
+ * A host-supplied wrapper (`identity: 'optional'`) may return
+ * something unreadable, and for that case a value that cannot be read
+ * must not become a filter that drops everything. For a stream this
+ * package built, the constructor has already refused.
+ */
+function u64FromHex(read) {
+    let hex;
+    try {
+        hex = read();
+    }
+    catch {
+        return null;
+    }
+    if (hex === undefined || !/^[0-9a-fA-F]{1,16}$/.test(hex))
+        return null;
+    return BigInt(`0x${hex}`);
+}

package/dist/three/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `@net-mesh/browser/three` — the store, bound to a scene graph.
+ *
+ * The adapter the Fleet demo grew, extracted because every game that
+ * renders a networked store writes the same twenty lines and gets the
+ * same two things wrong: it rebuilds objects that did not change, and
+ * it leaks the ones that went away.
+ *
+ * ## No runtime dependency on Three.js
+ *
+ * Nothing here imports `three`. The scene graph is a structural type —
+ * anything with `add` and `remove` — and the objects are whatever the
+ * caller's `create` returns. So the browser package's bundle does not
+ * grow by a renderer, and the same binding drives a Three.js scene, a
+ * canvas, or a test double.
+ *
+ * `three` is **not declared as a dependency of any kind** — not a
+ * peer dependency either, and the manifest says so by having no
+ * `peerDependencies` key. An earlier version of this comment called
+ * it an optional peer dependency, which would have had npm warn on a
+ * missing or mismatched `three`: a promise the manifest does not
+ * make. The types it would have supplied are not needed, because the
+ * ones here are structural.
+ *
+ * ## What it is for
+ *
+ * The store already shares the references of subtrees that did not
+ * change (`state.ts`'s reconciliation). That promise is worthless if
+ * the render layer rebuilds everything anyway, and it is exactly what
+ * a naive `for (const entity of Object.values(state.entities))` loop
+ * throws away. This binding turns it into the thing you wanted from
+ * it: an entity whose reference is unchanged is not touched, so a
+ * 60 Hz loop over a world where one ship moved does one update.
+ */
+/** The subset of `THREE.Object3D` a scene needs to expose. */
+export interface SceneGraphLike<O> {
+    add(child: O): unknown;
+    remove(child: O): unknown;
+}
+/** The subset of a store this binding reads. */
+export interface StoreLike<S> {
+    getState(): S;
+    subscribe(listener: (state: S, previous: S) => void): () => void;
+}
+/** How one kind of entity becomes, and stays, an object in the scene. */
+export interface EntityBinding<E, O> {
+    /**
+     * Build the object for an entity that has just appeared.
+     *
+     * Called once per id. Add it to the scene yourself only if you need
+     * a parent other than the one passed to {@link bindEntities}.
+     */
+    create(entity: E, id: string): O;
+    /**
+     * Bring an existing object up to date.
+     *
+     * Called only when the entity's REFERENCE changed, which is the
+     * whole point: the store shares unchanged subtrees, so an entity
+     * nothing touched costs nothing here.
+     */
+    update(object: O, entity: E, id: string): void;
+    /**
+     * Let go of an object whose entity is gone.
+     *
+     * The binding removes it from the scene first. Disposing geometries
+     * and materials is yours, because only you know which are shared —
+     * and Three.js leaks both if nobody does it.
+     */
+    remove?(object: O, id: string): void;
+}
+export interface BindEntitiesOptions<S, E, O> {
+    readonly store: StoreLike<S>;
+    readonly scene: SceneGraphLike<O>;
+    /** The entities to render, by stable id. */
+    readonly select: (state: S) => Readonly<Record<string, E>>;
+    readonly binding: EntityBinding<E, O>;
+    /**
+     * Where a `create`, `update` or `remove` that throws is reported.
+     *
+     * One entity's bug must not stop the rest of the frame — the same
+     * convention the store's own listeners use. Defaults to
+     * `console.error`.
+     */
+    readonly onError?: (error: unknown, id: string) => void;
+}
+/** A live binding between a store and a scene. */
+export interface SceneBinding<O> {
+    /**
+     * Reconcile now, against the store's current state.
+     *
+     * Called for you on every change; call it yourself from a render
+     * loop if you would rather pull than be pushed.
+     */
+    apply(): void;
+    /** The object currently rendering an entity, if any. */
+    object(id: string): O | undefined;
+    /** How many objects the binding holds. */
+    readonly size: number;
+    /** Unsubscribe and remove every object from the scene. */
+    dispose(): void;
+}
+/**
+ * Bind a store's entities to a scene graph.
+ *
+ * Reconciles on every published revision: new ids are created and
+ * added, changed ones updated, absent ones removed. An entity whose
+ * reference is unchanged is skipped entirely.
+ */
+export declare function bindEntities<S, E, O>(options: BindEntitiesOptions<S, E, O>): SceneBinding<O>;

package/dist/three/index.js

@@ -0,0 +1,130 @@
+/**
+ * `@net-mesh/browser/three` — the store, bound to a scene graph.
+ *
+ * The adapter the Fleet demo grew, extracted because every game that
+ * renders a networked store writes the same twenty lines and gets the
+ * same two things wrong: it rebuilds objects that did not change, and
+ * it leaks the ones that went away.
+ *
+ * ## No runtime dependency on Three.js
+ *
+ * Nothing here imports `three`. The scene graph is a structural type —
+ * anything with `add` and `remove` — and the objects are whatever the
+ * caller's `create` returns. So the browser package's bundle does not
+ * grow by a renderer, and the same binding drives a Three.js scene, a
+ * canvas, or a test double.
+ *
+ * `three` is **not declared as a dependency of any kind** — not a
+ * peer dependency either, and the manifest says so by having no
+ * `peerDependencies` key. An earlier version of this comment called
+ * it an optional peer dependency, which would have had npm warn on a
+ * missing or mismatched `three`: a promise the manifest does not
+ * make. The types it would have supplied are not needed, because the
+ * ones here are structural.
+ *
+ * ## What it is for
+ *
+ * The store already shares the references of subtrees that did not
+ * change (`state.ts`'s reconciliation). That promise is worthless if
+ * the render layer rebuilds everything anyway, and it is exactly what
+ * a naive `for (const entity of Object.values(state.entities))` loop
+ * throws away. This binding turns it into the thing you wanted from
+ * it: an entity whose reference is unchanged is not touched, so a
+ * 60 Hz loop over a world where one ship moved does one update.
+ */
+function report(onError, error, id) {
+    if (onError !== undefined) {
+        onError(error, id);
+        return;
+    }
+    // Same convention as the store's listener isolation: report it
+    // where a page can see it, keep the rest of the frame running.
+    console.error(`[net-mesh/three] entity ${id}:`, error);
+}
+/**
+ * Bind a store's entities to a scene graph.
+ *
+ * Reconciles on every published revision: new ids are created and
+ * added, changed ones updated, absent ones removed. An entity whose
+ * reference is unchanged is skipped entirely.
+ */
+export function bindEntities(options) {
+    const objects = new Map();
+    /** The entity each object was last rendered from, by reference. */
+    const rendered = new Map();
+    let live = true;
+    function apply() {
+        if (!live)
+            return;
+        const entities = options.select(options.store.getState());
+        for (const id of Object.keys(entities)) {
+            const entity = entities[id];
+            const existing = objects.get(id);
+            if (existing === undefined) {
+                try {
+                    const created = options.binding.create(entity, id);
+                    objects.set(id, created);
+                    rendered.set(id, entity);
+                    options.scene.add(created);
+                }
+                catch (error) {
+                    report(options.onError, error, id);
+                }
+                continue;
+            }
+            // The reference comparison the store's reconciliation exists to
+            // make possible. `Object.is`, not a deep compare: a deep
+            // compare per entity per frame is the cost this avoids.
+            if (Object.is(rendered.get(id), entity))
+                continue;
+            rendered.set(id, entity);
+            try {
+                options.binding.update(existing, entity, id);
+            }
+            catch (error) {
+                report(options.onError, error, id);
+            }
+        }
+        for (const [id, object] of [...objects]) {
+            if (Object.prototype.hasOwnProperty.call(entities, id))
+                continue;
+            objects.delete(id);
+            rendered.delete(id);
+            options.scene.remove(object);
+            try {
+                options.binding.remove?.(object, id);
+            }
+            catch (error) {
+                report(options.onError, error, id);
+            }
+        }
+    }
+    const unsubscribe = options.store.subscribe(() => {
+        apply();
+    });
+    apply();
+    return {
+        apply,
+        object: id => objects.get(id),
+        get size() {
+            return objects.size;
+        },
+        dispose: () => {
+            if (!live)
+                return;
+            live = false;
+            unsubscribe();
+            for (const [id, object] of [...objects]) {
+                objects.delete(id);
+                rendered.delete(id);
+                options.scene.remove(object);
+                try {
+                    options.binding.remove?.(object, id);
+                }
+                catch (error) {
+                    report(options.onError, error, id);
+                }
+            }
+        },
+    };
+}