@torrent-tv/proxy 2.2.0 → 2.4.0

package/services/data-channel-handler.js

@@ -0,0 +1,226 @@
+/**
+ * @file WebRTC data channel request handler (proxy side).
+ *
+ * When a browser opens a data channel to this proxy, this handler wires up
+ * message handlers that implement an HTTP-over-DataChannel protocol:
+ * each incoming `request` message triggers a local `fetch` to the Fastify
+ * server, and the response is streamed back as base64-encoded chunks.
+ *
+ * ## Wire protocol
+ *
+ * Browser → Proxy
+ * ```
+ * { type: "request",  requestId, method, path, query, headers, body }
+ * { type: "ping",     id }
+ * ```
+ *
+ * Proxy → Browser
+ * ```
+ * { type: "response-start", requestId, status, headers }
+ * { type: "response-chunk", requestId, data: string (base64), done: boolean }
+ * { type: "response-error", requestId, error: string }
+ * { type: "pong",           id }
+ * ```
+ *
+ * The protocol mirrors the tunnel relay protocol so both transports share
+ * the same mental model and the same browser-side `WebRtcProxy` implementation.
+ */
+
+/** @import { DataChannel } from 'node-datachannel' */
+
+/**
+ * Configuration for the data channel handler.
+ *
+ * @typedef {Object} DataChannelHandlerOptions
+ * @property {number} proxyPort
+ *   Local port the proxy's Fastify HTTP server is listening on.
+ *   Incoming requests are forwarded to `http://127.0.0.1:{proxyPort}`.
+ * @property {(message: string) => void} [onLog]
+ *   Optional log sink.
+ */
+
+/**
+ * An incoming request message received over the data channel.
+ *
+ * @typedef {Object} DataChannelRequest
+ * @property {string}  requestId
+ * @property {string}  method    - HTTP method (GET, POST, …).
+ * @property {string}  path      - Request path (e.g. "/api/sources").
+ * @property {string}  query     - Raw query string without the leading "?".
+ * @property {Record<string, string>} headers - Headers to forward.
+ * @property {string | null} body - Request body string, or null.
+ */
+
+/**
+ * The object returned by {@link createDataChannelHandler}.
+ *
+ * @typedef {Object} DataChannelHandler
+ * @property {(sessionId: string, channel: DataChannel) => void} handleChannel
+ *   Wire message handlers onto a freshly opened data channel.
+ */
+
+/**
+ * Create a handler for incoming WebRTC data channels.
+ *
+ * @param {DataChannelHandlerOptions} options
+ * @returns {DataChannelHandler}
+ */
+export function createDataChannelHandler({ proxyPort, onLog }) {
+  /**
+   * @param {string} message
+   * @returns {void}
+   */
+  function log(message) {
+    if (typeof onLog === "function") {
+      onLog(message);
+    }
+  }
+
+  /**
+   * Wire up the `onMessage`, `onClosed`, and `onError` handlers for a channel.
+   *
+   * @param {string}      sessionId
+   * @param {DataChannel} channel
+   * @returns {void}
+   */
+  function handleChannel(sessionId, channel) {
+    log(`[dc] Session ${sessionId.slice(0, 8)}: channel open`);
+
+    channel.onMessage((raw) => {
+      /** @type {DataChannelRequest | { type: "ping", id: string }} */
+      let message;
+      try {
+        message = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+      } catch {
+        return;
+      }
+
+      if (message.type === "request") {
+        void handleRequest(channel, message).catch((error) => {
+          log(`[dc] Session ${sessionId.slice(0, 8)}: request error: ${error?.message ?? error}`);
+        });
+        return;
+      }
+
+      if (message.type === "ping") {
+        send(channel, { type: "pong", id: message.id });
+      }
+    });
+
+    channel.onClosed(() => {
+      log(`[dc] Session ${sessionId.slice(0, 8)}: channel closed`);
+    });
+
+    channel.onError((err) => {
+      log(`[dc] Session ${sessionId.slice(0, 8)}: channel error: ${err}`);
+    });
+  }
+
+  /**
+   * Fetch a resource from the local proxy HTTP server and stream the response
+   * back to the browser over the data channel.
+   *
+   * The `Host` header is rewritten to `127.0.0.1:{proxyPort}` so that Fastify
+   * routes the request correctly regardless of what the browser sent.
+   *
+   * @param {DataChannel}        channel
+   * @param {DataChannelRequest} req
+   * @returns {Promise<void>}
+   */
+  async function handleRequest(channel, req) {
+    const { requestId, method, path, query, headers: forwardedHeaders, body } = req;
+
+    // Reject paths that are not absolute, contain traversal sequences, or
+    // do not start with a known proxy route prefix.  All valid browser-side
+    // requests use /api/*, /stream, /transcode/*, /health, or /healthz.
+    if (
+      typeof path !== "string" ||
+      !path.startsWith("/") ||
+      path.includes("..") ||
+      !PATH_ALLOWLIST_RE.test(path)
+    ) {
+      send(channel, { type: "response-error", requestId, error: "Invalid request path." });
+      return;
+    }
+
+    // Reject unreasonably large JSON bodies (legitimate API calls are small).
+    const MAX_BODY_BYTES = 64 * 1024; // 64 KB
+    if (body != null && typeof body === "string" && body.length > MAX_BODY_BYTES) {
+      send(channel, { type: "response-error", requestId, error: "Request body too large." });
+      return;
+    }
+
+    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) {
+      send(channel, { type: "response-error", requestId, error: fetchError?.message ?? String(fetchError) });
+      return;
+    }
+
+    /** @type {Record<string, string>} */
+    const responseHeaders = {};
+    for (const [name, value] of response.headers.entries()) {
+      responseHeaders[name] = value;
+    }
+
+    send(channel, { type: "response-start", requestId, status: response.status, headers: responseHeaders });
+
+    if (!response.body) {
+      send(channel, { 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(channel, { type: "response-chunk", requestId, data: "", done: true });
+          break;
+        }
+        send(channel, {
+          type: "response-chunk",
+          requestId,
+          data: Buffer.from(value).toString("base64"),
+          done: false
+        });
+      }
+    } catch {
+      send(channel, { type: "response-chunk", requestId, data: "", done: true });
+    }
+  }
+
+  /**
+   * Serialise `message` to JSON and send it over the data channel.
+   * Errors are silently swallowed — the channel may have closed between
+   * the open check and the actual send.
+   *
+   * @param {DataChannel} channel
+   * @param {object}      message
+   * @returns {void}
+   */
+  function send(channel, message) {
+    try {
+      channel.sendMessage(JSON.stringify(message));
+    } catch {
+      // Channel closed between check and send — safe to ignore.
+    }
+  }
+
+  return { handleChannel };
+}
+
+/**
+ * Allowed path prefixes for data-channel requests.
+ * Only the known proxy API and streaming routes are accepted.
+ */
+const PATH_ALLOWLIST_RE = /^(?:\/api\/|\/stream(?:$|\?)|\/?transcode\/|\/health(?:z)?(?:$|\?))/;

