@torrent-tv/proxy 2.9.14 → 2.9.16

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.)
+
 ## 2.9.14
 
 - **New**: `GET /api/sources/:sourceKey/stats` now reports `headerBytes` / `headerDownloadedBytes` — how much of the file's header/index region (leading 256 KB + trailing 2 MB, the bytes the codec probe needs) is downloaded, counted by whole torrent pieces from the bitfield. Lets the browser show the download phase's progress and ETA toward the next (transcode) phase. Coarse by design (piece granularity).

package/CLAUDE.md

@@ -47,6 +47,63 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
   around it with `--ignore-scripts` + a targeted rebuild of `node-datachannel`;
   if you ever change install flow, keep that in mind.
 
+## Planned: public reachability (remote access)
+
+Decided direction — full plan in the parent `../CLAUDE.md`. Proxy-side pieces:
+
+- **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
+  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.
+- Future: ed25519 proxy identity (sign announcements), BEP 44 endpoint
+  announcements via the `bittorrent-dht` already bundled with WebTorrent.
+
+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.
+Level 2 (research): sliding-window chunk store. Full rationale in the parent
+`../CLAUDE.md` "Disk hygiene" section.
+
+## Cloud proxy
+
+The same proxy code also runs as the company-hosted fallback when the user
+pool can't serve a viewer. Keep the proxy host-agnostic so it runs unchanged on
+rented infra (flat-rate/unmetered bandwidth — Hetzner dedicated / OVH; NOT
+metered-egress clouds). Provider/economics analysis in the parent
+`../CLAUDE.md` "Cloud proxy" section.
+
 ## Changelog
 
 Every behavioural change must be recorded in `CHANGELOG.md` — add an entry under

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.14",
+  "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/server.js

@@ -154,7 +154,10 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }
   });
 
   app.addHook("onClose", async () => {
+    // Order matters: stop the ffmpeg readers (HLS sessions) before destroying
+    // the torrents whose files they read from, then remove the torrent data.
     await hlsSessionManager.disposeAll();
+    await torrentPool.destroyAll();
   });
 
   await app.listen({ host, port: selectedPort });

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/torrent-pool.js

@@ -423,4 +423,56 @@ export class TorrentPool {
       // Best effort — never break streaming because prioritization failed.
     }
   }
+
+  /**
+   * Destroy every torrent together with its on-disk store, then tear down the
+   * WebTorrent client. Called from the proxy's graceful-shutdown `onClose`
+   * hook so downloaded torrent data does not linger under `os.tmpdir()` after
+   * the process stops.
+   *
+   * `client.destroy()` on its own destroys the torrents but only *closes* their
+   * stores (data stays on disk), so each torrent is removed explicitly with
+   * `{ destroyStore: true }` first. Best-effort: never rejects and never hangs
+   * on a single store-removal error during shutdown.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroyAll() {
+    if (!this.client || this.client.destroyed) {
+      return;
+    }
+
+    // Destroy each torrent with its store so downloaded pieces are removed
+    // from disk. This also removes the torrent from `client.torrents`, so the
+    // subsequent `client.destroy()` only tears down the client internals.
+    const torrents = [...this.client.torrents];
+    await Promise.all(
+      torrents.map(
+        (torrent) =>
+          new Promise((resolve) => {
+            try {
+              torrent.destroy({ destroyStore: true }, () => resolve());
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              logger.warn(`failed to destroy torrent store: ${message}`);
+              resolve();
+            }
+          })
+      )
+    );
+
+    // Tear down the client itself (DHT, connection pool, TCP server).
+    await new Promise((resolve) => {
+      try {
+        this.client.destroy(() => resolve());
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`failed to destroy WebTorrent client: ${message}`);
+        resolve();
+      }
+    });
+
+    this.torrents.clear();
+    this.#pending.clear();
+  }
 }