@torrent-tv/proxy 2.9.19 → 2.9.21

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.9.23
+
+- **New**: Symmetric-NAT port prediction for WebRTC (roadmap step 4; `webrtc-manager.js` + `nat-classifier.js` delta + `cli.js` wiring). When the startup NAT classification reports a **symmetric** NAT, for each real IPv4 `srflx` candidate the proxy also offers predicted-port candidates at `base + delta*k` (k = 1..16, `delta` = the per-destination external-port step measured at startup), each with a unique ICE foundation. The browser probes these too; if one matches the external port the NAT assigns for the proxy→browser path, ICE connects — the practical, signalling-only form of the birthday-paradox trick (no node-datachannel changes, no extra sockets). **Scope**: covers sequential/predictable symmetric NATs; a fully-random symmetric NAT (where the true 256-socket birthday would be needed) is not solved by this and is out of reach on the node-datachannel stack. No-op for cone NATs (the fixed-port mapping already suffices) and IPv6 (no NAT). Diagnostics: logs the injected predicted ports per session (`symmetric NAT (delta=D) — injecting N predicted srflx candidates: …`); combined with the existing `selected pair local=[…]` log this shows whether a predicted port won. NOTE: could not be exercised end-to-end — the dev's home NAT is cone; needs a symmetric-NAT vantage to verify in the field (the logging is there to diagnose it when it appears).
+
+## 2.9.22
+
+- **Fix**: The proxy no longer crashes on a repeat/remote WebRTC session (regression from 2.9.18). Two causes, both fixed: (1) `webrtc-manager.handleSignal` called `setRemoteDescription`/`addRemoteCandidate` with **no try/catch**, so when node-datachannel threw synchronously (`Failed to gather local ICE candidates`) the whole process died — killing every viewer and the tunnel — and was restarted by s6. It now contains the error per session (logs + closes only that session, never throws out of the handler). (2) Root cause of the gather failure: 2.9.18 set `enableIceUdpMux` per-PeerConnection but with **no persistent mux owner**, so the shared UDP socket was bound/freed with each connection — a session opened while a just-closed one still held the fixed port could not bind it and failed to gather. Fixed by creating ONE persistent `IceUdpMuxListener` on the fixed UDP port once at startup (owned by the WebRTC manager for the proxy's whole lifetime, released on shutdown via `dispose()`); every session keeps `enableIceUdpMux` + the same port and demuxes over the shared socket by ICE ufrag. This keeps the clean single-port model (one UDP port, one UPnP mapping, one reachable endpoint) while surviving session churn. Verified against libdatachannel issue #861 and locally: 5 sequential + 2 concurrent PeerConnections all gather on the one port with no error, and the srflx candidate carries the fixed port.
+
+## 2.9.21
+
+- **Chore**: Diagnostic — the `/api/sources/:key/stats` route now logs the real swarm state on every poll: `[stats] <key> peers=N down=NKB/s file=N% header=down/totalB`. This surfaces a cold-start download stall (0 peers / header not advancing), which is what makes `POST /api/playback-plan` block on the codec probe until the browser's data-channel request times out. (Diagnosis: on the first/cold attempt the file header has not downloaded within ~60 s — likely worsened by `uTP not supported` on arm64/musl limiting peers — so the blocking probe times out; a warm attempt minutes later, with the header already cached, probes in ~25 ms and plays. Verified by the same torrent failing cold on cellular and playing warm on desktop.)
+
 ## 2.9.20
 
 - **New**: Startup NAT classification (`services/nat-classifier.js`, dependency-free — `node:dgram` + `node:crypto`). From a single local UDP socket the proxy sends a STUN Binding Request to two different public STUN servers (Google + Cloudflare) and compares the reflexive external port: same → **endpoint-independent (cone)** NAT (the fixed-port WebRTC mapping from 2.9.18 is sufficient, no port prediction needed); different → **symmetric** NAT (the mapped port varies per viewer, so WebRTC will need port prediction — a later roadmap step). The class is logged at startup. Best-effort: STUN probes are time-bounded and never block startup; an inconclusive probe is logged and ignored. Uses the modern dual-server, single-socket test (no RFC 3489 CHANGE-REQUEST, which public STUN servers like Google's do not support). Evaluated `@xmcl/stun-client`/`stun` (both MIT) but their public APIs create a fresh socket per query and/or rely on CHANGE-REQUEST, which is wrong for this test — hence the minimal in-house client.

package/bin/cli.js

@@ -126,6 +126,12 @@ let portMapper = null;
 /** @type {ReturnType<typeof createPortMapper> | null} UDP mapping for the WebRTC port. */
 let udpPortMapper = null;
 
+/** @type {ReturnType<typeof createWebRtcManager> | null} */
+let webRtcManager = null;
+
+/** @type {import("../services/nat-classifier.js").NatClassification | null} Latest NAT classification (for WebRTC port prediction). */
+let natInfo = null;
+
 
 /**
  * Register this proxy with the registry server.
@@ -204,6 +210,11 @@ async function shutdown(signal) {
       await udpPortMapper.stop();
       udpPortMapper = null;
     }
+    // Close WebRTC sessions and release the shared UDP mux listener socket.
+    if (webRtcManager) {
+      try { webRtcManager.dispose(); } catch { /* ignore */ }
+      webRtcManager = null;
+    }
     if (app) {
       await app.close();
     }
