@torrent-tv/proxy 2.87.21 → 2.88.0

package/services/transport/port-mapper.js

@@ -1,235 +1,235 @@
-/**
- * @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}.
- * @param {number} [opts.portRangeEnd] - When set and > `port`, map the whole
- *   contiguous range `[port..portRangeEnd]` (used for the WebRTC UDP range, so
- *   whichever port a session binds is reachable). Single port otherwise.
- * @returns {PortMapper}
- */
-export function createPortMapper({
-  port,
-  protocol = "TCP",
-  description = "torrent-tv proxy",
-  ttlSeconds = DEFAULT_TTL_SECONDS,
-  portRangeEnd
-} = {}) {
-  const rangeEnd = Number.isInteger(portRangeEnd) && portRangeEnd > port ? portRangeEnd : null;
-  const portList = rangeEnd
-    ? Array.from({ length: rangeEnd - port + 1 }, (_, i) => port + i)
-    : [port];
-  const label = rangeEnd ? `${protocol} ${port}-${rangeEnd}` : `${protocol} ${port}`;
-
-  /** @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, { logRemoval = false } = {}) {
-    try {
-      await withTimeout(instance.destroy(), STOP_TIMEOUT_MS, "destroy");
-      if (logRemoval) {
-        logger.info(`port-mapper: removed mapping for ${label}`);
-      }
-    } catch (error) {
-      // Lease expiry (ttl) is the backstop if we cannot unmap cleanly.
-      logger.warn(`port-mapper: failed to remove ${label} 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;
-    let mappedCount = 0;
-    try {
-      instance = new NatAPI({ ttl: ttlSeconds, autoUpdate: true, description });
-      // Map every port in the range, best-effort per port (one port failing
-      // must not abort the rest). All share the one NatAPI instance, so its
-      // auto-renew covers them and a single destroy() unmaps all.
-      for (const p of portList) {
-        try {
-          await withTimeout(
-            instance.map({ publicPort: p, privatePort: p, protocol, description, ttl: ttlSeconds }),
-            START_TIMEOUT_MS,
-            `map ${p}`
-          );
-          mappedCount++;
-          if (mappedCount === 1) {
-            // The UPnP SSDP emitter gains one listener per map()/renewal; a
-            // 10-port range exceeds Node's default limit of 10 and floods the
-            // log with MaxListenersExceededWarning. The client is created
-            // lazily by the first map(), so lift the limit right after it.
-            instance._upnpClient?.ssdp?.setMaxListeners?.(0);
-          }
-        } catch (error) {
-          logger.warn(`port-mapper: failed to map ${protocol} ${p}: ${describeError(error)}`);
-        }
-      }
-    } catch (error) {
-      mappedEndpoint = null;
-      logger.warn(`port-mapper: no port mapping available (${describeError(error)}); continuing without it`);
-      if (instance) {
-        await safeDestroy(instance);
-      }
-      return;
-    }
-
-    if (mappedCount === 0) {
-      // 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 ports mapped for ${label}; continuing without it`);
-      await safeDestroy(instance);
-      return;
-    }
-
-    // Mapping succeeded — keep the instance so its auto-renew timers stay alive
-    // and stop() can remove the mappings 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 ${label} but could not read external IP: ${describeError(error)}`);
-    }
-
-    mappedEndpoint = { externalIp: externalIp || null, externalPort: port, protocol };
-    const counts = portList.length > 1 ? ` (${mappedCount}/${portList.length} ports)` : "";
-    if (externalIp) {
-      logger.success(
-        `port-mapper: mapped ${externalIp} → ${label}${counts} (ttl ${ttlSeconds}s, auto-renew)`
-      );
-    } else {
-      logger.info(
-        `port-mapper: mapped ${label}${counts} (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, { logRemoval: true });
-  }
-
-  /**
-   * @returns {MappedEndpoint | null}
-   */
-  function getMappedEndpoint() {
-    return mappedEndpoint;
-  }
-
-  return { start, stop, getMappedEndpoint };
-}
+/**
+ * @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}.
+ * @param {number} [opts.portRangeEnd] - When set and > `port`, map the whole
+ *   contiguous range `[port..portRangeEnd]` (used for the WebRTC UDP range, so
+ *   whichever port a session binds is reachable). Single port otherwise.
+ * @returns {PortMapper}
+ */
+export function createPortMapper({
+  port,
+  protocol = "TCP",
+  description = "torrent-tv proxy",
+  ttlSeconds = DEFAULT_TTL_SECONDS,
+  portRangeEnd
+} = {}) {
+  const rangeEnd = Number.isInteger(portRangeEnd) && portRangeEnd > port ? portRangeEnd : null;
+  const portList = rangeEnd
+    ? Array.from({ length: rangeEnd - port + 1 }, (_, i) => port + i)
+    : [port];
+  const label = rangeEnd ? `${protocol} ${port}-${rangeEnd}` : `${protocol} ${port}`;
+
+  /** @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, { logRemoval = false } = {}) {
+    try {
+      await withTimeout(instance.destroy(), STOP_TIMEOUT_MS, "destroy");
+      if (logRemoval) {
+        logger.info(`port-mapper: removed mapping for ${label}`);
+      }
+    } catch (error) {
+      // Lease expiry (ttl) is the backstop if we cannot unmap cleanly.
+      logger.warn(`port-mapper: failed to remove ${label} 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;
+    let mappedCount = 0;
+    try {
+      instance = new NatAPI({ ttl: ttlSeconds, autoUpdate: true, description });
+      // Map every port in the range, best-effort per port (one port failing
+      // must not abort the rest). All share the one NatAPI instance, so its
+      // auto-renew covers them and a single destroy() unmaps all.
+      for (const p of portList) {
+        try {
+          await withTimeout(
+            instance.map({ publicPort: p, privatePort: p, protocol, description, ttl: ttlSeconds }),
+            START_TIMEOUT_MS,
+            `map ${p}`
+          );
+          mappedCount++;
+          if (mappedCount === 1) {
+            // The UPnP SSDP emitter gains one listener per map()/renewal; a
+            // 10-port range exceeds Node's default limit of 10 and floods the
+            // log with MaxListenersExceededWarning. The client is created
+            // lazily by the first map(), so lift the limit right after it.
+            instance._upnpClient?.ssdp?.setMaxListeners?.(0);
+          }
+        } catch (error) {
+          logger.warn(`port-mapper: failed to map ${protocol} ${p}: ${describeError(error)}`);
+        }
+      }
+    } catch (error) {
+      mappedEndpoint = null;
+      logger.warn(`port-mapper: no port mapping available (${describeError(error)}); continuing without it`);
+      if (instance) {
+        await safeDestroy(instance);
+      }
+      return;
+    }
+
+    if (mappedCount === 0) {
+      // 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 ports mapped for ${label}; continuing without it`);
+      await safeDestroy(instance);
+      return;
+    }
+
+    // Mapping succeeded — keep the instance so its auto-renew timers stay alive
+    // and stop() can remove the mappings 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 ${label} but could not read external IP: ${describeError(error)}`);
+    }
+
+    mappedEndpoint = { externalIp: externalIp || null, externalPort: port, protocol };
+    const counts = portList.length > 1 ? ` (${mappedCount}/${portList.length} ports)` : "";
+    if (externalIp) {
+      logger.success(
+        `port-mapper: mapped ${externalIp} → ${label}${counts} (ttl ${ttlSeconds}s, auto-renew)`
+      );
+    } else {
+      logger.info(
+        `port-mapper: mapped ${label}${counts} (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, { logRemoval: true });
+  }
+
+  /**
+   * @returns {MappedEndpoint | null}
+   */
+  function getMappedEndpoint() {
+    return mappedEndpoint;
+  }
+
+  return { start, stop, getMappedEndpoint };
+}

