@torrent-tv/proxy 2.9.17 → 2.9.19

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 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).
+
 ## 2.9.17
 
 - **New**: The proxy reports its UPnP-mapped external endpoint to the server over the tunnel (new `proxy-endpoint` message: `{ externalIp, externalPort, protocol }` from `port-mapper.getMappedEndpoint()`). Sent when the mapping completes and re-sent on every tunnel (re)connect, so the server can dial back and verify the proxy is reachable from the internet (server 0.8.22). No effect if port mapping is disabled or failed.

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);
@@ -122,6 +123,9 @@ let tunnelClient = null;
 /** @type {ReturnType<typeof createPortMapper> | null} */
 let portMapper = null;
 
+/** @type {ReturnType<typeof createPortMapper> | null} UDP mapping for the WebRTC port. */
+let udpPortMapper = null;
+
 
 /**
  * Register this proxy with the registry server.
@@ -190,12 +194,16 @@ async function shutdown(signal) {
   }
   logger.warn(`Received ${signal}, shutting down...`);
   try {
-    // Remove the router port mapping before exiting (lease expiry is the
+    // Remove the router port mappings before exiting (lease expiry is the
     // backstop if this is skipped on a hard kill).
     if (portMapper) {
       await portMapper.stop();
       portMapper = null;
     }
+    if (udpPortMapper) {
+      await udpPortMapper.stop();
+      udpPortMapper = null;
+    }
     if (app) {
       await app.close();
     }
@@ -248,10 +256,47 @@ try {
         const message = error instanceof Error ? error.message : String(error);
         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.
+    udpPortMapper = createPortMapper({
+      port: actualPort,
+      protocol: "UDP",
+      description: "torrent-tv proxy (WebRTC)"
+    });
+    void udpPortMapper.start().catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`UDP port mapping failed to start: ${message}`);
+    });
   } else {
     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.
@@ -297,6 +342,9 @@ 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,
     sendSignal(sessionId, signal) {
       tunnelClient?.sendSignal(sessionId, signal);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.17",
+  "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

@@ -70,6 +70,11 @@ function isPrivateHostCandidate(candidate) {
  *   `node-datachannel` `DataChannel` object; hand it to `createDataChannelHandler`.
  * @property {(message: string) => void} [onLog]
  *   Optional log sink.
+ * @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).
  */
 
 /**
@@ -89,10 +94,20 @@ function isPrivateHostCandidate(candidate) {
  * @param {WebRtcManagerOptions} options
  * @returns {WebRtcManager}
  */
-export function createWebRtcManager({ sendSignal, onDataChannel, onLog }) {
+export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort }) {
   /** @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,9 +133,7 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog }) {
       return existing;
     }
 
-    const pc = new nodeDataChannel.PeerConnection(`proxy-${sessionId.slice(0, 8)}`, {
-      iceServers: ICE_SERVERS
-    });
+    const pc = new nodeDataChannel.PeerConnection(`proxy-${sessionId.slice(0, 8)}`, pcConfig);
 
     // Forward all ICE candidates to the browser through the tunnel.
     //
@@ -131,7 +144,11 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog }) {
     // 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 });
     });
 
@@ -147,6 +164,22 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog }) {
 
     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") {
@@ -154,6 +187,12 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog }) {
       }
     });
 
+    // 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`);