@torrent-tv/proxy 2.0.1 → 2.1.0

package/bin/cli.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
-import chalk from "chalk";
+/**
+ * @file CLI entry point for the torrent-tv proxy.
+ *
+ * Parses command-line arguments, starts the local HTTP server, registers
+ * this proxy with the registry server, establishes the WebSocket tunnel,
+ * and maintains a periodic heartbeat.
+ */
+
 import { Command } from "commander";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import ffmpegStatic from "ffmpeg-static";
 import { startProxyServer } from "../server.js";
 import { registerClient, sendHeartbeat } from "../services/registry-api.js";
+import { createTunnelClient } from "../services/tunnel-client.js";
+import { logger } from "../utils/logger.js";
 
 const program = new Command();
 
@@ -45,7 +54,7 @@ const options = program.opts();
 
 const localPort = Number(options.port);
 if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
-  console.error(chalk.red("[proxy-client] Invalid --port value."));
+  logger.error("Invalid --port value.");
   process.exit(1);
 }
 
@@ -61,6 +70,12 @@ const transcodeAudio = options.transcodeAudio !== false;
 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",
@@ -78,12 +93,30 @@ function assertFfmpegAvailability() {
   }
 }
 
+/** @type {boolean} */
 let registrationInProgress = false;
+
+/** @type {ReturnType<typeof setInterval> | null} */
 let heartbeatTimer = null;
+
+/** @type {import("fastify").FastifyInstance | null} */
 let app = null;
+
+/** @type {number} */
 let actualPort = localPort;
+
+/** @type {boolean} */
 let shutdownInProgress = false;
 
+/** @type {ReturnType<typeof import("../services/tunnel-client.js").createTunnelClient> | null} */
+let tunnelClient = 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;
@@ -97,12 +130,18 @@ async function registerClientSafe() {
       baseUrl: explicitBaseUrl || `http://${bindHost}:${actualPort}`,
       token
     });
-    console.log(chalk.green(`[proxy-client] Registered: ${JSON.stringify(result.client)}`));
+    logger.success(`Registered: ${JSON.stringify(result.client)}`);
   } finally {
     registrationInProgress = false;
   }
 }
 
