@torrent-tv/proxy 2.0.1 → 2.2.0

package/services/torrent-pool.js

@@ -1,7 +1,22 @@
+/**
+ * @file WebTorrent client pool.
+ *
+ * Manages a shared WebTorrent client instance and a map of active torrents
+ * keyed by a hash of their source. Tracks file-level usage so that only
+ * the pieces needed by active streams are selected for download.
+ */
+
 import crypto from "node:crypto";
-import chalk from "chalk";
 import WebTorrent from "webtorrent";
+import { logger } from "../utils/logger.js";
 
+/**
+ * Decode a raw torrent source value into the format expected by WebTorrent.
+ *
+ * @param {"magnet" | "torrent"} sourceType - How the source is encoded.
+ * @param {string} source                   - Magnet URI or base64-encoded .torrent file.
+ * @returns {string | Buffer}
+ */
 function decodeTorrentSource(sourceType, source) {
   if (sourceType === "magnet") {
     return source;
@@ -12,17 +27,47 @@ function decodeTorrentSource(sourceType, source) {
   throw new Error("Unsupported sourceType. Expected magnet or torrent.");
 }
 
+/**
+ * Shared WebTorrent pool.
+ *
+ * Torrents are loaded on demand and cached indefinitely (the pool has no
+ * eviction policy — callers are responsible for keeping the set small).
+ * File-level piece selection is tracked through a reference-count map so
+ * that only files with at least one active stream cause downloading.
+ */
 export class TorrentPool {
   constructor() {
+    /** @type {import("webtorrent").WebTorrent} */
     this.client = new WebTorrent();
+
+    /**
+     * Active torrents keyed by `"${sourceType}:${sha1(source)}"`.
+     *
+     * @type {Map<string, import("webtorrent").Torrent>}
+     */
     this.torrents = new Map();
+
+    /**
+     * Per-torrent file usage reference counts.
+     * Maps torrent object → (fileIndex → refCount).
+     *
+     * @type {WeakMap<import("webtorrent").Torrent, Map<number, number>>}
+     */
     this.fileUsageByTorrent = new WeakMap();
 
     this.client.on("error", (error) => {
-      console.error(chalk.red(`[proxy-client] WebTorrent client error: ${error.message}`));
+      logger.error(`WebTorrent client error: ${error.message}`);
     });
   }
 
+  /**
+   * Return the torrent for the given source, loading it if necessary.
+   * Resolves once the torrent metadata is ready.
+   *
+   * @param {"magnet" | "torrent"} sourceType
+   * @param {string} source - Magnet URI or base64-encoded .torrent bytes.
+   * @returns {Promise<import("webtorrent").Torrent>}
+   */
   async getTorrent(sourceType, source) {
     const key = `${sourceType}:${crypto.createHash("sha1").update(source).digest("hex")}`;
     const existing = this.torrents.get(key);
@@ -47,6 +92,14 @@ export class TorrentPool {
     return torrent;
   }
 
+  /**
+   * Mark a single file as active, deselecting all others.
+   * Prefer {@link acquireFile} when the active set may contain multiple files.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {number} fileIndex - Zero-based index into `torrent.files`.
+   * @returns {void}
+   */
   setActiveFile(torrent, fileIndex) {
     if (!torrent || !Array.isArray(torrent.files)) {
       return;
@@ -68,6 +121,15 @@ export class TorrentPool {
     }
   }
 
+  /**
+   * Increment the reference count for a file, selecting it for download.
+   * Returns a release function that decrements the count; when it reaches
+   * zero the file is automatically deselected.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {number} fileIndex - Zero-based index into `torrent.files`.
+   * @returns {() => void} Release function — call it once when done streaming.
+   */
   acquireFile(torrent, fileIndex) {
     if (!torrent || !Array.isArray(torrent.files) || !Number.isInteger(fileIndex) || fileIndex < 0) {
       return () => undefined;
@@ -99,6 +161,14 @@ export class TorrentPool {
     };
   }
 
+  /**
+   * Update WebTorrent piece selection to match the current usage map.
+   * Files with at least one consumer are selected; all others are deselected.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {Map<number, number>} usage - fileIndex → refCount.
+   * @returns {void}
+   */
   #syncSelections(torrent, usage) {
     if (!torrent || !Array.isArray(torrent.files)) {
       return;

package/services/tunnel-client.js

@@ -0,0 +1,220 @@
+/**
+ * @file Outbound WebSocket tunnel from the proxy to the registry server.
+ *
+ * The proxy establishes one persistent connection on startup.
+ * The server sends relay requests through it; the proxy fetches them
+ * locally (against 127.0.0.1) and streams responses back chunk-by-chunk.
+ */
+
+/**
+ * @typedef {Object} TunnelClientOptions
+ * @property {string} serverUrl   - Base URL of the registry server (http/https).
+ * @property {string} proxyId     - Stable ID used to identify this proxy on the server.
+ * @property {string} token       - Auth token sent as a header during the WS handshake.
+ * @property {number} proxyPort   - Local port the proxy HTTP server is listening on.
+ * @property {(message: string) => void} [onLog] - Optional log callback.
+ */
+
+/**
+ * @typedef {Object} TunnelRelayRequest
+ * @property {string} requestId - Unique ID assigned by the server for this relay round-trip.
+ * @property {string} method    - HTTP method to use when calling the local proxy.
+ * @property {string} path      - Request path (e.g. "/health").
+ * @property {string} query     - Query string without the leading "?".
+ * @property {Record<string, string>} headers - Headers forwarded from the browser.
+ * @property {string | null} body - Serialised JSON body, or null for GET.
+ */
+
+const RECONNECT_DELAY_MS = 5_000;
+
+/**
+ * Create and manage the outbound WebSocket tunnel to the registry server.
+ *
+ * @param {TunnelClientOptions} options
+ * @returns {{ connect: () => void, disconnect: () => void }}
+ */
+export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog }) {
+  const wsUrl = serverUrl.replace(/^http/, "ws").replace(/\/+$/, "") + "/ws/proxy-tunnel";
+
+  /** @type {WebSocket | null} */
+  let socket = null;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let reconnectTimer = null;
+  let stopped = false;
+
+  /**
+   * Emit a log message via the provided callback.
+   *
+   * @param {string} message
+   * @returns {void}
+   */
+  function log(message) {
+    if (typeof onLog === "function") {
+      onLog(message);
+    }
+  }
+
+  /**
+   * Open a new WebSocket connection to the server.
+   * Automatically reconnects on close unless {@link disconnect} was called.
+   *
+   * @returns {void}
+   */
+  function connect() {
+    if (stopped) {
+      return;
+    }
+    log(`Connecting tunnel to ${wsUrl}`);
+
+    socket = new WebSocket(wsUrl, {
+      headers: {
+        "x-proxy-id": proxyId,
+        "x-proxy-token": token
+      }
+    });
+
+    socket.addEventListener("open", () => {
+      log("Tunnel connected.");
+    });
+
+    socket.addEventListener("message", (event) => {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      if (message.type === "request") {
+        void handleRelayRequest(message).catch((error) => {
+          log(`Tunnel relay error: ${error?.message ?? error}`);
+        });
+      }
+    });
+
+    socket.addEventListener("close", (event) => {
+      log(`Tunnel disconnected (code=${event.code}). Reconnecting in ${RECONNECT_DELAY_MS}ms...`);
+      socket = null;
+      if (!stopped) {
+        reconnectTimer = setTimeout(connect, RECONNECT_DELAY_MS);
+      }
+    });
+
+    socket.addEventListener("error", (event) => {
+      log(`Tunnel WebSocket error: ${event.message ?? "unknown"}`);
+    });
+  }
+
+  /**
+   * Execute a relay request sent by the server: fetch the resource
+   * from the local proxy and stream the response back chunk-by-chunk.
+   *
+   * @param {TunnelRelayRequest} relayRequest
+   * @returns {Promise<void>}
+   */
+  async function handleRelayRequest(relayRequest) {
+    const { requestId, method, path, query, headers: forwardedHeaders, body } = relayRequest;
+    const targetUrl = `http://127.0.0.1:${proxyPort}${path}` + (query ? `?${query}` : "");
+    const requestHeaders = { ...(forwardedHeaders ?? {}), host: `127.0.0.1:${proxyPort}` };
+
+    let response;
+    try {
+      response = await fetch(targetUrl, {
+        method,
+        headers: requestHeaders,
+        body: body != null ? body : undefined,
+        redirect: "manual"
+      });
+    } catch (fetchError) {
+      sendError(requestId, fetchError?.message ?? String(fetchError));
+      return;
+    }
+
+    const responseHeaders = {};
+    for (const [headerName, headerValue] of response.headers.entries()) {
+      responseHeaders[headerName] = headerValue;
+    }
+
+    send({
+      type: "response-start",
+      requestId,
+      status: response.status,
+      headers: responseHeaders
+    });
+
+    if (!response.body) {
+      send({ type: "response-chunk", requestId, data: "", done: true });
+      return;
+    }
+
+    try {
+      const reader = response.body.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          send({ type: "response-chunk", requestId, data: "", done: true });
+          break;
+        }
+        send({
+          type: "response-chunk",
+          requestId,
+          data: Buffer.from(value).toString("base64"),
+          done: false
+        });
+      }
+    } catch {
+      send({ type: "response-chunk", requestId, data: "", done: true });
+    }
+  }
+
+  /**
+   * Send a JSON message through the WebSocket if it is open.
+   *
+   * @param {object} message
+   * @returns {void}
+   */
+  function send(message) {
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify(message));
+    }
+  }
+
+  /**
+   * Send a `response-error` message back to the server for the given request.
+   *
+   * @param {string} requestId
+   * @param {string} errorMessage
+   * @returns {void}
+   */
+  function sendError(requestId, errorMessage) {
+    send({ type: "response-error", requestId, error: errorMessage });
+  }
+
+  return {
+    /**
+     * Start the tunnel, connecting immediately and reconnecting on drop.
+     *
+     * @returns {void}
+     */
+    connect() {
+      stopped = false;
+      connect();
+    },
+
+    /**
+     * Stop the tunnel and close the current connection without reconnecting.
+     *
+     * @returns {void}
+     */
+    disconnect() {
+      stopped = true;
+      if (reconnectTimer != null) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+      }
+      if (socket) {
+        socket.close(1000, "shutdown");
+        socket = null;
+      }
+    }
+  };
+}

