@net-mesh/browser 0.42.0 → 0.44.0

package/dist/stream.js

@@ -17,13 +17,24 @@ export class StreamIdentityError extends SessionError {
         this.name = 'StreamIdentityError';
     }
 }
+/** Most frames a {@link LeafStream} buffers before its first consumer. */
+export const LEAF_STREAM_PENDING_MAX_FRAMES = 1024;
+/** Most bytes a {@link LeafStream} buffers before its first consumer. */
+export const LEAF_STREAM_PENDING_MAX_BYTES = 1 << 20;
 /**
  * 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.
+ * opens a stream and awaits it a tick later loses nothing — up to
+ * {@link LEAF_STREAM_PENDING_MAX_FRAMES} frames and
+ * {@link LEAF_STREAM_PENDING_MAX_BYTES} bytes. Past either bound the
+ * OLDEST buffered frame is dropped and counted in
+ * {@link LeafStream.droppedBeforeConsumer} (a single frame larger than the
+ * byte bound is never buffered, and is counted there too): a stream used only to send
+ * (the store, netcode and region-link layers read inbound traffic
+ * elsewhere) must not keep every frame the peer sends for its lifetime.
  */
 export class LeafStream {
     inner;
@@ -31,7 +42,11 @@ export class LeafStream {
     queues = new Set();
     listeners = new Set();
     pending = [];
+    pendingBytes = 0;
+    dropped = 0;
     closed = false;
+    /** Why the SESSION closed this stream, when it did so for a leader change. */
+    retiredBy = null;
     /**
      * This stream's wire id as a number, or `null` when the inner
      * object's `stream_id_hex()` was not hex.
@@ -94,6 +109,13 @@ export class LeafStream {
         }
         inner.on_message((event) => this.receive(event));
     }
+    /**
+     * Frames dropped from the pre-consumer buffer because no `for await`
+     * consumer or `onMessage` listener was attached and it was full.
+     */
+    get droppedBeforeConsumer() {
+        return this.dropped;
+    }
     /** The authenticated peer this stream is with, 16 lowercase hex. */
     get peerNode() {
         return this.inner.peer_node_hex();
@@ -113,7 +135,7 @@ export class LeafStream {
     /** 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');
+            throw new SessionError(this.retiredBy ?? 'the stream is closed');
         try {
             await this.inner.send(payload);
         }
@@ -124,7 +146,7 @@ export class LeafStream {
     /** Listen for payloads. Returns a cancel handle. */
     onMessage(listener) {
         this.listeners.add(listener);
-        const buffered = this.pending.splice(0, this.pending.length);
+        const buffered = this.drainPending();
         for (const payload of buffered)
             listener(payload);
         return () => {
@@ -134,13 +156,26 @@ export class LeafStream {
     [Symbol.asyncIterator]() {
         const queue = new AsyncQueue(() => this.queues.delete(queue));
         this.queues.add(queue);
-        const buffered = this.pending.splice(0, this.pending.length);
+        const buffered = this.drainPending();
         for (const payload of buffered)
             queue.push(payload);
         if (this.closed)
             queue.end();
         return queue;
     }
+    /**
+     * @internal — the session closing this stream because the leader it
+     * was opened on is gone. Later sends fail with the leaf's own
+     * reopenable wording ("stale stream handle"), so a store that cached
+     * the stream reopens it on the new leader instead of failing every
+     * frame forever (SDK audit 2026-10-11).
+     */
+    retire(reason) {
+        if (this.closed)
+            return;
+        this.retiredBy = reason;
+        this.close();
+    }
     /** Close the stream and end every consumer. */
     close() {
         if (this.closed)
@@ -163,12 +198,39 @@ export class LeafStream {
      * taken as an already-decoded payload, which is what a
      * host-supplied {@link LeafWasmStreamLike} may deliver.
      */
+    /**
+     * Hand the pre-consumer buffer over, emptying it — count included. The
+     * byte count stayed at the drained total, so after a consumer drained the
+     * buffer and detached, rebuffering tripped the byte cap almost at once
+     * and evicted all but the newest frame on nearly every arrival (code
+     * review 2026-10-11, BROWSER-1).
+     */
+    drainPending() {
+        this.pendingBytes = 0;
+        return this.pending.splice(0, this.pending.length);
+    }
     receive(event) {
         const payload = this.decode(event);
         if (payload === null || this.closed)
             return;
         if (this.queues.size === 0 && this.listeners.size === 0) {
+            // A single frame over the byte cap is dropped and counted rather
+            // than buffered: the eviction loop below stops at one frame, so it
+            // would otherwise sit there past the cap (cubic review of PR #1228).
+            if (payload.byteLength > LEAF_STREAM_PENDING_MAX_BYTES) {
+                this.dropped += 1;
+                return;
+            }
             this.pending.push(payload);
+            this.pendingBytes += payload.byteLength;
+            // Bounded (SDK audit 2026-10-11): unbounded, an unread stream grew
+            // at the peer's send rate until the tab ran out of memory.
+            while (this.pending.length > LEAF_STREAM_PENDING_MAX_FRAMES ||
+                this.pendingBytes > LEAF_STREAM_PENDING_MAX_BYTES) {
+                const oldest = this.pending.shift();
+                this.pendingBytes -= oldest.byteLength;
+                this.dropped += 1;
+            }
             return;
         }
         for (const listener of this.listeners) {

package/dist/udp-probe.d.ts

@@ -53,7 +53,12 @@ export type StunProbeOutcome =
     readonly type: 'unanswered';
     readonly detail: string;
 }
-/** The probe was not run — no address to aim at, or it was disabled. */
+/**
+ * The probe established nothing either way: it was not run (no address
+ * to aim at, disabled, or the connection failed before gathering), or
+ * it ran and was inconclusive (gathering completed with neither an
+ * answer nor a "no response" report). Never evidence of blocked UDP.
+ */
  | {
     readonly type: 'notRun';
     readonly reason: string;
@@ -76,6 +81,10 @@ export type ProbeEvent = {
 /** The probe connection's ICE state became `failed`. */
  | {
     readonly ice: 'failed';
+}
+/** Gathering completed (the end-of-candidates signal). */
+ | {
+    readonly gathering: 'complete';
 };
 /**
  * Is this candidate line server-reflexive? The `typ` token followed by
@@ -98,10 +107,19 @@ export declare function probeEventAnswers(event: ProbeEvent): boolean;
  * event answers, `notRun` when the engine failed the connection before
  * gathering a single candidate (nothing was sent, so silence is not
  * evidence — measured: Firefox without a media permission on an
- * IPv6-only network with no IPv4 route), `unanswered` otherwise. The
- * Rust probe's `probe_verdict`, the same three answers.
+ * IPv6-only network with no IPv4 route) or when gathering completed with
+ * neither an answer nor a "no response" report (inconclusive),
+ * `unanswered` otherwise. The Rust probe's `probe_verdict`, the same
+ * three answers.
  */
 export declare function stunProbeVerdict(events: readonly ProbeEvent[]): 'answered' | 'unanswered' | 'notRun';
+/**
+ * Is this a `typ host` candidate whose address is a literal publicly
+ * routable IP (not private, loopback, link-local, CGNAT, unique-local or
+ * unspecified)? An obfuscated `.local` address is not known public. Mirrors
+ * the Rust `host_candidate_is_public`.
+ */
+export declare function hostCandidateIsPublic(line: string): boolean;
 /** {@link probeEventAnswers} over everything one probe reported. */
 export declare function stunProbeAnswered(events: readonly ProbeEvent[]): boolean;
 /** One endpoint and what probing it established. */

package/dist/udp-probe.js

@@ -61,15 +61,71 @@ export function probeEventAnswers(event) {
  * event answers, `notRun` when the engine failed the connection before
  * gathering a single candidate (nothing was sent, so silence is not
  * evidence — measured: Firefox without a media permission on an
- * IPv6-only network with no IPv4 route), `unanswered` otherwise. The
- * Rust probe's `probe_verdict`, the same three answers.
+ * IPv6-only network with no IPv4 route) or when gathering completed with
+ * neither an answer nor a "no response" report (inconclusive),
+ * `unanswered` otherwise. The Rust probe's `probe_verdict`, the same
+ * three answers.
  */
 export function stunProbeVerdict(events) {
     if (events.some(probeEventAnswers))
         return 'answered';
     const gathered = events.some((event) => 'candidate' in event);
     const failed = events.some((event) => 'ice' in event && event.ice === 'failed');
-    return failed && !gathered ? 'notRun' : 'unanswered';
+    if (failed && !gathered)
+        return 'notRun';
+    // Gathering that COMPLETED with no reflexive candidate and no "no
+    // response" report is inconclusive ONLY when a host candidate carried a
+    // literal public address: an engine may suppress a srflx equal to it, so
+    // a host with no NAT would otherwise read as `udp-blocked` (SDK audit
+    // 2026-10-11). Behind NAT the srflx is never suppressed, so its absence
+    // is silence — what blocked UDP looks like in Chromium (browser matrix,
+    // PR #1228). Same rule as the Rust `probe_verdict`.
+    const completed = events.some((event) => 'gathering' in event);
+    const reportedNoResponse = events.some((event) => 'error' in event && event.error >= STUN_NO_RESPONSE_CODE);
+    const publicHost = events.some((event) => 'candidate' in event && hostCandidateIsPublic(event.candidate));
+    return completed && !reportedNoResponse && publicHost ? 'notRun' : 'unanswered';
+}
+/**
+ * Is this a `typ host` candidate whose address is a literal publicly
+ * routable IP (not private, loopback, link-local, CGNAT, unique-local or
+ * unspecified)? An obfuscated `.local` address is not known public. Mirrors
+ * the Rust `host_candidate_is_public`.
+ */
+export function hostCandidateIsPublic(line) {
+    const tokens = line.trim().split(/\s+/);
+    let host = false;
+    for (let i = 0; i + 1 < tokens.length; i += 1) {
+        if (tokens[i] === 'typ' && tokens[i + 1] === 'host')
+            host = true;
+    }
+    const addr = tokens[4];
+    if (!host || addr === undefined)
+        return false;
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(addr);
+    if (v4 !== null) {
+        const o = v4.slice(1).map(Number);
+        if (o.some((n) => n > 255))
+            return false;
+        const [a, b] = o;
+        const isPrivate = a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+        const loopback = a === 127;
+        const linkLocal = a === 169 && b === 254;
+        const unspecified = o.every((n) => n === 0);
+        const broadcast = o.every((n) => n === 255);
+        const cgnat = a === 100 && (b & 0xc0) === 64;
+        return !(isPrivate || loopback || linkLocal || unspecified || broadcast || cgnat);
+    }
+    if (!addr.includes(':') || !/^[0-9a-f:.]+$/i.test(addr))
+        return false;
+    const lower = addr.toLowerCase();
+    if (lower === '::' || lower === '::1')
+        return false;
+    const first = Number.parseInt(lower.startsWith(':') ? '0' : lower.split(':')[0] ?? '0', 16);
+    if (Number.isNaN(first))
+        return false;
+    const uniqueLocal = (first & 0xfe00) === 0xfc00;
+    const linkLocalV6 = (first & 0xffc0) === 0xfe80;
+    return !(uniqueLocal || linkLocalV6);
 }
 /** {@link probeEventAnswers} over everything one probe reported. */
 export function stunProbeAnswered(events) {
@@ -154,11 +210,24 @@ export async function probeStunBinding(rtcAddr, options = {}) {
     // load-bearing rather than a safety net.
     let noResponse = null;
     const timer = setTimeout(() => settle({ type: 'unanswered', detail: noResponse ?? 'no answer inside the probe deadline' }), timeoutMs);
+    // Completion with no reflexive candidate is inconclusive only when no
+    // "no response" report came AND a host candidate carried a literal
+    // public address: libwebrtc drops a reflexive candidate equal to it, so
+    // the anchor can have answered with nothing visible. Behind NAT, or
+    // with only `.local` hosts (Firefox, which also makes no "no response"
+    // report), the srflx is never suppressed and its absence is silence
+    // (`stunProbeVerdict`, the same rule).
+    let publicHost = false;
     const gatheringDone = () => {
-        settle({
-            type: 'unanswered',
-            detail: noResponse ?? 'gathering completed with no reflexive candidate',
-        });
+        if (noResponse === null && publicHost) {
+            settle({
+                type: 'notRun',
+                reason: 'gathering completed beside a public host with no reflexive candidate and no "no response" report: ' +
+                    'inconclusive',
+            });
+            return;
+        }
+        settle({ type: 'unanswered', detail: noResponse ?? 'gathering completed with no reflexive candidate' });
     };
     // Did the engine gather anything at all? A connection it fails
     // before the first candidate is one it could not gather for, and
@@ -179,6 +248,8 @@ export async function probeStunBinding(rtcAddr, options = {}) {
             return;
         }
         gathered = true;
+        if (hostCandidateIsPublic(candidate.candidate))
+            publicHost = true;
         // Host candidates are gathered regardless of what the network does
         // to UDP — Chromium even hides them behind an mDNS `.local` name —
         // so only a reflexive one is evidence.

package/dist/world/link.d.ts

@@ -109,7 +109,16 @@ export interface RegionHandoffsOptions<E> {
     };
     /** Outcomes: `moved`, `refused`, `unresolved` (source), `admitted` (target). */
     onEvent?(event: HandoffEvent): void;
+    /** Entity handoffs: re-offer, give up, and how long a decision is remembered. */
     readonly timing?: HandoffTiming;
+    /**
+     * Forwarded actions ({@link RegionHandoffs.forward}), when they need other
+     * timing than entity handoffs: a hit is worthless after half a second,
+     * while a moving entity must not be given up that soon (it would be live
+     * nowhere) nor forgotten while its offer may still be re-sent (it could
+     * be admitted twice). Default: `timing`.
+     */
+    readonly actionTiming?: HandoffTiming;
     /** How often to re-offer and prune, ms. Default 100. */
     readonly tickMs?: number;
     readonly now?: () => number;

package/dist/world/link.js

@@ -264,9 +264,10 @@ export function regionHandoffs(options) {
             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 actionTiming = options.actionTiming ?? options.timing;
+    const retryMs = actionTiming?.retryMs ?? 250;
+    const giveUpMs = actionTiming?.giveUpMs ?? 60_000;
+    const retentionMs = actionTiming?.handledRetentionMs ?? 600_000;
     const stop = options.link.onMessage(body => {
         if (closed)
             return;

package/dist/world/regions.d.ts

@@ -44,8 +44,15 @@ export declare function regionsAround(x: number, z: number, options: {
 }): 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;
+/**
+ * How often region hosts re-announce: an announcement is a lease, held
+ * for the leaf's 300 s TTL. 30 s, not 2 s, for the reason
+ * `LOBBY_ANNOUNCE_MS` gives: re-announcements flood through the anchor to
+ * every peer, and at 2 s they saturated a host's anchor link at 64 nodes.
+ * A failed announcement is retried sooner, as a lobby's is
+ * (`ANNOUNCE_RETRY_MS`, doubling up to `ANNOUNCE_RETRY_MAX_MS`).
+ */
+export declare const REGION_ANNOUNCE_MS = 30000;
 /**
  * Announce that this node hosts `regions` of `world`, and keep announcing
  * (an announcement is a lease). `announce` replaces a node's tags, so pass

package/dist/world/regions.js

@@ -27,6 +27,7 @@
  * directory (`handoffLink({ peerOf: directory.peerOf })`) needs the list:
  * otherwise a node that announces a region could also send offers as it.
  */
+import { ANNOUNCE_RETRY_MAX_MS, ANNOUNCE_RETRY_MS } from '../lobby.js';
 import { nodeHexOf } from '../store/host.js';
 import { joinStore } from '../store/join.js';
 /** Region `r:<rx>:<rz>` for a position, with regions `size` units square. */
@@ -51,8 +52,15 @@ export function regionsAround(x, z, options) {
 export function regionTag(world, region) {
     return `net-world:${world}:region:${region}`;
 }
-/** How often region hosts re-announce: an announcement is a lease. */
-export const REGION_ANNOUNCE_MS = 2_000;
+/**
+ * How often region hosts re-announce: an announcement is a lease, held
+ * for the leaf's 300 s TTL. 30 s, not 2 s, for the reason
+ * `LOBBY_ANNOUNCE_MS` gives: re-announcements flood through the anchor to
+ * every peer, and at 2 s they saturated a host's anchor link at 64 nodes.
+ * A failed announcement is retried sooner, as a lobby's is
+ * (`ANNOUNCE_RETRY_MS`, doubling up to `ANNOUNCE_RETRY_MAX_MS`).
+ */
+export const REGION_ANNOUNCE_MS = 30_000;
 /**
  * Announce that this node hosts `regions` of `world`, and keep announcing
  * (an announcement is a lease). `announce` replaces a node's tags, so pass
@@ -61,9 +69,29 @@ export const REGION_ANNOUNCE_MS = 2_000;
 export function announceRegions(node, world, regions, options = {}) {
     const tags = [...(options.tags ?? []), ...regions.map(region => regionTag(world, region))];
     let stopped = false;
+    // A failed announcement is retried on a short backoff of its own: a
+    // region nobody can find for a whole lease refresh is a hole in the map.
+    let retry = null;
+    let retryMs = ANNOUNCE_RETRY_MS;
     const once = () => {
-        if (!stopped)
-            void node.announce(tags).catch(() => undefined);
+        if (stopped)
+            return;
+        if (retry !== null) {
+            clearTimeout(retry);
+            retry = null;
+        }
+        void node.announce(tags).then(() => {
+            retryMs = ANNOUNCE_RETRY_MS;
+        }, () => {
+            if (stopped || retry !== null)
+                return;
+            retry = setTimeout(() => {
+                retry = null;
+                once();
+            }, retryMs);
+            retry.unref?.();
+            retryMs = Math.min(retryMs * 2, ANNOUNCE_RETRY_MAX_MS);
+        });
     };
     once();
     const timer = setInterval(once, options.everyMs ?? REGION_ANNOUNCE_MS);
@@ -71,6 +99,8 @@ export function announceRegions(node, world, regions, options = {}) {
     return () => {
         stopped = true;
         clearInterval(timer);
+        if (retry !== null)
+            clearTimeout(retry);
     };
 }
 /** A region directory over the mesh's signed announcements. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/browser",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Browser-native Net mesh leaf \u2014 idiomatic TypeScript over the net-mesh-leaf wasm node",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,8 @@
     "check:package": "node scripts/check-package.mjs",
     "test": "tsc -p tsconfig.test.json && vitest run",
     "test:watch": "vitest",
-    "bench:world": "node scripts/bench-world.mjs"
+    "bench:world": "node scripts/bench-world.mjs",
+    "bench:netcode": "node scripts/bench-netcode.mjs"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",