+/**
+ * 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;
@@ -112,7 +151,11 @@ async function shutdown(signal) {
     clearInterval(heartbeatTimer);
     heartbeatTimer = null;
   }
-  console.log(chalk.yellow(`[proxy-client] Received ${signal}, shutting down...`));
+  if (tunnelClient) {
+    tunnelClient.disconnect();
+    tunnelClient = null;
+  }
+  logger.warn(`Received ${signal}, shutting down...`);
   try {
     if (app) {
       await app.close();
@@ -120,7 +163,7 @@ async function shutdown(signal) {
     process.exit(0);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.error(chalk.red(`[proxy-client] Shutdown failed: ${message}`));
+    logger.error(`Shutdown failed: ${message}`);
     process.exit(1);
   }
 }
@@ -139,16 +182,23 @@ try {
   actualPort = started.port;
   const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
 
-  console.log(chalk.cyan(`[proxy-client] Local stream endpoint: http://${bindHost}:${actualPort}/stream`));
-  console.log(chalk.cyan(`[proxy-client] Advertised direct URL: ${directBaseUrl}`));
+  logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
+  logger.info(`Advertised direct URL: ${directBaseUrl}`);
   if (transcodeAudio) {
-    console.log(
-      chalk.cyan(`[proxy-client] Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`)
-    );
+    logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
   }
 
   await registerClientSafe();
 
+  tunnelClient = createTunnelClient({
+    serverUrl,
+    proxyId: clientId,
+    token,
+    proxyPort: actualPort,
+    onLog: (msg) => logger.info(msg)
+  });
+  tunnelClient.connect();
+
   heartbeatTimer = setInterval(async () => {
     const status = await sendHeartbeat({
       serverUrl,
@@ -156,18 +206,18 @@ try {
       token
     });
     if (status === 404) {
-      console.log(chalk.yellow("[proxy-client] Heartbeat returned 404, re-registering..."));
+      logger.warn("Heartbeat returned 404, re-registering...");
       try {
         await registerClientSafe();
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.error(chalk.red(`[proxy-client] Re-register failed: ${message}`));
+        logger.error(`Re-register failed: ${message}`);
       }
     }
   }, 20_000);
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);
-  console.error(chalk.red(`[proxy-client] ${message}`));
+  logger.error(message);
   process.exit(1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/playback-plan/post.js

@@ -1,3 +1,22 @@
+/**
+ * Determine the best playback mode (direct stream or HLS transcode) for a
+ * torrent file and return the corresponding plan.
+ *
+ * POST /api/playback-plan
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ playbackPlanner: ReturnType<import("../../../services/playback-planner.js").createPlaybackPlanner> }} deps
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
 function getPayload(body) {
   if (body && typeof body === "object" && !Array.isArray(body)) {
     return body;

package/routes/api/sources/post.js

@@ -1,3 +1,21 @@
+/**
+ * Register a torrent source with the proxy and receive a stable source key.
+ *
+ * POST /api/sources
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ sourceRegistry: ReturnType<import("../../../store/source-registry.js").createSourceRegistry> }} deps
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
 function getPayload(body) {
   if (body && typeof body === "object" && !Array.isArray(body)) {
     return body;

package/routes/api/transcode-sessions/post.js

@@ -1,3 +1,21 @@
+/**
+ * Create or return an existing HLS transcode session for a torrent file.
+ *
+ * POST /api/transcode-sessions
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
 function getPayload(body) {
   if (body && typeof body === "object" && !Array.isArray(body)) {
     return body;

package/routes/api/transcode-sessions/progress/get.js

@@ -1,3 +1,13 @@
+/**
+ * Return the current encoding progress for an active HLS transcode session.
+ *
+ * GET /api/transcode-sessions/:sessionId/progress
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
 export async function handleApiTranscodeSessionsProgressGet(req, reply, { hlsSessionManager }) {
   const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
   if (!sessionId) {

package/routes/api/transcode-sessions/release/post.js

@@ -1,3 +1,22 @@
+/**
+ * Release a consumer from a transcode session.
+ * When the last consumer is released the session is disposed automatically.
+ *
+ * POST /api/transcode-sessions/:sessionId/release
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
 function getPayload(body) {
   if (body && typeof body === "object" && !Array.isArray(body)) {
     return body;

package/routes/health/get.js

@@ -1,3 +1,12 @@
+/**
+ * Basic liveness check for load balancers and container orchestrators.
+ *
+ * GET /health
+ *
+ * @param {import("fastify").FastifyRequest} _req
+ * @param {import("fastify").FastifyReply} reply
+ * @returns {Promise<void>}
+ */
 export async function handleHealthGet(_req, reply) {
   return reply.send({ ok: true });
 }

package/routes/healthz/get.js

@@ -1,3 +1,12 @@
+/**
+ * Docker / Kubernetes readiness probe endpoint.
+ *
+ * GET /healthz
+ *
+ * @param {import("fastify").FastifyRequest} _req
+ * @param {import("fastify").FastifyReply} reply
+ * @returns {Promise<void>}
+ */
 export async function handleHealthzGet(_req, reply) {
   return reply.send({ ok: true });
 }

package/routes/stream/get.js

@@ -1,5 +1,21 @@
+/**
+ * @file Byte-range aware torrent file streaming endpoint.
+ *
+ * Accepts either a `sourceKey` (registered via POST /api/sources) or a raw
+ * `sourceType` + `source` pair.  Responds with HTTP 206 for range requests
+ * and HTTP 200 for full-file requests.
+ */
+
 import { parseRange } from "../../utils/parse-range.js";
 
