@torrent-tv/proxy 2.9.15 → 2.9.16

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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,11 +51,16 @@ 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.
+- **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 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.
 - **HTTPS listener**: serve the existing routes over TLS with a per-proxy

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,20 @@ 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().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.

package/package.json

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