@@ -236,6 +247,11 @@ try {
     logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
   }
 
+  // All WebRTC sessions are multiplexed onto this single UDP port (same number
+  // as the HTTP port, different protocol) via a persistent ICE UDP mux listener
+  // in the WebRTC manager. One port → one UPnP mapping → one reachable endpoint.
+  const webrtcUdpPort = actualPort;
+
   // Try to open the local port on the home router (UPnP/NAT-PMP) so the proxy
   // is reachable from the internet without manual port forwarding. Best-effort
   // and fire-and-forget: failure is normal (router without UPnP) and must not
@@ -257,13 +273,11 @@ try {
         logger.warn(`Port mapping failed to start: ${message}`);
       });
 
-    // Also map the WebRTC UDP port (same number, different protocol). All
-    // WebRTC sessions are multiplexed onto this single UDP port (ICE UDP mux),
-    // so a static mapping makes the proxy's WebRTC path reachable even behind
-    // symmetric NAT. This endpoint is NOT reported to the server: the browser
-    // discovers it via ICE (srflx) candidates, not the TCP dial-back probe.
+    // Also map the single WebRTC UDP port. Not reported to the server: the
+    // browser discovers the endpoint via ICE (srflx) candidates, not the TCP
+    // dial-back probe.
     udpPortMapper = createPortMapper({
-      port: actualPort,
+      port: webrtcUdpPort,
       protocol: "UDP",
       description: "torrent-tv proxy (WebRTC)"
     });