+/**
+ * Resolve source parameters from the query string.
+ * Prefers a registered `sourceKey`; falls back to inline `sourceType`+`source`.
+ *
+ * @param {import("fastify").FastifyRequest["query"]} query
+ * @param {ReturnType<import("../../store/source-registry.js").createSourceRegistry>} sourceRegistry
+ * @returns {{ sourceType: string, source: string }}
+ */
 function getSourceParams(query, sourceRegistry) {
   const sourceKey = typeof query.sourceKey === "string" ? query.sourceKey : "";
   const sourceTypeFromQuery = typeof query.sourceType === "string" ? query.sourceType : "";
@@ -11,6 +27,16 @@ function getSourceParams(query, sourceRegistry) {
   return { sourceType, source };
 }
 
+/**
+ * Stream a torrent file over HTTP with byte-range support.
+ *
+ * GET /stream
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ sourceRegistry: ReturnType<import("../../store/source-registry.js").createSourceRegistry>, torrentPool: import("../../services/torrent-pool.js").TorrentPool }} deps
+ * @returns {Promise<void>}
+ */
 export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool }) {
   const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
   const fileIndex = Number(fileIndexRaw);
@@ -58,6 +84,15 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool
   return reply.send(stream);
 }
 
+/**
+ * Attach event listeners that release the file reference exactly once when
+ * the stream or the underlying HTTP connection closes.
+ *
+ * @param {import("node:stream").Readable} stream
+ * @param {import("fastify").FastifyReply} reply
+ * @param {() => void} release
+ * @returns {void}
+ */
 function bindRelease(stream, reply, release) {
   let released = false;
   const releaseOnce = () => {

package/routes/transcode/session-file/get.js

@@ -1,3 +1,16 @@
+/**
+ * Serve HLS playlist and segment files from an active transcode session.
+ *
+ * Polls until the requested file appears (up to 15 s) so that HLS clients
+ * do not receive a 404 during the ffmpeg warmup phase.
+ *
+ * GET /transcode/:sessionId/:fileName
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
 export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionManager }) {
   const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
   const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
@@ -23,6 +36,16 @@ export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionMana
   return reply.send(result.stream);
 }
 
+/**
+ * Poll `hlsSessionManager.getFileStream()` until the file is available,
+ * the session fails, or the timeout elapses.
+ *
+ * @param {import("../../../services/hls-session-manager.js").HlsSessionManager} hlsSessionManager
+ * @param {string} sessionId
+ * @param {string} fileName
+ * @param {number} timeoutMs
+ * @returns {Promise<Awaited<ReturnType<import("../../../services/hls-session-manager.js").HlsSessionManager["getFileStream"]>>>}
+ */
 async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {
@@ -35,6 +58,12 @@ async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeou
   return { kind: "warming-up" };
 }
 
+/**
+ * Resolve after a given number of milliseconds.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
 function delay(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);

package/server.js

@@ -1,3 +1,11 @@
+/**
+ * @file Proxy HTTP server bootstrap.
+ *
+ * Creates and configures the Fastify application, registers all routes and
+ * plugins, then starts listening on the first available port at or above the
+ * requested one.
+ */
+
 import Fastify from "fastify";
 import fastifyCors from "@fastify/cors";
 import fastifyHelmet from "@fastify/helmet";
@@ -23,6 +31,13 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const publicRoot = path.resolve(__dirname, "./public");
 
+/**
+ * Build a list of candidate port numbers starting at `startPort`.
+ *
+ * @param {number} startPort
+ * @param {number} [maxAttempts=51]
+ * @returns {number[]}
+ */
 function buildPortCandidates(startPort, maxAttempts = 51) {
   const ports = [];
   for (let index = 0; index < maxAttempts; index += 1) {
@@ -31,6 +46,20 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
   return ports;
 }
 
+/**
+ * @typedef {Object} ProxyServerOptions
+ * @property {string}  host           - Bind host (e.g. "127.0.0.1" or "0.0.0.0").
+ * @property {number}  port           - Preferred listen port.
+ * @property {boolean} transcodeAudio - Whether HLS audio transcoding is enabled.
+ * @property {string}  ffmpegBin      - Path to the ffmpeg executable.
+ */
+
+/**
+ * Create, configure, and start the proxy HTTP server.
+ *
+ * @param {ProxyServerOptions} options
+ * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
+ */
 export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }) {
   const app = Fastify({
     bodyLimit: 10 * 1024 * 1024