@torrent-tv/proxy 2.9.18 → 2.9.19

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
+
+## 2.9.19
+
+- **Chore**: Diagnostics for verifying remote WebRTC reachability and root-causing failures. `port-mapper.js` now logs a `removed mapping for <proto> <port>` line on clean shutdown unmap (previously silent on success). `webrtc-manager.js` now logs the **full** local ICE candidate (`addr:port typ …`, so the pinned UDP port is visible), every **ICE-state** transition (`checking → connected/failed`), and — on connect — the **selected candidate pair** (`local=[…] remote=[…]` with type/address/port), the single most useful line for "did the WebRTC path connect, and over which route (LAN / public srflx v4 / v6)".
+
 ## 2.9.18
 
 - **New**: WebRTC is now reachable behind NAT via a static UDP port mapping. All sessions are pinned to a single UDP port (same number as the HTTP port, default 9090) and multiplexed over it (`enableIceUdpMux` + `portRangeBegin`/`portRangeEnd` in `webrtc-manager.js`), and that UDP port is UPnP/NAT-PMP-mapped at startup (a second `port-mapper.js` instance, protocol UDP, removed on shutdown). Because the socket is bound to a fixed, statically-mapped port, the proxy's `srflx` ICE candidate now carries `publicIP:9090` — reachable from the browser even behind symmetric NAT for that port (previously WebRTC used an ephemeral UDP port that UPnP could not map). Verified: two PeerConnections share the one UDP port with no bind conflict; host + srflx (v4 and global v6) candidates all carry the fixed port. The UDP endpoint is not reported to the server (the browser learns it via ICE, not the TCP dial-back probe).

package/bin/cli.js

@@ -20,6 +20,7 @@ import { createWebRtcManager } from "../services/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/data-channel-handler.js";
 import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
+import { classifyNat } from "../services/nat-classifier.js";
 import { logger } from "../utils/logger.js";
 
 const require = createRequire(import.meta.url);
@@ -274,6 +275,28 @@ try {
     logger.info("Automatic port mapping is disabled (--no-port-mapping).");
   }
 
