@torrent-tv/proxy 2.9.15 → 2.9.17

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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).
+
 ## 2.9.15
 
 - **Fix**: Torrent data is now cleaned up on graceful shutdown. `TorrentPool.destroyAll()` removes every torrent **with its on-disk store** (`torrent.destroy({ destroyStore: true })`) and then tears down the WebTorrent client; it is wired into the Fastify `onClose` hook (after `hlsSessionManager.disposeAll()`, so ffmpeg readers stop before their source files are removed). Previously nothing called `client.remove()`/`torrent.destroy()` anywhere, so downloaded files accumulated under `os.tmpdir()` until the process was killed — and even a clean SIGTERM/SIGINT left them behind. (First step of disk-hygiene Level 1; refcount/TTL removal and the startup orphan sweep are separate, still pending.)

package/CLAUDE.md

@@ -51,24 +51,34 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
 
 Decided direction — full plan in the parent `../CLAUDE.md`. Proxy-side pieces:
 
-- **Auto port mapping** at startup via UPnP IGD / NAT-PMP / PCP (`nat-api` /
-  `@silentbot1/nat-api`; WebTorrent already does this for the torrent port).
-  Always request a lease time and renew it while running; remove the mapping
-  on graceful shutdown — lease expiry cleans up after crashes. Zero user
-  action, nothing left behind on the router.
-- Report the mapped external endpoint (and local addresses) to the server over
-  the tunnel; the server dial-back-verifies reachability before use.
+- **Auto port mapping** — IMPLEMENTED (`services/port-mapper.js`, changelog
+  2.9.16). UPnP IGD / NAT-PMP via `@silentbot1/nat-api` (now a direct dep; the
+  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. 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.
 
@@ -77,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

@@ -19,6 +19,7 @@ import { createTunnelClient } from "../services/tunnel-client.js";
 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 { logger } from "../utils/logger.js";
 
 const require = createRequire(import.meta.url);
@@ -53,6 +54,7 @@ program
   .option("--id <id>", "Stable client id")
   .option("--name <name>", "Display name")
   .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
+  .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
   .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
   .option("--token <token>", "Registration token", "")
   .addHelpText("after", HELP_EXAMPLES);
@@ -75,6 +77,7 @@ const clientId = options.id ? String(options.id) : crypto.randomUUID();
 const clientName = options.name ? String(options.name) : `proxy-${clientId.slice(0, 8)}`;
 const token = String(options.token ?? "");
 const transcodeAudio = options.transcodeAudio !== false;
+const portMappingEnabled = options.portMapping !== false;
 const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
 const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
 
@@ -116,6 +119,9 @@ let shutdownInProgress = false;
 /** @type {ReturnType<typeof createTunnelClient> | null} */
 let tunnelClient = null;
 
+/** @type {ReturnType<typeof createPortMapper> | null} */
+let portMapper = null;
+
 
 /**
  * Register this proxy with the registry server.
@@ -184,6 +190,12 @@ async function shutdown(signal) {
   }
   logger.warn(`Received ${signal}, shutting down...`);
   try {
+    // Remove the router port mapping before exiting (lease expiry is the
+    // backstop if this is skipped on a hard kill).
+    if (portMapper) {
+      await portMapper.stop();
+      portMapper = null;
+    }
     if (app) {
       await app.close();
     }
@@ -216,6 +228,30 @@ try {
     logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
   }
 
+  // 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
+  // delay tunnel connect / registration, so we do not await it.
+  if (portMappingEnabled) {
+    portMapper = createPortMapper({ port: actualPort, protocol: "TCP" });
+    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}`);
+      });
+  } else {
+    logger.info("Automatic port mapping is disabled (--no-port-mapping).");
+  }
+
   // 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.
@@ -244,6 +280,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)
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.15",
+  "version": "2.9.17",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -21,6 +21,7 @@
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/static": "^9.1.3",
+    "@silentbot1/nat-api": "^0.4.9",
     "chalk": "^5.4.1",
     "commander": "^12.1.0",
     "fastify": "^5.8.5",

package/services/port-mapper.js

@@ -0,0 +1,196 @@
+/**
+ * @file Automatic port mapping (UPnP IGD / NAT-PMP / PCP) for the proxy.
+ *
+ * Opens a port on the user's home router so the proxy is reachable from the
+ * internet without any manual port forwarding. Uses `@silentbot1/nat-api`
+ * (the same library WebTorrent already uses for the torrent port, so this adds
+ * no new dependency surface on the host).
+ *
+ * Strictly best-effort: a router without UPnP/NAT-PMP — or one that declines —
+ * is a normal case, not an error. Mapping failure never blocks proxy startup
+ * and never throws to the caller. Reachability of the mapped endpoint is
+ * verified separately (server-side dial-back probe — a later stage).
+ *
+ * The mapping is created with a TTL and auto-renewed while the proxy runs
+ * (`autoUpdate`), and removed on graceful shutdown via {@link stop}. If the
+ * process dies without calling `stop()`, the router drops the mapping when the
+ * lease expires.
+ */
+
+import NatAPI from "@silentbot1/nat-api";
+import { logger } from "../utils/logger.js";
+
+// nat-api clamps ttl to a 1200 s minimum; it auto-renews at (ttl - 600) s.
+const DEFAULT_TTL_SECONDS = 7200;
+// SSDP discovery can hang on networks with no responding gateway — bound it so
+// startup is never delayed waiting for a router that will not answer.
+const START_TIMEOUT_MS = 10_000;
+// A slow/unreachable router must not hang shutdown; lease expiry is the backstop.
+const STOP_TIMEOUT_MS = 5_000;
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Reject after `ms` if `promise` has not settled, so a hung NAT operation
+ * cannot block startup or shutdown.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {string} label
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms} ms`)), ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+/**
+ * @typedef {object} MappedEndpoint
+ * @property {string | null} externalIp - Public IP as seen by NAT-PMP/UPnP, or null if unknown.
+ * @property {number} externalPort
+ * @property {"TCP" | "UDP"} protocol
+ */
+
+/**
+ * @typedef {object} PortMapper
+ * @property {() => Promise<void>} start - Create the mapping (best-effort, never throws).
+ * @property {() => Promise<void>} stop - Remove the mapping and stop auto-renew (idempotent).
+ * @property {() => MappedEndpoint | null} getMappedEndpoint - The active mapping, or null.
+ */
+
+/**
+ * Create a port mapper for a single local port.
+ *
+ * @param {object} opts
+ * @param {number} opts.port - The local port to expose (used as both public and private port).
+ * @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}.
+ * @returns {PortMapper}
+ */
+export function createPortMapper({
+  port,
+  protocol = "TCP",
+  description = "torrent-tv proxy",
+  ttlSeconds = DEFAULT_TTL_SECONDS
+} = {}) {
+  /** @type {InstanceType<typeof NatAPI> | null} */
+  let nat = null;
+  /** @type {MappedEndpoint | null} */
+  let mappedEndpoint = null;
+  let started = false;
+
+  /**
+   * Destroy the NatAPI instance, swallowing errors. `destroy()` unmaps every
+   * open port and clears the auto-renew timers.
+   *
+   * @param {InstanceType<typeof NatAPI>} instance
+   * @returns {Promise<void>}
+   */
+  async function safeDestroy(instance) {
+    try {
+      await withTimeout(instance.destroy(), STOP_TIMEOUT_MS, "destroy");
+    } 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)}`);
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async function start() {
+    if (started) {
+      return;
+    }
+    started = true;
+
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      logger.warn(`port-mapper: invalid port ${port}; skipping port mapping`);
+      return;
+    }
+
+    let instance;
+    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"
+      );
+    } 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) {
+        await safeDestroy(instance);
+      }
+      return;
+    }
+
+    // Mapping succeeded — keep the instance so its auto-renew timers stay alive
+    // and stop() can remove the mapping later.
+    nat = instance;
+
+    // Discover the external IP (best-effort; the mapping is valid without it).
+    let externalIp = null;
+    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)}`);
+    }
+
+    mappedEndpoint = { externalIp: externalIp || null, externalPort: port, protocol };
+    if (externalIp) {
+      logger.success(
+        `port-mapper: mapped ${externalIp}:${port} → ${protocol} ${port} (ttl ${ttlSeconds}s, auto-renew)`
+      );
+    } else {
+      logger.info(
+        `port-mapper: mapped ${protocol} ${port} (external IP unknown; ttl ${ttlSeconds}s, auto-renew)`
+      );
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async function stop() {
+    if (!nat) {
+      return;
+    }
+    const instance = nat;
+    nat = null;
+    mappedEndpoint = null;
+    await safeDestroy(instance);
+  }
+
+  /**
+   * @returns {MappedEndpoint | null}
+   */
+  function getMappedEndpoint() {
+    return mappedEndpoint;
+  }
+
+  return { start, stop, getMappedEndpoint };
+}

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 });
     }
   };
 }