package/services/health-collector.js

@@ -0,0 +1,48 @@
+/**
+ * @file System health metrics for proxy scoring.
+ *
+ * Collects lightweight OS-level metrics that allow the registry server to
+ * score and rank proxy clients when a browser requests playback.
+ * All values are cheap to read and require no background work.
+ */
+
+import os from "node:os";
+
+/**
+ * Snapshot of system health at a point in time.
+ *
+ * `cpuLoad`  — 1-minute load average divided by the number of logical CPUs.
+ *   0 means idle, 1 means fully utilised, >1 means overloaded.
+ *   Suitable as input to `Math.max(0, 1 - Math.min(1, cpuLoad))` for a
+ *   normalised "CPU availability" score.
+ *
+ * `memFree`  — fraction of total system RAM that is currently free (0–1).
+ *
+ * `uptime`   — process uptime in whole seconds (useful for preferring
+ *   already-warmed proxies over freshly started ones).
+ *
+ * @typedef {Object} HealthMetrics
+ * @property {number} cpuLoad - 1-min load avg / cpu-count.  0 = idle, 1 = saturated, >1 = overloaded.
+ * @property {number} memFree - Free RAM as a fraction of total RAM (0–1).
+ * @property {number} uptime  - Process uptime in seconds.
+ */
+
+/**
+ * Collect current system health metrics.
+ *
+ * All three values are rounded to three decimal places to avoid unnecessary
+ * diff noise when serialising to JSON across the tunnel.
+ *
+ * @returns {HealthMetrics}
+ */
+export function collectHealthMetrics() {
+  const cpuCount = os.cpus().length || 1;
+  const cpuLoad = os.loadavg()[0] / cpuCount;
+  const memFree = os.freemem() / os.totalmem();
+
+  return {
+    cpuLoad: Math.round(cpuLoad * 1000) / 1000,
+    memFree: Math.round(memFree * 1000) / 1000,
+    uptime: Math.floor(process.uptime())
+  };
+}

package/services/registry-api.js