@@ -280,13 +294,15 @@ try {
   // never block startup.
   void classifyNat()
     .then((nat) => {
+      // Stored for WebRTC port prediction (webRtcManager reads it per session).
+      natInfo = nat;
       if (nat.klass === "endpoint-independent") {
         logger.info(
           `nat: endpoint-independent (cone) — external UDP port stable across STUN servers (${nat.externalIp}); fixed-port WebRTC mapping is sufficient, no port prediction needed`
         );
       } else if (nat.klass === "symmetric") {
         logger.warn(
-          `nat: SYMMETRIC — external UDP port varies per destination (delta ${nat.portDelta}); WebRTC will need port prediction to reach remote viewers`
+          `nat: SYMMETRIC — external UDP port varies per destination (delta ${nat.portDelta}); WebRTC offers predicted ports (base+delta*k) — covers sequential/predictable symmetric NAT, not fully random`
         );
       } else {
         logger.info("nat: classification inconclusive (STUN probes failed); continuing");
@@ -302,10 +318,9 @@ try {
   // The WebRTC manager handles the actual peer connection and data channel.
   //
   // We use a late-binding ref so both objects can reference each other without
-  // running into the TDZ (tunnelClient is declared above; webRtcManager uses let
-  // so the closure in createTunnelClient can call it after both are initialised).
-  /** @type {ReturnType<typeof createWebRtcManager> | null} */
-  let webRtcManager = null;
+  // running into the TDZ (tunnelClient is declared above; webRtcManager is the
+  // module-scoped `let` above so the closure in createTunnelClient — and the
+  // shutdown handler — can reach it after initialisation).
 
   tunnelClient = createTunnelClient({
     serverUrl,
@@ -342,9 +357,12 @@ try {
   });
 
   webRtcManager = createWebRtcManager({
-    // Pin all WebRTC sessions to this single UDP port (multiplexed via ICE UDP
-    // mux) so the UPnP UDP mapping above makes the WebRTC path reachable.
-    udpPort: actualPort,
+    // Single UDP port (UPnP-mapped above) shared by all sessions via a
+    // persistent ICE UDP mux listener, so the WebRTC path is reachable from the
+    // internet on one fixed port.
+    udpPort: webrtcUdpPort,
+    // Latest NAT classification — enables symmetric-NAT port prediction.
+    getNatInfo: () => natInfo,
     sendSignal(sessionId, signal) {
       tunnelClient?.sendSignal(sessionId, signal);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.19",
+  "version": "2.9.21",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/sources/stats/get.js

@@ -1,3 +1,5 @@
+import { logger } from "../../../../utils/logger.js";
+
 /**
  * Return download statistics for a registered torrent source.
  *
@@ -38,5 +40,20 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
   const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
   const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
 
-  return reply.send(torrentPool.getFileStats(torrent, fileIndex));
+  const stats = torrentPool.getFileStats(torrent, fileIndex);
+
+  // Diagnostic: surface the real swarm state per poll so a cold-start download
+  // stall (0 peers / header not advancing → playback-plan blocks on the codec
+  // probe → browser timeout) is visible in the proxy log.
+  const downKbps = (stats.downloadSpeed / 1024).toFixed(0);
+  const filePct = stats.fileProgress != null ? `${(stats.fileProgress * 100).toFixed(1)}%` : "n/a";
+  const header =
+    stats.headerBytes != null
+      ? `${stats.headerDownloadedBytes}/${stats.headerBytes}B`
+      : "n/a";
+  logger.info(
+    `[stats] ${sourceKey.slice(0, 8)} peers=${stats.numPeers} down=${downKbps}KB/s file=${filePct} header=${header}`
+  );
+
+  return reply.send(stats);
 }

package/services/port-mapper.js

@@ -85,14 +85,24 @@ function withTimeout(promise, ms, label) {
  * @param {"TCP" | "UDP"} [opts.protocol] - Protocol to map. Defaults to "TCP" (the HTTP/stream port).
  * @param {string} [opts.description] - Human-readable label shown in the router's port-mapping table.
  * @param {number} [opts.ttlSeconds] - Lease time in seconds. Defaults to {@link DEFAULT_TTL_SECONDS}.
+ * @param {number} [opts.portRangeEnd] - When set and > `port`, map the whole
+ *   contiguous range `[port..portRangeEnd]` (used for the WebRTC UDP range, so
+ *   whichever port a session binds is reachable). Single port otherwise.
  * @returns {PortMapper}
  */
 export function createPortMapper({
   port,
   protocol = "TCP",
   description = "torrent-tv proxy",
-  ttlSeconds = DEFAULT_TTL_SECONDS
+  ttlSeconds = DEFAULT_TTL_SECONDS,
+  portRangeEnd
 } = {}) {
+  const rangeEnd = Number.isInteger(portRangeEnd) && portRangeEnd > port ? portRangeEnd : null;
+  const portList = rangeEnd
+    ? Array.from({ length: rangeEnd - port + 1 }, (_, i) => port + i)
+    : [port];
+  const label = rangeEnd ? `${protocol} ${port}-${rangeEnd}` : `${protocol} ${port}`;
+
   /** @type {InstanceType<typeof NatAPI> | null} */
   let nat = null;
   /** @type {MappedEndpoint | null} */
@@ -110,11 +120,11 @@ export function createPortMapper({
     try {
       await withTimeout(instance.destroy(), STOP_TIMEOUT_MS, "destroy");
       if (logRemoval) {
-        logger.info(`port-mapper: removed mapping for ${protocol} ${port}`);
+        logger.info(`port-mapper: removed mapping for ${label}`);
       }
     } catch (error) {
       // Lease expiry (ttl) is the backstop if we cannot unmap cleanly.
-      logger.warn(`port-mapper: failed to remove ${protocol} ${port} mapping cleanly: ${describeError(error)}`);
+      logger.warn(`port-mapper: failed to remove ${label} mapping cleanly: ${describeError(error)}`);
     }
   }
 
@@ -133,16 +143,25 @@ export function createPortMapper({
     }
 
     let instance;
+    let mappedCount = 0;
     try {
       instance = new NatAPI({ ttl: ttlSeconds, autoUpdate: true, description });
-      await withTimeout(
-        instance.map({ publicPort: port, privatePort: port, protocol, description, ttl: ttlSeconds }),
-        START_TIMEOUT_MS,
-        "map"
-      );
+      // Map every port in the range, best-effort per port (one port failing
+      // must not abort the rest). All share the one NatAPI instance, so its
+      // auto-renew covers them and a single destroy() unmaps all.
+      for (const p of portList) {
+        try {
+          await withTimeout(
+            instance.map({ publicPort: p, privatePort: p, protocol, description, ttl: ttlSeconds }),
+            START_TIMEOUT_MS,
+            `map ${p}`
+          );
+          mappedCount++;
+        } catch (error) {
+          logger.warn(`port-mapper: failed to map ${protocol} ${p}: ${describeError(error)}`);
+        }
+      }
     } catch (error) {
-      // No UPnP/NAT-PMP on this router, or it declined. Normal, non-fatal: the
-      // proxy still works on LAN and wherever hole punching succeeds.
       mappedEndpoint = null;
       logger.warn(`port-mapper: no port mapping available (${describeError(error)}); continuing without it`);
       if (instance) {
@@ -151,8 +170,17 @@ export function createPortMapper({
       return;
     }
 
+    if (mappedCount === 0) {
+      // No UPnP/NAT-PMP on this router, or it declined. Normal, non-fatal: the
+      // proxy still works on LAN and wherever hole punching succeeds.
+      mappedEndpoint = null;
+      logger.warn(`port-mapper: no ports mapped for ${label}; continuing without it`);
+      await safeDestroy(instance);
+      return;
+    }
+
     // Mapping succeeded — keep the instance so its auto-renew timers stay alive
-    // and stop() can remove the mapping later.
+    // and stop() can remove the mappings later.
     nat = instance;
 
     // Discover the external IP (best-effort; the mapping is valid without it).
@@ -160,17 +188,18 @@ export function createPortMapper({
     try {
       externalIp = await withTimeout(instance.externalIp(), START_TIMEOUT_MS, "externalIp");
     } catch (error) {
-      logger.warn(`port-mapper: mapped ${protocol} ${port} but could not read external IP: ${describeError(error)}`);
+      logger.warn(`port-mapper: mapped ${label} but could not read external IP: ${describeError(error)}`);
     }
 
     mappedEndpoint = { externalIp: externalIp || null, externalPort: port, protocol };
+    const counts = portList.length > 1 ? ` (${mappedCount}/${portList.length} ports)` : "";
     if (externalIp) {
       logger.success(
-        `port-mapper: mapped ${externalIp}:${port} → ${protocol} ${port} (ttl ${ttlSeconds}s, auto-renew)`
+        `port-mapper: mapped ${externalIp} → ${label}${counts} (ttl ${ttlSeconds}s, auto-renew)`
       );
     } else {
       logger.info(
-        `port-mapper: mapped ${protocol} ${port} (external IP unknown; ttl ${ttlSeconds}s, auto-renew)`
+        `port-mapper: mapped ${label}${counts} (external IP unknown; ttl ${ttlSeconds}s, auto-renew)`
       );
     }
   }

package/services/webrtc-manager.js

@@ -15,6 +15,72 @@ import nodeDataChannel from "node-datachannel";
 
 const ICE_SERVERS = ["stun:stun.l.google.com:19302"];
 
+// Symmetric-NAT port prediction window. For each real srflx candidate we offer
+// this many extra candidates at ports base + delta*k (k = 1..N), because the
+// number of NAT mappings the router allocates between STUN gathering and the
+// browser connectivity check is unknown — a small window covers the likely
+// values without bloating the SDP.
+const PORT_PREDICTION_WINDOW = 16;
+
+/**
+ * Build predicted srflx ICE candidates for a symmetric NAT.
+ *
+ * A symmetric NAT assigns a different external port per destination, so the
+ * STUN-learned srflx port is not the port the NAT will use toward the browser.
+ * Given the per-destination port `delta` measured at startup, we offer ports
+ * `base + delta*k` (k = 1..window) so the browser also probes them; if one
+ * matches the mapping the NAT creates for the proxy→browser path, ICE connects.
+ * This is the practical, signalling-only form of the birthday-paradox trick —
+ * it works for sequential/predictable symmetric NATs, not fully random ones.
+ *
+ * Each predicted candidate gets a unique foundation so ICE treats it as a
+ * distinct candidate. Returns [] for non-srflx, IPv6, missing/zero delta, or a
+ * candidate string we cannot parse.
+ *
+ * @param {string} candidate - Raw candidate string (with or without `a=`).
+ * @param {number} delta - Per-destination external-port delta (from NAT classification).
+ * @param {number} [windowSize]
+ * @returns {Array<{ candidate: string, port: number }>}
+ */
+function buildPredictedSrflxCandidates(candidate, delta, windowSize = PORT_PREDICTION_WINDOW) {
+  if (!Number.isInteger(delta) || delta === 0) {
+    return [];
+  }
+  const raw = candidate.replace(/^a=/, "");
+  if (!/ typ srflx /.test(raw)) {
+    return [];
+  }
+  // candidate:<foundation> <component> <proto> <priority> <ip> <port> typ srflx ...
+  const parts = raw.split(" ");
+  if (parts.length < 8 || !parts[0].startsWith("candidate:")) {
+    return [];
+  }
+  const ip = parts[4];
+  if (typeof ip !== "string" || ip.includes(":")) {
+    // IPv6 has no NAT — port prediction is meaningless.
+    return [];
+  }
+  const basePort = Number(parts[5]);
+  if (!Number.isInteger(basePort)) {
+    return [];
+  }
+
+  const out = [];
+  const seen = new Set([basePort]);
+  for (let k = 1; k <= windowSize; k++) {
+    const port = basePort + delta * k;
+    if (port < 1 || port > 65535 || seen.has(port)) {
+      continue;
+    }
+    seen.add(port);
+    const p = parts.slice();
+    p[0] = `candidate:pp${k}`;
+    p[5] = String(port);
+    out.push({ candidate: p.join(" "), port });
+  }
+  return out;
+}
+
 /**
  * Return true when the ICE candidate string describes a `typ host` candidate
  * with a private (RFC 1918 / ULA / loopback) IP address.
@@ -70,11 +136,24 @@ function isPrivateHostCandidate(candidate) {
  *   `node-datachannel` `DataChannel` object; hand it to `createDataChannelHandler`.
  * @property {(message: string) => void} [onLog]
  *   Optional log sink.
+ * @property {() => ({ klass: string, portDelta: number|null } | null)} [getNatInfo]
+ *   Returns the latest NAT classification (or null if not yet known). When it
+ *   reports a symmetric NAT with a known port delta, each srflx candidate is
+ *   accompanied by predicted-port candidates (see {@link buildPredictedSrflxCandidates}).
  * @property {number} [udpPort]
- *   When set, every PeerConnection is pinned to this single UDP port and ICE
- *   UDP multiplexing is enabled, so all sessions share one port that can be
- *   statically UPnP-mapped (makes the WebRTC path reachable behind NAT). When
- *   omitted, node-datachannel uses an ephemeral UDP port (previous behaviour).
+ *   When set, all WebRTC sessions are multiplexed onto this single UDP port so
+ *   it can be statically UPnP-mapped (one mapping, one reachable port). A
+ *   persistent {@link import("node-datachannel").IceUdpMuxListener} is created
+ *   once at startup and owns the shared socket; every PeerConnection enables
+ *   `enableIceUdpMux` on the same port and demuxes over it by ICE ufrag.
+ *
+ *   The persistent listener is the crucial part: per-PeerConnection
+ *   `enableIceUdpMux` WITHOUT it ties the shared socket to a connection's
+ *   lifetime, so a freshly-opened session fails to bind the port while a
+ *   just-closed one still holds it → "Failed to gather local ICE candidates"
+ *   (which crashed the proxy). The listener keeps the socket alive across
+ *   sessions; verified with sequential + concurrent connections on one port.
+ *   When omitted, node-datachannel uses an ephemeral UDP port.
  */
 
 /**
@@ -86,6 +165,9 @@ function isPrivateHostCandidate(candidate) {
  *   the matching peer connection, creating it if necessary.
  * @property {(sessionId: string) => void} closeSession
  *   Tear down and remove a peer connection by session ID.
+ * @property {() => void} dispose
+ *   Close all peer connections and stop the shared UDP mux listener. Call on
+ *   proxy shutdown so the listener's socket is released.
  */
 
 /**
@@ -94,20 +176,10 @@ function isPrivateHostCandidate(candidate) {
  * @param {WebRtcManagerOptions} options
  * @returns {WebRtcManager}
  */
-export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort }) {
+export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort, getNatInfo }) {
   /** @type {Map<string, import("node-datachannel").PeerConnection>} */
   const peers = new Map();
 
-  // Base PeerConnection config shared by every session. When a UDP port is
-  // configured, pin all sessions to it and enable ICE UDP mux so they share the
-  // single (UPnP-mapped) port; otherwise fall back to an ephemeral UDP port.
-  const pcConfig = { iceServers: ICE_SERVERS };
-  if (Number.isInteger(udpPort) && udpPort > 0 && udpPort <= 65535) {
-    pcConfig.enableIceUdpMux = true;
-    pcConfig.portRangeBegin = udpPort;
-    pcConfig.portRangeEnd = udpPort;
-  }
-
   /**
    * @param {string} message
    * @returns {void}
@@ -118,6 +190,36 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
     }
   }
 
+  // Base PeerConnection config shared by every session.
+  const pcConfig = { iceServers: ICE_SERVERS };
+
+  // Single-port UDP mux: create ONE persistent listener that owns the shared
+  // UDP socket for the proxy's whole lifetime, then have every PeerConnection
+  // mux over it (enableIceUdpMux + the same fixed port). The listener must
+  // outlive individual sessions — without it the socket is bound/freed per
+  // connection and a repeat session fails to gather ICE candidates.
+  /** @type {import("node-datachannel").IceUdpMuxListener | null} */
+  let udpMuxListener = null;
+  if (Number.isInteger(udpPort) && udpPort > 0 && udpPort <= 65535) {
+    try {
+      udpMuxListener = new nodeDataChannel.IceUdpMuxListener(udpPort);
+      // STUN that doesn't match an existing session (our PeerConnections are
+      // created from the SDP offer before the browser's STUN arrives, so normal
+      // traffic is "handled"). Stray/unhandled requests are simply dropped.
+      udpMuxListener.onUnhandledStunRequest(() => {});
+      pcConfig.enableIceUdpMux = true;
+      pcConfig.portRangeBegin = udpPort;
+      pcConfig.portRangeEnd = udpPort;
+      log(`[webrtc] UDP mux listener bound on port ${udpPort}; all sessions share it`);
+    } catch (error) {
+      // Could not bind the mux port — fall back to ephemeral UDP ports (no
+      // single-port reachability, but the proxy still works on LAN / via STUN).
+      const message = error instanceof Error ? error.message : String(error);
+      log(`[webrtc] UDP mux listener failed on port ${udpPort} (${message}); using ephemeral ports`);
+      udpMuxListener = null;
+    }
+  }
+
   /**
    * Retrieve an existing peer connection or create a new one for the session.
    *
@@ -150,6 +252,28 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
         `[webrtc] Session ${sessionId.slice(0, 8)}: sending ${isPrivate ? "private" : "public"} candidate: ${candidate.replace(/^a=/, "")}`
       );
       sendSignal(sessionId, { type: "candidate", candidate, mid });
+
+      // Symmetric-NAT port prediction: offer extra srflx candidates at the
+      // predicted external ports so the browser probes them too. No-op unless
+      // the NAT is symmetric with a known delta and this is an IPv4 srflx
+      // candidate. Best-effort — never let it break candidate forwarding.
+      try {
+        const nat = typeof getNatInfo === "function" ? getNatInfo() : null;
+        if (nat && nat.klass === "symmetric") {
+          const predicted = buildPredictedSrflxCandidates(candidate, nat.portDelta);
+          if (predicted.length > 0) {
+            log(
+              `[webrtc] Session ${sessionId.slice(0, 8)}: symmetric NAT (delta=${nat.portDelta}) — injecting ${predicted.length} predicted srflx candidates: ${predicted.map((p) => p.port).join(",")}`
+            );
+            for (const p of predicted) {
+              sendSignal(sessionId, { type: "candidate", candidate: p.candidate, mid });
+            }
+          }
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`[webrtc] Session ${sessionId.slice(0, 8)}: port-prediction inject failed: ${message}`);
+      }
     });
 
     pc.onGatheringStateChange((state) => {
@@ -225,9 +349,19 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
         return;
       }
       log(`[webrtc] Session ${sessionId.slice(0, 8)}: received offer`);
-      const pc = getOrCreatePeer(sessionId);
-      pc.setRemoteDescription(signal.sdp, "offer");
-      // `onLocalDescription` fires automatically with the SDP answer.
+      // node-datachannel can throw SYNCHRONOUSLY here (e.g. "Failed to gather
+      // local ICE candidates" when the pinned UDP port cannot be bound). A
+      // single bad session must never crash the whole proxy — that would drop
+      // every other viewer and the tunnel. Contain it: fail this session only.
+      try {
+        const pc = getOrCreatePeer(sessionId);
+        pc.setRemoteDescription(signal.sdp, "offer");
+        // `onLocalDescription` fires automatically with the SDP answer.
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`[webrtc] Session ${sessionId.slice(0, 8)}: failed to handle offer: ${message}`);
+        closeSession(sessionId);
+      }
       return;
     }
 
@@ -237,7 +371,12 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
         return;
       }
       if (typeof signal.candidate === "string" && typeof signal.mid === "string") {
-        pc.addRemoteCandidate(signal.candidate, signal.mid);
+        try {
+          pc.addRemoteCandidate(signal.candidate, signal.mid);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          log(`[webrtc] Session ${sessionId.slice(0, 8)}: failed to add candidate: ${message}`);
+        }
       }
     }
   }
@@ -258,5 +397,20 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
     }
   }
 
-  return { handleSignal, closeSession };
+  /**
+   * Close all peer connections and stop the shared UDP mux listener.
+   *
+   * @returns {void}
+   */
+  function dispose() {
+    for (const sessionId of [...peers.keys()]) {
+      closeSession(sessionId);
+    }
+    if (udpMuxListener) {
+      try { udpMuxListener.stop(); } catch { /* ignore */ }
+      udpMuxListener = null;
+    }
+  }
+
+  return { handleSignal, closeSession, dispose };
 }