@torrent-tv/proxy 2.9.16 → 2.9.18

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
+
 ## 2.9.16
 
 - **New**: Automatic port mapping (`services/port-mapper.js`). At startup the proxy asks the home router to open its local port (default TCP 9090) via UPnP IGD / NAT-PMP using `@silentbot1/nat-api` (the same library WebTorrent already uses for the torrent port — no new host dependency). The mapping uses a 2 h lease auto-renewed while running and is removed on graceful shutdown (wired into the `cli.js` shutdown path; lease expiry is the backstop on a hard kill). Strictly best-effort: a router without UPnP/NAT-PMP is a normal case — it is logged and the proxy continues. Bounded by start/stop timeouts so a non-responding gateway never delays startup or hangs shutdown. Disable with `--no-port-mapping`. The discovered external endpoint is exposed via `getMappedEndpoint()` for the upcoming server-side reachability probe (not yet reported). `@silentbot1/nat-api` is now a direct dependency (was transitive via WebTorrent).

package/CLAUDE.md

@@ -56,24 +56,29 @@ Decided direction — full plan in the parent `../CLAUDE.md`. Proxy-side pieces:
   same lib WebTorrent uses for the torrent port). Maps TCP 9090 with a 2 h
   auto-renewed lease, removed on shutdown (lease expiry covers hard kills).
   Best-effort + start/stop timeouts; `--no-port-mapping` opts out;
-  `getMappedEndpoint()` exposes the external endpoint for the reachability
-  probe. NOT yet done: mapping the **UDP** port WebRTC actually uses (it binds
-  ephemeral UDP ports, so this TCP mapping does not yet help WebRTC — see the
-  NAT-traversal toolbox in the parent CLAUDE.md), and reporting the endpoint
-  to the server.
-- Report the mapped external endpoint (and local addresses) to the server over
-  the tunnel; the server dial-back-verifies reachability before use.
+  `getMappedEndpoint()` exposes the external endpoint. NOT yet done: mapping the
+  **UDP** port WebRTC actually uses (it binds ephemeral UDP ports, so this TCP
+  mapping does not yet help WebRTC — roadmap step 3 in the parent CLAUDE.md).
+  Also pending (next iteration): a success log line in `port-mapper.js` `stop()`
+  (`removed mapping for TCP <port>`) — today stop() only logs on failure, so a
+  clean unmap on shutdown is silent.
+- **Report endpoint to server** — ✅ DONE (proxy 2.9.17). The mapped endpoint
+  is sent over the tunnel (`tunnel-client.sendEndpoint` → `proxy-endpoint`) on
+  mapping success and on every tunnel (re)connect; the server dial-back-verifies
+  reachability (server 0.8.22, roadmap step 2).
 - **HTTPS listener**: serve the existing routes over TLS with a per-proxy
   certificate delivered by the server through the tunnel (persist cert+key
   locally; ~90-day renewals are pushed the same way). Add CORS headers for the
   web-app origin so hls.js / `<video>` can fetch cross-origin.
 - Plain HTTPS becomes the preferred video transport; WebRTC data channel stays
   as fallback for hosts where no port could be opened.
-- **NAT-traversal toolbox** (staged, see parent `../CLAUDE.md`): birthday-
-  paradox port prediction (open ~256 UDP sockets, inject predicted-port ICE
-  candidates) for symmetric NAT; IPv6-first (audit the candidate filter — do
-  not drop *global* v6); STUN-based NAT pre-classification at startup reported
-  to the registry; relay-then-upgrade later.
+- **Later roadmap steps** (single staged roadmap in parent `../CLAUDE.md`,
+  WebRTC-first ordering): step 3 map the WebRTC UDP port (fixed
+  `portRangeBegin`/`End` + UPnP-map UDP); step 4 birthday-paradox port
+  prediction (open ~256 UDP sockets, inject predicted-port ICE candidates) for
+  symmetric NAT; step 5 IPv6-first (audit the candidate filter — do not drop
+  *global* v6) + STUN NAT pre-classification reported to the registry; then
+  the DNS+TLS path (steps 6–7); step 8 relay-then-upgrade (deferred).
 - Future: ed25519 proxy identity (sign announcements), BEP 44 endpoint
   announcements via the `bittorrent-dht` already bundled with WebTorrent.
 