@@ -1,8 +1,34 @@
 /**
  * @file HTTP client for the registry server API.
  *
- * Handles proxy registration and periodic heartbeat requests.
+ * 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.
  */
 
 /**
@@ -27,21 +53,14 @@ function ensureBaseUrl(serverUrl) {
   return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
 }
 
-/**
- * @typedef {Object} RegisterClientParams
- * @property {string} serverUrl - Base URL of the registry server.
- * @property {string} id        - Stable unique identifier for this proxy.
- * @property {string} name      - Human-readable display name.
- * @property {string} baseUrl   - Publicly reachable base URL of this proxy.
- * @property {string} token     - Auth token sent as `x-proxy-token`.
- */
-
 /**
  * Register this proxy with the registry server.
- * Throws if the server responds with a non-2xx status.
+ *
+ * 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: { id: string, name: string, baseUrl: string, createdAt: string, lastSeenAt: string } }>}
+ * @returns {Promise<{ client: ProxyClientSummary }>}
  */
 export async function registerClient({ serverUrl, id, name, baseUrl, token }) {
   const response = await fetch(buildRegistryUrl(serverUrl, "api/proxy-clients/register"), {
@@ -60,34 +79,3 @@ export async function registerClient({ serverUrl, id, name, baseUrl, token }) {
 
   return response.json();
 }
-
-/**
- * @typedef {Object} SendHeartbeatParams
- * @property {string} serverUrl - Base URL of the registry server.
- * @property {string} id        - Proxy ID to refresh.
- * @property {string} token     - Auth token sent as `x-proxy-token`.
- */
-
-/**
- * Send a heartbeat to the registry server to refresh `lastSeenAt`.
- * Returns the HTTP status code, or `null` if the request failed entirely
- * (e.g. network error).
- *
- * @param {SendHeartbeatParams} params
- * @returns {Promise<number | null>}
- */
-export async function sendHeartbeat({ serverUrl, id, token }) {
-  try {
-    const response = await fetch(buildRegistryUrl(serverUrl, "api/proxy-clients/heartbeat"), {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-proxy-token": token
-      },
-      body: JSON.stringify({ id })
-    });
-    return response.status;
-  } catch (_error) {
-    return null;
-  }
-}

package/services/tunnel-client.js

@@ -1,28 +1,75 @@
 /**
  * @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.
+ * The proxy opens one persistent connection on startup.  Through it the
+ * server can:
+ *   - relay browser HTTP requests to the proxy's local Fastify server, and
+ *   - forward WebRTC signalling messages (offers, ICE candidates) between
+ *     the browser and the proxy's WebRTC manager.
+ *
+ * The tunnel reconnects automatically with a fixed back-off after any
+ * unexpected close.
  */
 
+/** @import { HealthMetrics } from './health-collector.js' */
+
 /**
+ * Configuration for the tunnel client.
+ *
  * @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.
+ * @property {string}  serverUrl
+ *   Base URL of the registry server (http or https — converted to ws/wss automatically).
+ * @property {string}  proxyId
+ *   Stable ID used to identify this proxy on the server.
+ * @property {string}  token
+ *   Auth token sent as the `x-proxy-id` / `x-proxy-token` headers during the WS handshake.
+ * @property {number}  proxyPort
+ *   Local port the proxy's Fastify server is listening on.
+ * @property {(sessionId: string, signal: WebRtcSignal) => void} [onSignal]
+ *   Called when the server forwards a WebRTC signal (SDP offer or ICE candidate)
+ *   from a browser to this proxy.  `sessionId` scopes the signal to a P2P session.
+ * @property {() => void} [onConnect]
+ *   Called each time the WebSocket connection becomes open (including reconnects).
+ *   Use to re-register the proxy so the server's in-memory store stays consistent
+ *   after server restarts.
+ * @property {() => HealthMetrics} [onHealthRequest]
+ *   Called when the server sends a `health-request` message.  The return value is
+ *   sent back as `health-response` and used by the server to score this proxy.
+ * @property {(message: string) => void} [onLog]
+ *   Optional structured log sink.
+ */
+
+/**
+ * A single WebRTC signal message forwarded through the tunnel.
+ *
+ * @typedef {Object} WebRtcSignal
+ * @property {string}  type       - Signal kind: "offer" | "answer" | "candidate".
+ * @property {string}  [sdp]      - SDP string (for "offer" and "answer").
+ * @property {string}  [candidate] - ICE candidate string (for "candidate").
+ * @property {string}  [mid]      - SDP media ID associated with the candidate.
  */
 
 /**
+ * A relay request sent by the server — asking the proxy to perform a local
+ * HTTP fetch and stream the response back through the tunnel.
+ *
  * @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 {string} requestId - Unique ID that ties request → response chunks.
+ * @property {string} method    - HTTP method (GET, POST, etc.).
+ * @property {string} path      - Request path on the local proxy (e.g. "/health").
+ * @property {string} query     - Raw 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.
+ * @property {string | null} body - Serialised request body, or null.
+ */
+
+/**
+ * The object returned by {@link createTunnelClient}.
+ *
+ * @typedef {Object} TunnelClient
+ * @property {() => void}   connect      - Open the tunnel; reconnects on drop.
+ * @property {() => void}   disconnect   - Close the tunnel; suppresses reconnects.
+ * @property {(sessionId: string, signal: WebRtcSignal) => void} sendSignal
+ *   Send a WebRTC signal (answer / candidate) back to the browser.
  */
 
 const RECONNECT_DELAY_MS = 5_000;
@@ -31,9 +78,9 @@ 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 }}
+ * @returns {TunnelClient}
  */