package/services/transport/registry-api.js

@@ -1,81 +1,81 @@
-/**
- * @file HTTP client for the registry server API.
- *
- * Handles proxy registration with the registry server.
- * The auth token is sent as the `x-proxy-token` request header.
- *
- * Liveness is tracked via the WebSocket tunnel connection — no heartbeat
- * HTTP polling is needed.  The proxy re-registers on every tunnel reconnect
- * so the server's in-memory store stays consistent after restarts.
- */
-
-/**
- * Parameters required to register this proxy with the registry server.
- *
- * @typedef {Object} RegisterClientParams
- * @property {string} serverUrl - Base URL of the registry server (e.g. "http://my-server:8080").
- * @property {string} id        - Stable unique identifier for this proxy instance.
- * @property {string} name      - Human-readable display name shown in the server UI.
- * @property {string} baseUrl   - Publicly reachable base URL of this proxy's HTTP server.
- * @property {string} token     - Auth token sent as the `x-proxy-token` header.
- */
-
-/**
- * The summary record returned by the server after a successful registration.
- *
- * @typedef {Object} ProxyClientSummary
- * @property {string} id         - Stable unique identifier.
- * @property {string} name       - Display name.
- * @property {string} baseUrl    - Advertised base URL.
- * @property {string} createdAt  - ISO timestamp of first registration.
- * @property {string} lastSeenAt - ISO timestamp of this registration.
- */
-
-/**
- * Build a full URL to a registry API endpoint.
- *
- * @param {string} serverUrl - Base URL of the registry server.
- * @param {string} pathname  - Relative path (e.g. "api/proxy-clients/register").
- * @returns {URL}
- */
-function buildRegistryUrl(serverUrl, pathname) {
-  return new URL(pathname, ensureBaseUrl(serverUrl));
-}
-
-/**
- * Ensure the server URL ends with a trailing slash so that relative
- * paths in `new URL(pathname, base)` resolve correctly.
- *
- * @param {string} serverUrl
- * @returns {string}
- */
-function ensureBaseUrl(serverUrl) {
-  return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
-}
-
-/**
- * Register this proxy with the registry server.
- *
- * Throws if the server responds with a non-2xx status.  The caller is
- * responsible for retrying — see `cli.js` → `registerWithRetry`.
- *
- * @param {RegisterClientParams} params
- * @returns {Promise<{ client: ProxyClientSummary }>}
- */
-export async function registerClient({ serverUrl, id, name, baseUrl, token }) {
-  const response = await fetch(buildRegistryUrl(serverUrl, "api/proxy-clients/register"), {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "x-proxy-token": token
-    },
-    body: JSON.stringify({ id, name, baseUrl })
-  });
-
-  if (!response.ok) {
-    const bodyText = await response.text();
-    throw new Error(`Registration failed (${response.status}): ${bodyText}`);
-  }
-
-  return response.json();
-}
+/**
+ * @file HTTP client for the registry server API.
+ *
+ * Handles proxy registration with the registry server.
+ * The auth token is sent as the `x-proxy-token` request header.
+ *
+ * Liveness is tracked via the WebSocket tunnel connection — no heartbeat
+ * HTTP polling is needed.  The proxy re-registers on every tunnel reconnect
+ * so the server's in-memory store stays consistent after restarts.
+ */
+
+/**
+ * Parameters required to register this proxy with the registry server.
+ *
+ * @typedef {Object} RegisterClientParams
+ * @property {string} serverUrl - Base URL of the registry server (e.g. "http://my-server:8080").
+ * @property {string} id        - Stable unique identifier for this proxy instance.
+ * @property {string} name      - Human-readable display name shown in the server UI.
+ * @property {string} baseUrl   - Publicly reachable base URL of this proxy's HTTP server.
+ * @property {string} token     - Auth token sent as the `x-proxy-token` header.
+ */
+
+/**
+ * The summary record returned by the server after a successful registration.
+ *
+ * @typedef {Object} ProxyClientSummary
+ * @property {string} id         - Stable unique identifier.
+ * @property {string} name       - Display name.
+ * @property {string} baseUrl    - Advertised base URL.
+ * @property {string} createdAt  - ISO timestamp of first registration.
+ * @property {string} lastSeenAt - ISO timestamp of this registration.
+ */
+
+/**
+ * Build a full URL to a registry API endpoint.
+ *
+ * @param {string} serverUrl - Base URL of the registry server.
+ * @param {string} pathname  - Relative path (e.g. "api/proxy-clients/register").
+ * @returns {URL}
+ */
+function buildRegistryUrl(serverUrl, pathname) {
+  return new URL(pathname, ensureBaseUrl(serverUrl));
+}
+
+/**
+ * Ensure the server URL ends with a trailing slash so that relative
+ * paths in `new URL(pathname, base)` resolve correctly.
+ *
+ * @param {string} serverUrl
+ * @returns {string}
+ */
+function ensureBaseUrl(serverUrl) {
+  return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
+}
+
+/**
+ * Register this proxy with the registry server.
+ *
+ * Throws if the server responds with a non-2xx status.  The caller is
+ * responsible for retrying — see `cli.js` → `registerWithRetry`.
+ *
+ * @param {RegisterClientParams} params
+ * @returns {Promise<{ client: ProxyClientSummary }>}
+ */
+export async function registerClient({ serverUrl, id, name, baseUrl, token }) {
+  const response = await fetch(buildRegistryUrl(serverUrl, "api/proxy-clients/register"), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-proxy-token": token
+    },
+    body: JSON.stringify({ id, name, baseUrl })
+  });
+
+  if (!response.ok) {
+    const bodyText = await response.text();
+    throw new Error(`Registration failed (${response.status}): ${bodyText}`);
+  }
+
+  return response.json();
+}