@@ -82,17 +87,16 @@ All of this must stay deployment-agnostic (HA addon, bare npm, Docker).
 ## Disk hygiene (open item — torrent data is NOT cleaned up today)
 
 HLS segments are handled (`hls-session-manager.js`: idle TTL, `disposeSession`,
-`disposeAll`). Torrent data is NOT: `new WebTorrent()` in `torrent-pool.js` uses
-the default FS store under `os.tmpdir()`, there is no `client.remove()` /
-`torrent.destroy()`, `deselect()` only stops further download, nothing sweeps
-orphans at startup, and `TorrentPool` is not wired into the `onClose` shutdown
-hook (`server.js` only disposes HLS sessions on close — see `cli.js` shutdown →
-`app.close()` → `onClose`).
-
-Level 1 (do first): `client.remove(torrent, { destroyStore: true })` on last-
-file refcount 0 + idle TTL; startup sweep of orphaned store dirs; wire
-`TorrentPool` teardown into the `onClose` hook so closing the proxy cleans up
-(not only startup); global disk cap with LRU eviction of whole torrents.
+`disposeAll`). Torrent data is **partially** handled: shutdown cleanup is done
+(`TorrentPool.destroyAll()` with `destroyStore: true`, wired into the `onClose`
+hook — proxy 2.9.15), but `deselect()` only stops further download and nothing
+removes a torrent's data **while the proxy keeps running**, nor sweeps orphans
+left by a previous hard kill at startup.
+
+Level 1 — remaining: `client.remove(torrent, { destroyStore: true })` on last-
+file refcount 0 + idle TTL (mirror the HLS session model); startup sweep of
+orphaned store dirs under `os.tmpdir()`; global disk cap with LRU eviction of
+whole torrents. (Shutdown teardown ✅ done.)
 Level 2 (research): sliding-window chunk store. Full rationale in the parent
 `../CLAUDE.md` "Disk hygiene" section.
 

package/bin/cli.js

@@ -122,6 +122,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 +193,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();
     }
@@ -234,9 +241,34 @@ try {
   // delay tunnel connect / registration, so we do not await it.
   if (portMappingEnabled) {
     portMapper = createPortMapper({ port: actualPort, protocol: "TCP" });
-    void portMapper.start().catch((error) => {
+    void portMapper
+      .start()
+      .then(() => {
+        // Mapping may finish after the tunnel is already connected; report the
+        // endpoint now. If the tunnel is not open yet, onConnect re-sends it.
+        const endpoint = portMapper?.getMappedEndpoint();
+        if (endpoint) {
+          tunnelClient?.sendEndpoint(endpoint);
+        }
+      })
+      .catch((error) => {
+        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(`Port mapping failed to start: ${message}`);
+      logger.warn(`UDP port mapping failed to start: ${message}`);
     });
   } else {
     logger.info("Automatic port mapping is disabled (--no-port-mapping).");
@@ -270,6 +302,13 @@ try {
         const message = error instanceof Error ? error.message : String(error);
         logger.error(`Re-registration after tunnel connect failed: ${message}`);
       });
+      // Re-report the mapped endpoint on every (re)connect — the server's
+      // in-memory reachability state resets on restart, and the mapping may
+      // have completed before this connection existed.
+      const endpoint = portMapper?.getMappedEndpoint();
+      if (endpoint) {
+        tunnelClient?.sendEndpoint(endpoint);
+      }
     },
     onLog: (message) => logger.info(message)
   });
@@ -280,6 +319,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.16",
+  "version": "2.9.18",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/tunnel-client.js

@@ -72,6 +72,9 @@ import { WebSocket } from "ws";
  * @property {() => void}   disconnect   - Close the tunnel; suppresses reconnects.
  * @property {(sessionId: string, signal: WebRtcSignal) => void} sendSignal
  *   Send a WebRTC signal (answer / candidate) back to the browser.
+ * @property {(endpoint: { externalIp: string | null, externalPort: number, protocol: string }) => void} sendEndpoint
+ *   Report this proxy's UPnP-mapped external endpoint to the server so it can
+ *   dial back and verify reachability.
  */
 
 const RECONNECT_DELAY_MS = 5_000;
@@ -312,6 +315,18 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onSig
      */
     sendSignal(sessionId, signal) {
       send({ type: "signal", sessionId, signal });
+    },
+
+    /**
+     * Report this proxy's UPnP-mapped external endpoint to the server.
+     * No-op if the tunnel is not currently open (the caller re-sends on
+     * connect / reconnect).
+     *
+     * @param {{ externalIp: string | null, externalPort: number, protocol: string }} endpoint
+     * @returns {void}
+     */
+    sendEndpoint(endpoint) {
+      send({ type: "proxy-endpoint", endpoint });
     }
   };
 }

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.
     //