-export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog }) {
+export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onSignal, onConnect, onHealthRequest, onLog }) {
   const wsUrl = serverUrl.replace(/^http/, "ws").replace(/\/+$/, "") + "/ws/proxy-tunnel";
 
   /** @type {WebSocket | null} */
@@ -43,7 +90,7 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
   let stopped = false;
 
   /**
-   * Emit a log message via the provided callback.
+   * Write a message to the log sink if one was provided.
    *
    * @param {string} message
    * @returns {void}
@@ -56,7 +103,7 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
 
   /**
    * Open a new WebSocket connection to the server.
-   * Automatically reconnects on close unless {@link disconnect} was called.
+   * Automatically schedules a reconnect after any unintentional close.
    *
    * @returns {void}
    */
@@ -75,6 +122,9 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
 
     socket.addEventListener("open", () => {
       log("Tunnel connected.");
+      if (typeof onConnect === "function") {
+        onConnect();
+      }
     });
 
     socket.addEventListener("message", (event) => {
@@ -84,10 +134,27 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
       } catch {
         return;
       }
+
       if (message.type === "request") {
         void handleRelayRequest(message).catch((error) => {
           log(`Tunnel relay error: ${error?.message ?? error}`);
         });
+        return;
+      }
+
+      // WebRTC signalling: server forwards a signal from a browser session.
+      if (message.type === "signal") {
+        if (typeof message.sessionId === "string" && message.signal && typeof onSignal === "function") {
+          onSignal(message.sessionId, message.signal);
+        }
+        return;
+      }
+
+      // Health check: server requests current metrics for proxy scoring.
+      if (message.type === "health-request") {
+        const metrics = typeof onHealthRequest === "function" ? onHealthRequest() : {};
+        send({ type: "health-response", requestId: message.requestId, metrics });
+        return;
       }
     });
 
@@ -105,8 +172,8 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
   }
 
   /**
-   * Execute a relay request sent by the server: fetch the resource
-   * from the local proxy and stream the response back chunk-by-chunk.
+   * Fetch a resource from the local Fastify server and stream the response
+   * back to the registry server chunk-by-chunk over the WebSocket.
    *
    * @param {TunnelRelayRequest} relayRequest
    * @returns {Promise<void>}
@@ -129,17 +196,13 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
       return;
     }
 
+    /** @type {Record<string, string>} */
     const responseHeaders = {};
     for (const [headerName, headerValue] of response.headers.entries()) {
       responseHeaders[headerName] = headerValue;
     }
 
-    send({
-      type: "response-start",
-      requestId,
-      status: response.status,
-      headers: responseHeaders
-    });
+    send({ type: "response-start", requestId, status: response.status, headers: responseHeaders });
 
     if (!response.body) {
       send({ type: "response-chunk", requestId, data: "", done: true });
@@ -167,7 +230,7 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
   }
 
   /**
-   * Send a JSON message through the WebSocket if it is open.
+   * Serialise a message to JSON and send it through the WebSocket if open.
    *
    * @param {object} message
    * @returns {void}
@@ -179,7 +242,7 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
   }
 
   /**
-   * Send a `response-error` message back to the server for the given request.
+   * Send a `response-error` frame for a given relay request.
    *
    * @param {string} requestId
    * @param {string} errorMessage
@@ -191,7 +254,7 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
 
   return {
     /**
-     * Start the tunnel, connecting immediately and reconnecting on drop.
+     * Start the tunnel.  Connects immediately and auto-reconnects on drop.
      *
      * @returns {void}
      */
@@ -201,7 +264,8 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
     },
 
     /**
-     * Stop the tunnel and close the current connection without reconnecting.
+     * Tear down the tunnel.  Closes the current connection and prevents
+     * any future reconnect attempts.
      *
      * @returns {void}
      */
@@ -215,6 +279,18 @@ export function createTunnelClient({ serverUrl, proxyId, token, proxyPort, onLog
         socket.close(1000, "shutdown");
         socket = null;
       }
+    },
+
+    /**
+     * Forward a WebRTC signal (SDP answer or ICE candidate) from this proxy
+     * to the browser via the server tunnel.
+     *
+     * @param {string} sessionId   - Scopes the signal to a single P2P session.
+     * @param {WebRtcSignal} signal
+     * @returns {void}
+     */
+    sendSignal(sessionId, signal) {
+      send({ type: "signal", sessionId, signal });
     }
   };
 }