@torrent-tv/proxy 2.61.0 → 2.63.0

package/bin/cli.js

@@ -1,512 +1,520 @@
-#!/usr/bin/env node
-/**
- * @file CLI entry point for the torrent-tv proxy.
- *
- * Parses command-line arguments, starts the local HTTP server, opens a
- * persistent WebSocket tunnel to the registry server, and registers this
- * proxy. Liveness is tracked via the tunnel connection — the proxy re-registers
- * automatically on reconnect so the server's in-memory store stays consistent.
- */
-
-// FIRST, and it must stay first: it sets how many blocking calls this process
-// can have in flight, and a module's imports are evaluated before its body, so
-// anything imported above it would get the default pool. See the file itself
-// for the measurement that made it necessary.
-import "../services/thread-pool.js";
-import { Command } from "commander";
-import crypto from "node:crypto";
-import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import ffmpegStatic from "ffmpeg-static";
-import { startProxyServer } from "../server.js";
-import { registerClient } from "../services/registry-api.js";
-import { createTunnelClient } from "../services/tunnel-client.js";
-import { createWebRtcManager } from "../services/webrtc-manager.js";
-import { createDataChannelHandler } from "../services/data-channel-handler.js";
-import { pruneCoreDumps } from "../services/core-dumps.js";
-import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/packet-witness.js";
-import { createUsrsctpStateReader } from "../services/usrsctp-state.js";
-import { startMemoryReport } from "../services/memory-report.js";
-import { collectHealthMetrics } from "../services/health-collector.js";
-import { createPortMapper } from "../services/port-mapper.js";
-import { classifyNat } from "../services/nat-classifier.js";
-import { DEFAULT_SEGMENT_FORMAT_ID, SEGMENT_FORMAT_IDS } from "../services/segment-formats/index.js";
-import { logToFile, logger } from "../utils/logger.js";
-
-const require = createRequire(import.meta.url);
-const { version: PROXY_VERSION } = require("../package.json");
-
-// Last-resort process guard. This proxy runs UNTRUSTED torrents through
-// WebTorrent, which can throw ASYNCHRONOUSLY on a malformed source — e.g. a
-// v2-only / hybrid magnet crashes `arr2hex(parsedTorrent.infoHash)` deep inside
-// `Torrent._onTorrentId` (undefined v1 infohash), in a microtask that bypasses
-// the client "error" event. Without this, one bad torrent takes down the whole
-// node and every viewer on it, and the addon restarts in a crash loop. Log the
-// full stack and keep serving: the offending session fails on its own; everyone
-// else is unaffected. (The add path also pre-validates the infohash, so this is
-// a backstop for anything not caught there.)
-process.on("uncaughtException", (error) => {
-  logger.error(`uncaughtException (kept alive): ${error?.stack ?? error}`);
-});
-process.on("unhandledRejection", (reason) => {
-  logger.error(`unhandledRejection (kept alive): ${reason instanceof Error ? reason.stack : String(reason)}`);
-});
-
-const program = new Command();
-
-const HELP_EXAMPLES = `
-Examples:
-  torrent-tv-proxy --server-url http://localhost:8080
-  torrent-tv-proxy --server-url http://localhost:8080 --host 0.0.0.0 --port 9090
-  torrent-tv-proxy --server-url http://localhost:8080 --public-base-url https://proxy.example.com
-  torrent-tv-proxy --server-url http://localhost:8080 --ffmpeg-bin /usr/local/bin/ffmpeg
-  torrent-tv-proxy --server-url http://localhost:8080 --no-transcode-audio
-
-Notes:
-  - --help prints this message and exits with code 0.
-  - Video transcode is available automatically for per-session fallback when requested by client API.
-`;
-
-if (process.argv.includes("help")) {
-  process.argv = [process.argv[0], process.argv[1], "--help"];
-}
-
-program
-  .name("torrent-proxy-client")
-  .description("Expose torrent files over HTTP stream endpoints for browser playback.")
-  .requiredOption("--server-url <url>", "Registry server base URL")
-  .option("--public-base-url <url>", "Direct URL advertised to browser clients")
-  .option("--host <host>", "Local bind host", "127.0.0.1")
-  .option("--port <port>", "Local HTTP port", "9090")
-  .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("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
-  .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
-  .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
-  .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
-  .option(
-    "--state-dir <path>",
-    "Where to keep what this host has measured about itself (default: beside the installed proxy)"
-  )
-  .option(
-    "--log-file <path>",
-    "Also write the log to this file, so a crash or an update does not take it with them"
-  )
-  .option(
-    "--segment-format <format>",
-    `HLS output container: ${SEGMENT_FORMAT_IDS.join(" | ")}`,
-    DEFAULT_SEGMENT_FORMAT_ID
-  )
-  .option("--token <token>", "Registration token", "")
-  .addHelpText("after", HELP_EXAMPLES);
-
-program.parse(process.argv);
-const options = program.opts();
-
-const localPort = Number(options.port);
-if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
-  logger.error("Invalid --port value.");
-  process.exit(1);
-}
-
-const serverUrl = String(options.serverUrl).replace(/\/+$/, "");
-const bindHost = String(options.host);
-const explicitBaseUrl = options.publicBaseUrl
-  ? String(options.publicBaseUrl).replace(/\/+$/, "")
-  : "";
-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;
-// Optional disk cap. undefined → the pool computes its own default; a valid
-// non-negative number (0 disables) → passed through.
-const maxDiskBytes =
-  options.maxDiskBytes !== undefined && Number.isFinite(Number(options.maxDiskBytes)) && Number(options.maxDiskBytes) >= 0
-    ? Number(options.maxDiskBytes)
-    : undefined;
-// Per-torrent memory budget for resident pieces. Pieces past it spill to disk
-// rather than being lost, so a small value costs read latency, never data.
-const memoryBytes =
-  options.memoryBytes !== undefined && Number.isFinite(Number(options.memoryBytes)) && Number(options.memoryBytes) > 0
-    ? Number(options.memoryBytes)
-    : undefined;
-const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
-const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
-
-/**
- * Verify that the ffmpeg binary is reachable and exits cleanly.
- * Throws with a descriptive message when the check fails.
- *
- * @returns {void}
- */
-function assertFfmpegAvailability() {
-  const probe = spawnSync(ffmpegBin, ["-version"], {
-    stdio: "ignore",
-    windowsHide: true,
-    timeout: 5000
-  });
-  if (probe.error) {
-    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
-    throw new Error(`Audio transcode is enabled, but ffmpeg is unavailable (${ffmpegBin}): ${message}`);
-  }
-  if (typeof probe.status === "number" && probe.status !== 0) {
-    throw new Error(
-      `Audio transcode is enabled, but ffmpeg check failed (${ffmpegBin}, exit code ${probe.status}).`
-    );
-  }
-}
-
-/** @type {boolean} */
-let registrationInProgress = false;
-
-/** @type {import("fastify").FastifyInstance | null} */
-let app = null;
-
-/** @type {number} */
-let actualPort = localPort;
-
-/** @type {boolean} */
-let shutdownInProgress = false;
-
-/** @type {ReturnType<typeof createTunnelClient> | null} */
-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;
-
-/** @type {ReturnType<typeof createWebRtcManager> | null} */
-let webRtcManager = null;
-/**
- * The packet witness, so shutdown can stop the ring it owns.
- *
- * @type {ReturnType<typeof createPacketWitness> | null}
- */
-let packetWitness = null;
-
-/** @type {ReturnType<typeof createUsrsctpStateReader> | null} */
-let usrsctpStateReader = null;
-
-/** @type {ReturnType<typeof createDataChannelHandler> | null} */
-let dataChannelHandler = null;
-
-/** @type {import("../services/nat-classifier.js").NatClassification | null} Latest NAT classification (for WebRTC port prediction). */
-let natInfo = null;
-
-
-/**
- * Register this proxy with the registry server.
- * Silently skips if a registration is already in flight.
- *
- * @returns {Promise<void>}
- */
-async function registerClientSafe() {
-  if (registrationInProgress) {
-    return;
-  }
-  registrationInProgress = true;
-  try {
-    const result = await registerClient({
-      serverUrl,
-      id: clientId,
-      name: clientName,
-      baseUrl: explicitBaseUrl || `http://${bindHost}:${actualPort}`,
-      token
-    });
-    logger.success(`Registered as "${result.client?.name}" (${result.client?.id?.slice(0, 8)})`);
-  } finally {
-    registrationInProgress = false;
-  }
-}
-
-/**
- * Register this proxy with the registry server, retrying indefinitely
- * with exponential backoff until it succeeds. This allows the proxy to
- * survive temporary server outages (restarts, deployments) without crashing.
- *
- * @returns {Promise<void>}
- */
-async function registerWithRetry() {
-  const MAX_DELAY_MS = 60_000;
-  let delayMs = 2_000;
-  let attempt = 0;
-  while (true) {
-    attempt++;
-    try {
-      await registerClientSafe();
-      return;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.warn(`Registration attempt ${attempt} failed: ${message}. Retrying in ${delayMs / 1000}s…`);
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
-      delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
-    }
-  }
-}
-
-/**
- * Gracefully shut down the tunnel, heartbeat timer, and HTTP server.
- *
- * @param {string} signal - Signal name (e.g. "SIGINT").
- * @returns {Promise<void>}
- */
-async function shutdown(signal) {
-  if (shutdownInProgress) {
-    return;
-  }
-  shutdownInProgress = true;
-  if (tunnelClient) {
-    tunnelClient.disconnect();
-    tunnelClient = null;
-  }
-  logger.warn(`Received ${signal}, shutting down...`);
-  try {
-    // 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;
-    }
-    // Close WebRTC sessions and release the shared UDP mux listener socket.
-    if (webRtcManager) {
-      try { webRtcManager.dispose(); } catch { /* ignore */ }
-      webRtcManager = null;
-    }
-    // Stop the packet ring and remove its scratch files. `process.exit` below
-    // does not take child processes with it, so without this a proxy restarted
-    // outside a container leaves one tcpdump running per restart.
-    if (packetWitness) {
-      try { await packetWitness.dispose(); } catch { /* ignore */ }
-      packetWitness = null;
-    }
-    if (app) {
-      await app.close();
-    }
-    process.exit(0);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(`Shutdown failed: ${message}`);
-    process.exit(1);
-  }
-}
-
-try {
-  logToFile(options.logFile);
-  if (transcodeAudio) {
-    assertFfmpegAvailability();
-  }
-  const started = await startProxyServer({
-    host: bindHost,
-    port: localPort,
-    transcodeAudio,
-    ffmpegBin,
-    maxDiskBytes,
-    memoryBytes,
-    segmentFormat: options.segmentFormat,
-    stateDir: options.stateDir,
-    deliverySink: options.deliverySink === true,
-    // Late-bound the same way `webRtcManager` is below: the torrent pool is
-    // built inside `startProxyServer`, before `dataChannelHandler` — the
-    // thing that actually owns a channel to push down — exists.
-    onSubtitleCues: (event) => dataChannelHandler?.publishSubtitleCues(event)
-  });
-  app = started.app;
-  actualPort = started.port;
-  const sourceRegistry = started.sourceRegistry;
-  const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
-
-  // A native fault writes the whole address space out — 4.18 GB each on the
-  // field host, and four of them nearly filled a 235 GB disk. Keep the newest
-  // two, which are the evidence for the fault still open, and drop the rest.
-  void pruneCoreDumps(options.stateDir);
-  // Same policy for the packet captures the send-queue witness writes.
-  packetWitness = createPacketWitness({
-    log: (message) => logger.info(message),
-    dir: options.stateDir || "",
-    port: actualPort
-  });
-  // A process that was KILLED mid-session leaves the ring's last seconds
-  // behind, and those seconds contain whatever ended it. Keep them under a name
-  // the pruner recognises BEFORE anything starts a new ring over them.
-  void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir));
-
-  // Reads usrsctp's own association state via gdb the moment a wedge is
-  // declared (roadmap item 11) — no source rebuild, the module ships
-  // unstripped. A host without gdb just never gets a reading, the same way a
-  // host without tcpdump never gets a packet capture.
-  usrsctpStateReader = createUsrsctpStateReader({ log: (message) => logger.info(message) });
-
-  // What this process holds, once a minute. The kernel killed the proxy on
-  // 2026-08-28 at 2.4 GB resident and the log had never said a word about
-  // memory, so the growth that ended in that kill has no shape in any record we
-  // keep. RSS is the figure the OOM killer reads, so RSS is the figure to say.
-  startMemoryReport({ log: (message) => logger.info(message) });
-
-  logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
-  logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
-  logger.info(`Advertised direct URL: ${directBaseUrl}`);
-  if (transcodeAudio) {
-    logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
-  }
-
-  // All WebRTC sessions are multiplexed onto this single UDP port (same number
-  // as the HTTP port, different protocol) via a persistent ICE UDP mux listener
-  // in the WebRTC manager. One port → one UPnP mapping → one reachable endpoint.
-  const webrtcUdpPort = actualPort;
-
-  // 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}`);
-      });
-
-    // Also map the single WebRTC UDP port. Not reported to the server: the
-    // browser discovers the endpoint via ICE (srflx) candidates, not the TCP
-    // dial-back probe.
-    udpPortMapper = createPortMapper({
-      port: webrtcUdpPort,
-      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) => {
-      // Stored for WebRTC port prediction (webRtcManager reads it per session).
-      natInfo = 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 offers predicted ports (base+delta*k) — covers sequential/predictable symmetric NAT, not fully random`
-        );
-      } 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.
-  //
-  // We use a late-binding ref so both objects can reference each other without
-  // running into the TDZ (tunnelClient is declared above; webRtcManager is the
-  // module-scoped `let` above so the closure in createTunnelClient — and the
-  // shutdown handler — can reach it after initialisation).
-
-  tunnelClient = createTunnelClient({
-    serverUrl,
-    proxyId: clientId,
-    token,
-    proxyPort: actualPort,
-    onSignal(sessionId, signal) {
-      webRtcManager?.handleSignal(sessionId, signal);
-    },
-    onHealthRequest() {
-      return collectHealthMetrics();
-    },
-    onConnect() {
-      // Re-register on every tunnel connect/reconnect so the server's
-      // in-memory store stays consistent after server restarts.
-      void registerClientSafe().catch((error) => {
-        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)
-  });
-
-  dataChannelHandler = createDataChannelHandler({
-    proxyPort: actualPort,
-    onLog: (message) => logger.info(message),
-    // Resolves a browser's registry sourceKey to the torrent pool's own key
-    // (the content's infohash) so the subtitle push subscription and the
-    // pool's own publish agree on what a source is called. See server.js.
-    sourceRegistry,
-    // Lets a stuck send queue ask the transport what it is doing. Late-bound:
-    // the manager is created below, with this handler already in hand.
-    getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null,
-    // Records the wire when a queue stays wedged — how the rare one-way
-    // transmit death (roadmap item 10, 2026-08-24) gets its evidence.
-    witness: packetWitness,
-    usrsctpState: usrsctpStateReader
-  });
-
-  webRtcManager = createWebRtcManager({
-    // Single UDP port (UPnP-mapped above) shared by all sessions via a
-    // persistent ICE UDP mux listener, so the WebRTC path is reachable from the
-    // internet on one fixed port.
-    udpPort: webrtcUdpPort,
-    // Latest NAT classification — enables symmetric-NAT port prediction.
-    getNatInfo: () => natInfo,
-    sendSignal(sessionId, signal) {
-      tunnelClient?.sendSignal(sessionId, signal);
-    },
-    onDataChannel(sessionId, channel) {
-      dataChannelHandler.handleChannel(sessionId, channel);
-    },
-    onLog: (message) => logger.info(message)
-  });
-
-  tunnelClient.connect();
-
-  await registerWithRetry();
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  logger.error(message);
-  process.exit(1);
-}
-
-process.on("SIGINT", () => {
-  void shutdown("SIGINT");
-});
-
-process.on("SIGTERM", () => {
-  void shutdown("SIGTERM");
-});
+#!/usr/bin/env node
+/**
+ * @file CLI entry point for the torrent-tv proxy.
+ *
+ * Parses command-line arguments, starts the local HTTP server, opens a
+ * persistent WebSocket tunnel to the registry server, and registers this
+ * proxy. Liveness is tracked via the tunnel connection — the proxy re-registers
+ * automatically on reconnect so the server's in-memory store stays consistent.
+ */
+
+// FIRST, and it must stay first: it sets how many blocking calls this process
+// can have in flight, and a module's imports are evaluated before its body, so
+// anything imported above it would get the default pool. See the file itself
+// for the measurement that made it necessary.
+import "../services/thread-pool.js";
+import { Command } from "commander";
+import crypto from "node:crypto";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import ffmpegStatic from "ffmpeg-static";
+import { startProxyServer } from "../server.js";
+import { registerClient } from "../services/registry-api.js";
+import { createTunnelClient } from "../services/tunnel-client.js";
+import { createWebRtcManager } from "../services/webrtc-manager.js";
+import { createDataChannelHandler } from "../services/data-channel-handler.js";
+import { pruneCoreDumps } from "../services/core-dumps.js";
+import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/packet-witness.js";
+import { createUsrsctpStateReader } from "../services/usrsctp-state.js";
+import { startMemoryReport } from "../services/memory-report.js";
+import { collectHealthMetrics } from "../services/health-collector.js";
+import { createPortMapper } from "../services/port-mapper.js";
+import { classifyNat } from "../services/nat-classifier.js";
+import { DEFAULT_SEGMENT_FORMAT_ID, SEGMENT_FORMAT_IDS } from "../services/segment-formats/index.js";
+import { logToFile, logger } from "../utils/logger.js";
+
+const require = createRequire(import.meta.url);
+const { version: PROXY_VERSION } = require("../package.json");
+
+// Last-resort process guard. This proxy runs UNTRUSTED torrents through
+// WebTorrent, which can throw ASYNCHRONOUSLY on a malformed source — e.g. a
+// v2-only / hybrid magnet crashes `arr2hex(parsedTorrent.infoHash)` deep inside
+// `Torrent._onTorrentId` (undefined v1 infohash), in a microtask that bypasses
+// the client "error" event. Without this, one bad torrent takes down the whole
+// node and every viewer on it, and the addon restarts in a crash loop. Log the
+// full stack and keep serving: the offending session fails on its own; everyone
+// else is unaffected. (The add path also pre-validates the infohash, so this is
+// a backstop for anything not caught there.)
+process.on("uncaughtException", (error) => {
+  logger.error(`uncaughtException (kept alive): ${error?.stack ?? error}`);
+});
+process.on("unhandledRejection", (reason) => {
+  logger.error(`unhandledRejection (kept alive): ${reason instanceof Error ? reason.stack : String(reason)}`);
+});
+
+const program = new Command();
+
+const HELP_EXAMPLES = `
+Examples:
+  torrent-tv-proxy --server-url http://localhost:8080
+  torrent-tv-proxy --server-url http://localhost:8080 --host 0.0.0.0 --port 9090
+  torrent-tv-proxy --server-url http://localhost:8080 --public-base-url https://proxy.example.com
+  torrent-tv-proxy --server-url http://localhost:8080 --ffmpeg-bin /usr/local/bin/ffmpeg
+  torrent-tv-proxy --server-url http://localhost:8080 --no-transcode-audio
+
+Notes:
+  - --help prints this message and exits with code 0.
+  - Video transcode is available automatically for per-session fallback when requested by client API.
+`;
+
+if (process.argv.includes("help")) {
+  process.argv = [process.argv[0], process.argv[1], "--help"];
+}
+
+program
+  .name("torrent-proxy-client")
+  .description("Expose torrent files over HTTP stream endpoints for browser playback.")
+  .requiredOption("--server-url <url>", "Registry server base URL")
+  .option("--public-base-url <url>", "Direct URL advertised to browser clients")
+  .option("--host <host>", "Local bind host", "127.0.0.1")
+  .option("--port <port>", "Local HTTP port", "9090")
+  .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("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
+  .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
+  .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
+  .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
+  .option(
+    "--state-dir <path>",
+    "Where to keep what this host has measured about itself (default: beside the installed proxy)"
+  )
+  .option(
+    "--log-file <path>",
+    "Also write the log to this file, so a crash or an update does not take it with them"
+  )
+  .option(
+    "--segment-format <format>",
+    `HLS output container: ${SEGMENT_FORMAT_IDS.join(" | ")}`,
+    DEFAULT_SEGMENT_FORMAT_ID
+  )
+  .option("--token <token>", "Registration token", "")
+  .addHelpText("after", HELP_EXAMPLES);
+
+program.parse(process.argv);
+const options = program.opts();
+
+const localPort = Number(options.port);
+if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
+  logger.error("Invalid --port value.");
+  process.exit(1);
+}
+
+const serverUrl = String(options.serverUrl).replace(/\/+$/, "");
+const bindHost = String(options.host);
+const explicitBaseUrl = options.publicBaseUrl
+  ? String(options.publicBaseUrl).replace(/\/+$/, "")
+  : "";
+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;
+// Optional disk cap. undefined → the pool computes its own default; a valid
+// non-negative number (0 disables) → passed through.
+const maxDiskBytes =
+  options.maxDiskBytes !== undefined && Number.isFinite(Number(options.maxDiskBytes)) && Number(options.maxDiskBytes) >= 0
+    ? Number(options.maxDiskBytes)
+    : undefined;
+// Per-torrent memory budget for resident pieces. Pieces past it spill to disk
+// rather than being lost, so a small value costs read latency, never data.
+const memoryBytes =
+  options.memoryBytes !== undefined && Number.isFinite(Number(options.memoryBytes)) && Number(options.memoryBytes) > 0
+    ? Number(options.memoryBytes)
+    : undefined;
+const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
+const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
+
+/**
+ * Verify that the ffmpeg binary is reachable and exits cleanly.
+ * Throws with a descriptive message when the check fails.
+ *
+ * @returns {void}
+ */
+function assertFfmpegAvailability() {
+  const probe = spawnSync(ffmpegBin, ["-version"], {
+    stdio: "ignore",
+    windowsHide: true,
+    timeout: 5000
+  });
+  if (probe.error) {
+    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
+    throw new Error(`Audio transcode is enabled, but ffmpeg is unavailable (${ffmpegBin}): ${message}`);
+  }
+  if (typeof probe.status === "number" && probe.status !== 0) {
+    throw new Error(
+      `Audio transcode is enabled, but ffmpeg check failed (${ffmpegBin}, exit code ${probe.status}).`
+    );
+  }
+}
+
+/** @type {boolean} */
+let registrationInProgress = false;
+
+/** @type {import("fastify").FastifyInstance | null} */
+let app = null;
+
+/** @type {number} */
+let actualPort = localPort;
+
+/** @type {boolean} */
+let shutdownInProgress = false;
+
+/** @type {ReturnType<typeof createTunnelClient> | null} */
+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;
+
+/** @type {ReturnType<typeof createWebRtcManager> | null} */
+let webRtcManager = null;
+/**
+ * The packet witness, so shutdown can stop the ring it owns.
+ *
+ * @type {ReturnType<typeof createPacketWitness> | null}
+ */
+let packetWitness = null;
+
+/** @type {ReturnType<typeof createUsrsctpStateReader> | null} */
+let usrsctpStateReader = null;
+
+/** @type {ReturnType<typeof createDataChannelHandler> | null} */
+let dataChannelHandler = null;
+
+/** @type {import("../services/nat-classifier.js").NatClassification | null} Latest NAT classification (for WebRTC port prediction). */
+let natInfo = null;
+
+
+/**
+ * Register this proxy with the registry server.
+ * Silently skips if a registration is already in flight.
+ *
+ * @returns {Promise<void>}
+ */
+async function registerClientSafe() {
+  if (registrationInProgress) {
+    return;
+  }
+  registrationInProgress = true;
+  try {
+    const result = await registerClient({
+      serverUrl,
+      id: clientId,
+      name: clientName,
+      baseUrl: explicitBaseUrl || `http://${bindHost}:${actualPort}`,
+      token
+    });
+    logger.success(`Registered as "${result.client?.name}" (${result.client?.id?.slice(0, 8)})`);
+  } finally {
+    registrationInProgress = false;
+  }
+}
+
+/**
+ * Register this proxy with the registry server, retrying indefinitely
+ * with exponential backoff until it succeeds. This allows the proxy to
+ * survive temporary server outages (restarts, deployments) without crashing.
+ *
+ * @returns {Promise<void>}
+ */
+async function registerWithRetry() {
+  const MAX_DELAY_MS = 60_000;
+  let delayMs = 2_000;
+  let attempt = 0;
+  while (true) {
+    attempt++;
+    try {
+      await registerClientSafe();
+      return;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`Registration attempt ${attempt} failed: ${message}. Retrying in ${delayMs / 1000}s…`);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
+    }
+  }
+}
+
+/**
+ * Gracefully shut down the tunnel, heartbeat timer, and HTTP server.
+ *
+ * @param {string} signal - Signal name (e.g. "SIGINT").
+ * @returns {Promise<void>}
+ */
+async function shutdown(signal) {
+  if (shutdownInProgress) {
+    return;
+  }
+  shutdownInProgress = true;
+  if (tunnelClient) {
+    tunnelClient.disconnect();
+    tunnelClient = null;
+  }
+  logger.warn(`Received ${signal}, shutting down...`);
+  try {
+    // 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;
+    }
+    // Close WebRTC sessions and release the shared UDP mux listener socket.
+    if (webRtcManager) {
+      try { webRtcManager.dispose(); } catch { /* ignore */ }
+      webRtcManager = null;
+    }
+    // Stop the packet ring and remove its scratch files. `process.exit` below
+    // does not take child processes with it, so without this a proxy restarted
+    // outside a container leaves one tcpdump running per restart.
+    if (packetWitness) {
+      try { await packetWitness.dispose(); } catch { /* ignore */ }
+      packetWitness = null;
+    }
+    if (app) {
+      await app.close();
+    }
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Shutdown failed: ${message}`);
+    process.exit(1);
+  }
+}
+
+try {
+  logToFile(options.logFile);
+  if (transcodeAudio) {
+    assertFfmpegAvailability();
+  }
+  const started = await startProxyServer({
+    host: bindHost,
+    port: localPort,
+    transcodeAudio,
+    ffmpegBin,
+    maxDiskBytes,
+    memoryBytes,
+    segmentFormat: options.segmentFormat,
+    stateDir: options.stateDir,
+    deliverySink: options.deliverySink === true,
+    // Late-bound the same way `webRtcManager` is below: the torrent pool is
+    // built inside `startProxyServer`, before `dataChannelHandler` — the
+    // thing that actually owns a channel to push down — exists.
+    onSubtitleCues: (event) => dataChannelHandler?.publishSubtitleCues(event)
+  });
+  app = started.app;
+  actualPort = started.port;
+  const sourceRegistry = started.sourceRegistry;
+  const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
+
+  // A native fault writes the whole address space out — 4.18 GB each on the
+  // field host, and four of them nearly filled a 235 GB disk. Keep the newest
+  // two, which are the evidence for the fault still open, and drop the rest.
+  void pruneCoreDumps(options.stateDir);
+  // Same policy for the packet captures the send-queue witness writes.
+  packetWitness = createPacketWitness({
+    log: (message) => logger.info(message),
+    dir: options.stateDir || "",
+    port: actualPort
+  });
+  // A process that was KILLED mid-session leaves the ring's last seconds
+  // behind, and those seconds contain whatever ended it. Keep them under a name
+  // the pruner recognises BEFORE anything starts a new ring over them.
+  void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir));
+
+  // Reads usrsctp's own association state via gdb the moment a wedge is
+  // declared (roadmap item 11) — no source rebuild, the module ships
+  // unstripped. A host without gdb just never gets a reading, the same way a
+  // host without tcpdump never gets a packet capture.
+  usrsctpStateReader = createUsrsctpStateReader({ log: (message) => logger.info(message) });
+
+  // What this process holds, once a minute. The kernel killed the proxy on
+  // 2026-08-28 at 2.4 GB resident and the log had never said a word about
+  // memory, so the growth that ended in that kill has no shape in any record we
+  // keep. RSS is the figure the OOM killer reads, so RSS is the figure to say.
+  // The disk path is where pieces spill and torrent data lands. A budget for
+  // memory alone is half a budget: a store that behaves about RAM can still
+  // fill the card an addon host boots from, and neither limit was measured
+  // before (roadmap item 2).
+  startMemoryReport({
+    log: (message) => logger.info(message),
+    diskPath: os.tmpdir()
+  });
+
+  logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
+  logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
+  logger.info(`Advertised direct URL: ${directBaseUrl}`);
+  if (transcodeAudio) {
+    logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
+  }
+
+  // All WebRTC sessions are multiplexed onto this single UDP port (same number
+  // as the HTTP port, different protocol) via a persistent ICE UDP mux listener
+  // in the WebRTC manager. One port → one UPnP mapping → one reachable endpoint.
+  const webrtcUdpPort = actualPort;
+
+  // 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}`);
+      });
+
+    // Also map the single WebRTC UDP port. Not reported to the server: the
+    // browser discovers the endpoint via ICE (srflx) candidates, not the TCP
+    // dial-back probe.
+    udpPortMapper = createPortMapper({
+      port: webrtcUdpPort,
+      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) => {
+      // Stored for WebRTC port prediction (webRtcManager reads it per session).
+      natInfo = 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 offers predicted ports (base+delta*k) — covers sequential/predictable symmetric NAT, not fully random`
+        );
+      } 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.
+  //
+  // We use a late-binding ref so both objects can reference each other without
+  // running into the TDZ (tunnelClient is declared above; webRtcManager is the
+  // module-scoped `let` above so the closure in createTunnelClient — and the
+  // shutdown handler — can reach it after initialisation).
+
+  tunnelClient = createTunnelClient({
+    serverUrl,
+    proxyId: clientId,
+    token,
+    proxyPort: actualPort,
+    onSignal(sessionId, signal) {
+      webRtcManager?.handleSignal(sessionId, signal);
+    },
+    onHealthRequest() {
+      return collectHealthMetrics();
+    },
+    onConnect() {
+      // Re-register on every tunnel connect/reconnect so the server's
+      // in-memory store stays consistent after server restarts.
+      void registerClientSafe().catch((error) => {
+        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)
+  });
+
+  dataChannelHandler = createDataChannelHandler({
+    proxyPort: actualPort,
+    onLog: (message) => logger.info(message),
+    // Resolves a browser's registry sourceKey to the torrent pool's own key
+    // (the content's infohash) so the subtitle push subscription and the
+    // pool's own publish agree on what a source is called. See server.js.
+    sourceRegistry,
+    // Lets a stuck send queue ask the transport what it is doing. Late-bound:
+    // the manager is created below, with this handler already in hand.
+    getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null,
+    // Records the wire when a queue stays wedged — how the rare one-way
+    // transmit death (roadmap item 10, 2026-08-24) gets its evidence.
+    witness: packetWitness,
+    usrsctpState: usrsctpStateReader
+  });
+
+  webRtcManager = createWebRtcManager({
+    // Single UDP port (UPnP-mapped above) shared by all sessions via a
+    // persistent ICE UDP mux listener, so the WebRTC path is reachable from the
+    // internet on one fixed port.
+    udpPort: webrtcUdpPort,
+    // Latest NAT classification — enables symmetric-NAT port prediction.
+    getNatInfo: () => natInfo,
+    sendSignal(sessionId, signal) {
+      tunnelClient?.sendSignal(sessionId, signal);
+    },
+    onDataChannel(sessionId, channel) {
+      dataChannelHandler.handleChannel(sessionId, channel);
+    },
+    onLog: (message) => logger.info(message)
+  });
+
+  tunnelClient.connect();
+
+  await registerWithRetry();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  logger.error(message);
+  process.exit(1);
+}
+
+process.on("SIGINT", () => {
+  void shutdown("SIGINT");
+});
+
+process.on("SIGTERM", () => {
+  void shutdown("SIGTERM");
+});