@net-mesh/browser 0.37.1 → 0.38.1

package/CHANGELOG.md

@@ -14,6 +14,54 @@ missing method at the call site rather than at install time. Unlike
 `@net-mesh/sdk`, this package never depends on `@net-mesh/core` — see
 the README on why it is a sibling package rather than a sub-path.
 
+## 0.38.1 — dual-stack anchors
+
+An anchor can now serve IPv4 and IPv6 players at once
+(`net-mesh anchor serve --rtc-bind 0.0.0.0:7101 --rtc-bind '[::]:7101'`).
+What a page sees:
+
+- **The anchor needs a STUN endpoint in each family too**
+  (`--rtc-stun-bind` of each family). Without a media permission a
+  browser's only candidate on a network is the server-reflexive one from
+  a STUN server of that family. The default ICE servers now use every
+  STUN endpoint the anchor publishes (`stun_addrs`).
+- **Firefox on a pure IPv6-only network (no IPv4 route) is unsupported.**
+  It gathers nothing there, and the connect fails `ice-timeout`, not
+  `udp-blocked`. On 464XLAT networks, as mobile IPv6-only networks are,
+  it connects. Chromium works on both.
+- **A probe the engine failed before it gathered reads `notRun`**, not
+  `unanswered`, so it can never produce `udp-blocked`.
+- **Public anchors.** An anchor started with `--open-games` issues a
+  credential for any game id from any page, keyed on the page's origin
+  and the id, so no operator setup is needed. `requestCredential({
+  anchorUrl, game })` is unchanged. Two sites naming their game alike
+  get two separate games and never see each other's lobbies.
+- **Connecting needs no change.** The anchor's answer offers a host
+  candidate per family, and the browser pairs with whichever its network
+  reaches.
+- **`udp-blocked` is stricter and says less.** The leaf now probes
+  **every** endpoint the anchor published, under one deadline, and
+  reports `udp-blocked` only when the anchor answered over HTTPS and
+  **every** probe went unanswered. One answered family, an unrun probe,
+  or no endpoints at all stays `ice-timeout`. So an IPv6-only player
+  whose IPv4 probe is silent is no longer told UDP is blocked.
+- **The `udp-blocked` message states the observation, not a cause.** It
+  now reads `no UDP response from the anchor's advertised endpoints: its
+  HTTPS bootstrap succeeded but STUN bindings to … went unanswered`,
+  because blocked UDP, a stopped UDP listener, a wrong advertised address
+  and loss all look the same. The `kind` is unchanged. Match on `kind`,
+  never on the message.
+- **`UdpBlockedEvidence.probedAll`** lists every endpoint probed; `probed`
+  is still the first.
+- **`ConnectedEvent.rtcAddrs`** lists every endpoint the anchor published,
+  primary first. `rtcAddr` is still the primary.
+- **The Rust and TypeScript probes agree** on what "answered" means: a
+  server-reflexive candidate, or a STUN error response (code below 700).
+  The wasm probe used to ignore error responses.
+- **New exports:** `classifyRtcFailureAll`, `probeStunBindings`,
+  `probeEventAnswers`, `stunProbeAnswered`, `candidateLineIsReflexive`,
+  and the `EndpointProbe` and `ProbeEvent` types.
+
 ## 0.37.0 — the first npm release
 
 Everything in this file ships in 0.37.0, the package's first release on npm.

package/dist/errors.d.ts

@@ -33,13 +33,19 @@ export interface UdpBlockedEvidence {
     readonly stunProbeFailed: true;
     /** The address the probe was aimed at, so the claim names its subject. */
     readonly probed: string;
+    /**
+     * Every endpoint probed, `probed` first; each went unanswered. A
+     * dual-stack anchor publishes one per family, and one answered probe
+     * means UDP works for that family, which is never this evidence.
+     */
+    readonly probedAll: readonly string[];
 }
 /**
  * `UdpBlockedEvidence` only when both observations hold; `null`
  * otherwise, which is the caller's instruction to stay with
  * `ice-timeout`. Mirror of `UdpBlockedEvidence::new`.
  */
