@torrent-tv/proxy 2.9.20 → 2.9.21

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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.

package/bin/cli.js

@@ -129,6 +129,9 @@ 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.
@@ -291,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");
@@ -356,6 +361,8 @@ try {
     // 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.20",
+  "version": "2.9.21",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

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,6 +136,10 @@ 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, all WebRTC sessions are multiplexed onto this single UDP port so
  *   it can be statically UPnP-mapped (one mapping, one reachable port). A
@@ -106,7 +176,7 @@ 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();
 
@@ -182,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) => {