package/store/source-registry.js

@@ -1,9 +1,42 @@
+/**
+ * @file In-memory registry of torrent sources.
+ *
+ * Sources are stored under a SHA-1 key derived from their type and content.
+ * The registry is bounded: when `maxSources` is exceeded, the oldest entries
+ * are evicted to keep memory usage predictable.
+ */
+
 import crypto from "node:crypto";
 
+/**
+ * @typedef {Object} SourceRecord
+ * @property {"magnet" | "torrent"} sourceType - Encoding of the `source` field.
+ * @property {string} source      - Magnet URI or base64-encoded .torrent bytes.
+ * @property {number} updatedAt   - Unix ms timestamp of the last upsert.
+ */
+
+/**
+ * Create a bounded in-memory source registry.
+ *
+ * @param {number} [maxSources=200] - Maximum number of entries to retain.
+ * @returns {{
+ *   upsert: (sourceType: string, source: string) => string,
+ *   get:    (sourceKey: string) => SourceRecord | null
+ * }}
+ */
 export function createSourceRegistry(maxSources = 200) {
+  /** @type {Map<string, SourceRecord>} */
   const sources = new Map();
 
   return {
+    /**
+     * Insert or refresh a source entry and return its key.
+     * Evicts the oldest entries if the map exceeds `maxSources`.
+     *
+     * @param {string} sourceType
+     * @param {string} source
+     * @returns {string} Stable SHA-1 hex key for this source.
+     */
     upsert(sourceType, source) {
       const sourceKey = crypto
         .createHash("sha1")
@@ -25,6 +58,14 @@ export function createSourceRegistry(maxSources = 200) {
 
       return sourceKey;
     },
+
+    /**
+     * Look up a source by its key.
+     * Returns `null` if the key is not registered.
+     *
+     * @param {string} sourceKey
+     * @returns {SourceRecord | null}
+     */
     get(sourceKey) {
       return sources.get(sourceKey) ?? null;
     }

package/utils/logger.js

@@ -0,0 +1,30 @@
+/**
+ * @file Centralised console logger for the proxy process.
+ *
+ * All messages are prefixed with `[proxy-client]` and coloured with chalk
+ * for consistent, readable terminal output.
+ */
+
+import chalk from "chalk";
+
+const PREFIX = "[proxy-client]";
+
+/**
+ * @typedef {Object} ProxyLogger
+ * @property {(message: string) => void} info    - Informational message (cyan).
+ * @property {(message: string) => void} success - Positive outcome (green).
+ * @property {(message: string) => void} warn    - Non-fatal warning (yellow).
+ * @property {(message: string) => void} error   - Error condition (red).
+ */
+
+/**
+ * Shared logger instance used throughout the proxy process.
+ *
+ * @type {ProxyLogger}
+ */
+export const logger = {
+  info:    (message) => console.log(chalk.cyan(`${PREFIX} ${message}`)),
+  success: (message) => console.log(chalk.green(`${PREFIX} ${message}`)),
+  warn:    (message) => console.warn(chalk.yellow(`${PREFIX} ${message}`)),
+  error:   (message) => console.error(chalk.red(`${PREFIX} ${message}`)),
+};

package/utils/parse-range.js

@@ -1,3 +1,16 @@
+/**
+ * @file HTTP Range header parser.
+ */
+
+/**
+ * Parse an HTTP `Range` header value into a byte range clamped to the file size.
+ * Only the `bytes=<start>-<end>` form is supported.
+ *
+ * @param {string | undefined} rangeHeader - Value of the `Range` request header.
+ * @param {number} fileLength              - Total file size in bytes.
+ * @returns {{ start: number, end: number } | null} Byte range, or `null` if the
+ *   header is absent, malformed, or uses an unsupported unit.
+ */
 export function parseRange(rangeHeader, fileLength) {
   if (!rangeHeader || !rangeHeader.startsWith("bytes=")) {
     return null;