-export declare function udpBlockedEvidence(bootstrapOk: boolean, stunProbeFailed: boolean, probed: string): UdpBlockedEvidence | null;
+export declare function udpBlockedEvidence(bootstrapOk: boolean, stunProbeFailed: boolean, probed: string, probedAll?: readonly string[]): UdpBlockedEvidence | null;
 /** Why an RTC attempt did not produce a DataChannel. */
 export type RtcErrorFailure = {
     readonly type: 'iceTimeout';

package/dist/errors.js

@@ -20,10 +20,13 @@
  * otherwise, which is the caller's instruction to stay with
  * `ice-timeout`. Mirror of `UdpBlockedEvidence::new`.
  */
-export function udpBlockedEvidence(bootstrapOk, stunProbeFailed, probed) {
+export function udpBlockedEvidence(bootstrapOk, stunProbeFailed, probed, probedAll = [probed]) {
     if (!bootstrapOk || !stunProbeFailed || probed.length === 0)
         return null;
-    return { bootstrapOk: true, stunProbeFailed: true, probed };
+    if (probedAll.length === 0 || probedAll[0] !== probed || probedAll.some((addr) => addr.length === 0)) {
+        return null;
+    }
+    return { bootstrapOk: true, stunProbeFailed: true, probed, probedAll: [...probedAll] };
 }
 /** The base class of everything this package rejects with. */
 export class LeafError extends Error {
@@ -564,8 +567,11 @@ function rtcDisplay(failure) {
         case 'iceTimeout':
             return ICE_TIMEOUT_DISPLAY;
         case 'udpBlocked':
-            return ("UDP appears blocked: the anchor's HTTPS bootstrap succeeded " +
-                `but a STUN binding to ${failure.evidence.probed} was unanswered`);
+            // An observation, not a cause: blocked UDP, a stopped UDP
+            // listener, a wrong advertised address or loss all look like
+            // this. Byte-identical to the Rust `Display`.
+            return ("no UDP response from the anchor's advertised endpoints: its HTTPS bootstrap succeeded " +
+                `but STUN bindings to ${failure.evidence.probedAll.join(', ')} went unanswered`);
         case 'channelClosed':
             return `the DataChannel closed: ${failure.detail}`;
         case 'unsupported':
@@ -672,10 +678,12 @@ export function parseLeafError(message) {
 export function parseRtcFailure(text) {
     if (text === ICE_TIMEOUT_DISPLAY)
         return { type: 'iceTimeout' };
-    const blocked = /^UDP appears blocked: the anchor's HTTPS bootstrap succeeded but a STUN binding to (.+) was unanswered$/.exec(text);
+    const blocked = /^no UDP response from the anchor's advertised endpoints: its HTTPS bootstrap succeeded but STUN bindings to (.+) went unanswered$/.exec(text);
     if (blocked) {
-        const probed = blocked[1] ?? '';
-        const evidence = udpBlockedEvidence(true, true, probed);
+        // Endpoints are `host:port` or `[v6]:port`; neither holds ", ".
+        const probedAll = (blocked[1] ?? '').split(', ');
+        const probed = probedAll[0] ?? '';
+        const evidence = udpBlockedEvidence(true, true, probed, probedAll);
         // The regex matched the message the Rust side only emits when it
         // holds the evidence, so `probed` is non-empty and this is
         // `UdpBlockedEvidence`; an empty subject is not evidence.

package/dist/events.d.ts

@@ -42,6 +42,12 @@ export interface ConnectedEvent {
      * none.
      */
     readonly rtcAddr: string | null;
+    /**
+     * **Every** endpoint that anchor published, primary first: one per
+     * family on a dual-stack anchor, `[rtcAddr]` on any other, empty when
+     * it published none. The STUN probe aims at all of them.
+     */
+    readonly rtcAddrs: readonly string[];
 }
 /** The session went away. */
 export interface DisconnectedEvent {

package/dist/events.js

@@ -72,6 +72,7 @@ export function parseEvent(json) {
                 nodeIdHex: str(fields, 'node_id_hex'),
                 peerNode: str(fields, 'peer_node'),
                 rtcAddr: optionalStr(fields, 'rtc_addr'),
+                rtcAddrs: rtcAddrsOf(fields),
             };
         case 'disconnected':
             return { type: 'disconnected', reason: str(fields, 'reason') };
@@ -247,6 +248,18 @@ function str(fields, key) {
         return String(value);
     return '';
 }
+/**
+ * `rtc_addrs` when the leaf sent a list (a dual-stack anchor), else
+ * `[rtc_addr]`, else empty: the rule `GET /rtc/anchor` documents.
+ */
+function rtcAddrsOf(fields) {
+    const list = fields.rtc_addrs;
+    if (Array.isArray(list)) {
+        return list.filter((addr) => typeof addr === 'string' && addr.length > 0);
+    }
+    const single = optionalStr(fields, 'rtc_addr');
+    return single === null ? [] : [single];
+}
 function optionalStr(fields, key) {
     const value = fields[key];
     return typeof value === 'string' && value.length > 0 ? value : null;