+  // Classify the home NAT (diagnostic + decides whether WebRTC will need port
+  // prediction for remote viewers). Best-effort, fire-and-forget — STUN probes
+  // never block startup.
+  void classifyNat()
+    .then((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`
+        );
+      } else {
+        logger.info("nat: classification inconclusive (STUN probes failed); continuing");
+      }
+    })
+    .catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`nat classification failed: ${message}`);
+    });
+
   // Create tunnel + WebRTC manager.
   // The tunnel forwards WebRTC signals between browser (via server) and this proxy.
   // The WebRTC manager handles the actual peer connection and data channel.

package/package.json

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

package/services/nat-classifier.js

@@ -0,0 +1,231 @@
+/**
+ * @file NAT classification via STUN (minimal, dependency-free client).
+ *
+ * Determines whether the proxy's home NAT preserves its external UDP port
+ * across destinations (endpoint-independent / "cone") or assigns a new port
+ * per destination ("symmetric"). This decides whether the fixed-UDP-port +
+ * UPnP mapping (the WebRTC reachability of proxy 2.9.18) is sufficient:
+ *
+ *   - endpoint-independent → a static mapping works; no port prediction needed.
+ *   - symmetric            → the mapped port differs per viewer; WebRTC needs
+ *                            port prediction (a later roadmap step).
+ *
+ * Method: from ONE local UDP socket, send a STUN Binding Request to TWO
+ * different public STUN servers (different destinations) and compare the
+ * reported external port. Same port → endpoint-independent; different →
+ * symmetric. This is the modern, reliable test — unlike RFC 3489's CHANGE-
+ * REQUEST classification, it needs no special STUN-server support (works with
+ * Google/Cloudflare STUN). The two queries MUST share one socket: a fresh
+ * socket would get its own NAT mapping and make even a cone NAT look symmetric.
+ *
+ * Strictly best-effort: never throws; returns `klass: "unknown"` if the probes
+ * fail (STUN blocked, offline). Used for diagnostics/telemetry and to gate the
+ * future WebRTC port-prediction work.
+ */
+
+import dgram from "node:dgram";
+import crypto from "node:crypto";
+
+const STUN_MAGIC_COOKIE = 0x2112a442;
+const STUN_BINDING_REQUEST = 0x0001;
+const ATTR_XOR_MAPPED_ADDRESS = 0x0020;
+const ATTR_MAPPED_ADDRESS = 0x0001;
+
+// Public STUN servers from DIFFERENT operators, so the destination genuinely
+// differs between the two queries (required for the symmetric test).
+const DEFAULT_STUN_SERVERS = [
+  { host: "stun.l.google.com", port: 19302 },
+  { host: "stun.cloudflare.com", port: 3478 },
+  { host: "stun1.l.google.com", port: 19302 }
+];
+
+const QUERY_TIMEOUT_MS = 4000;
+
+/**
+ * @typedef {object} NatObservation
+ * @property {string} server   - "host:port" that was queried.
+ * @property {string} ip       - Reflexive external IP reported.
+ * @property {number} port     - Reflexive external port reported.
+ */
+
+/**
+ * @typedef {object} NatClassification
+ * @property {"endpoint-independent" | "symmetric" | "unknown"} klass
+ * @property {string | null} externalIp - External IP (from the first success).
+ * @property {NatObservation[]} observations
+ * @property {number | null} portDelta   - port(2nd) - port(1st) when symmetric, else null.
+ */
+
+/**
+ * Build a 20-byte STUN Binding Request with a random 96-bit transaction id.
+ *
+ * @returns {Buffer}
+ */
+function buildBindingRequest() {
+  const msg = Buffer.alloc(20);
+  msg.writeUInt16BE(STUN_BINDING_REQUEST, 0);
+  msg.writeUInt16BE(0, 2); // message length (no attributes)
+  msg.writeUInt32BE(STUN_MAGIC_COOKIE, 4);
+  crypto.randomFillSync(msg, 8, 12); // transaction id
+  return msg;
+}
+
+/**
+ * Parse the reflexive address from a STUN response, preferring
+ * XOR-MAPPED-ADDRESS and falling back to MAPPED-ADDRESS. IPv4 only.
+ *
+ * @param {Buffer} msg
+ * @returns {{ ip: string, port: number } | null}
+ */
+function parseMappedAddress(msg) {
+  if (msg.length < 20) {
+    return null;
+  }
+  let offset = 20;
+  while (offset + 4 <= msg.length) {
+    const type = msg.readUInt16BE(offset);
+    const length = msg.readUInt16BE(offset + 2);
+    const valueStart = offset + 4;
+    if (valueStart + length > msg.length) {
+      break;
+    }
+
+    if (type === ATTR_XOR_MAPPED_ADDRESS || type === ATTR_MAPPED_ADDRESS) {
+      const family = msg.readUInt8(valueStart + 1);
+      if (family === 0x01) {
+        // IPv4
+        const xored = type === ATTR_XOR_MAPPED_ADDRESS;
+        const rawPort = msg.readUInt16BE(valueStart + 2);
+        const port = xored ? rawPort ^ (STUN_MAGIC_COOKIE >>> 16) : rawPort;
+        const addrBytes = [
+          msg.readUInt8(valueStart + 4),
+          msg.readUInt8(valueStart + 5),
+          msg.readUInt8(valueStart + 6),
+          msg.readUInt8(valueStart + 7)
+        ];
+        const cookieBytes = [
+          (STUN_MAGIC_COOKIE >>> 24) & 0xff,
+          (STUN_MAGIC_COOKIE >>> 16) & 0xff,
+          (STUN_MAGIC_COOKIE >>> 8) & 0xff,
+          STUN_MAGIC_COOKIE & 0xff
+        ];
+        const ipParts = addrBytes.map((b, i) => (xored ? b ^ cookieBytes[i] : b));
+        return { ip: ipParts.join("."), port };
+      }
+    }
+
+    // Attributes are padded to 4-byte boundaries.
+    offset = valueStart + length + ((4 - (length % 4)) % 4);
+  }
+  return null;
+}
+
+/**
+ * Send one Binding Request to `host:port` over the given socket and resolve
+ * with the reflexive address, or null on timeout / parse failure.
+ *
+ * @param {import("node:dgram").Socket} socket
+ * @param {string} host
+ * @param {number} port
+ * @returns {Promise<{ ip: string, port: number } | null>}
+ */
+function queryStun(socket, host, port) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const onMessage = (msg) => {
+      if (settled) {
+        return;
+      }
+      const parsed = parseMappedAddress(msg);
+      if (!parsed) {
+        return; // ignore unrelated datagrams; let the timeout fire if needed
+      }
+      settled = true;
+      socket.off("message", onMessage);
+      resolve(parsed);
+    };
+    socket.on("message", onMessage);
+    socket.send(buildBindingRequest(), port, host, (err) => {
+      if (err && !settled) {
+        settled = true;
+        socket.off("message", onMessage);
+        resolve(null);
+      }
+    });
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        socket.off("message", onMessage);
+        resolve(null);
+      }
+    }, QUERY_TIMEOUT_MS);
+    timer.unref?.();
+  });
+}
+
+/**
+ * Classify the host's NAT by comparing the external port seen by two different
+ * STUN servers over a single local socket.
+ *
+ * @param {{ servers?: Array<{ host: string, port: number }> }} [options]
+ * @returns {Promise<NatClassification>}
+ */
+export async function classifyNat({ servers = DEFAULT_STUN_SERVERS } = {}) {
+  /** @type {NatClassification} */
+  const unknown = { klass: "unknown", externalIp: null, observations: [], portDelta: null };
+
+  const socket = dgram.createSocket("udp4");
+  try {
+    await new Promise((resolve, reject) => {
+      socket.once("error", reject);
+      socket.bind(0, () => {
+        socket.off("error", reject);
+        resolve(undefined);
+      });
+    });
+  } catch {
+    try {
+      socket.close();
+    } catch {
+      // ignore
+    }
+    return unknown;
+  }
+
+  /** @type {NatObservation[]} */
+  const observations = [];
+  try {
+    for (const server of servers) {
+      const result = await queryStun(socket, server.host, server.port);
+      if (result) {
+        observations.push({ server: `${server.host}:${server.port}`, ip: result.ip, port: result.port });
+      }
+      // Stop once we have two observations from two different destinations.
+      if (observations.length >= 2) {
+        break;
+      }
+    }
+  } finally {
+    try {
+      socket.close();
+    } catch {
+      // ignore
+    }
+  }
+
+  if (observations.length < 2) {
+    return { ...unknown, observations };
+  }
+
+  const [first, second] = observations;
+  const externalIp = first.ip;
+  if (first.port === second.port) {
+    return { klass: "endpoint-independent", externalIp, observations, portDelta: null };
+  }
+  return {
+    klass: "symmetric",
+    externalIp,
+    observations,
+    portDelta: second.port - first.port
+  };
+}

package/services/port-mapper.js

@@ -106,12 +106,15 @@ export function createPortMapper({
    * @param {InstanceType<typeof NatAPI>} instance
    * @returns {Promise<void>}
    */
-  async function safeDestroy(instance) {
+  async function safeDestroy(instance, { logRemoval = false } = {}) {
     try {
       await withTimeout(instance.destroy(), STOP_TIMEOUT_MS, "destroy");
+      if (logRemoval) {
+        logger.info(`port-mapper: removed mapping for ${protocol} ${port}`);
+      }
     } catch (error) {
       // Lease expiry (ttl) is the backstop if we cannot unmap cleanly.
-      logger.warn(`port-mapper: failed to remove port mapping cleanly: ${describeError(error)}`);
+      logger.warn(`port-mapper: failed to remove ${protocol} ${port} mapping cleanly: ${describeError(error)}`);
     }
   }
 
@@ -182,7 +185,7 @@ export function createPortMapper({
     const instance = nat;
     nat = null;
     mappedEndpoint = null;
-    await safeDestroy(instance);
+    await safeDestroy(instance, { logRemoval: true });
   }
 
   /**

package/services/webrtc-manager.js

@@ -144,7 +144,11 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
     // the connection proceeds via the local LAN path.
     pc.onLocalCandidate((candidate, mid) => {
       const isPrivate = isPrivateHostCandidate(candidate);
-      log(`[webrtc] Session ${sessionId.slice(0, 8)}: sending ${isPrivate ? "private" : "public"} candidate`);
+      // Log the full candidate (addr:port typ …) so we can confirm WebRTC is
+      // pinned to the mapped UDP port and diagnose which paths are offered.
+      log(
+        `[webrtc] Session ${sessionId.slice(0, 8)}: sending ${isPrivate ? "private" : "public"} candidate: ${candidate.replace(/^a=/, "")}`
+      );
       sendSignal(sessionId, { type: "candidate", candidate, mid });
     });
 
@@ -160,6 +164,22 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
 
     pc.onStateChange((state) => {
       log(`[webrtc] Session ${sessionId.slice(0, 8)}: state → ${state}`);
+      // On connect, log which candidate pair actually won — this is the single
+      // most useful line for "did the open-port/WebRTC path work, and over
+      // which route (LAN / public srflx v4 / v6)".
+      if (state === "connected") {
+        try {
+          const pair = pc.getSelectedCandidatePair();
+          if (pair) {
+            const fmt = (c) => `${c.type} ${c.address}:${c.port}/${c.transportType}`;
+            log(
+              `[webrtc] Session ${sessionId.slice(0, 8)}: selected pair local=[${fmt(pair.local)}] remote=[${fmt(pair.remote)}]`
+            );
+          }
+        } catch {
+          // Diagnostics only — never let a logging call affect the connection.
+        }
+      }
       // "disconnected" is a transient state — ICE may recover on its own.
       // Only tear down on terminal states: "failed" and "closed".
       if (state === "failed" || state === "closed") {
@@ -167,6 +187,12 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort
       }
     });
 
+    // Granular ICE-level transitions (checking → connected/failed) — finer than
+    // the peer state above; pinpoints where a failing connection stalls.
+    pc.onIceStateChange((state) => {
+      log(`[webrtc] Session ${sessionId.slice(0, 8)}: ICE → ${state}`);
+    });
+
     // Browser creates the data channel — we receive it here.
     pc.onDataChannel((channel) => {
       log(`[webrtc] Session ${sessionId.slice(0, 8)}: data channel "${channel.getLabel()}" opened`);