@torrent-tv/proxy 2.9.69 → 2.9.71

package/services/torrent-worker/protocol.js

@@ -0,0 +1,103 @@
+/**
+ * @file Message protocol between the main thread and the torrent worker.
+ *
+ * **Why the torrent gets its own thread.** Profiling the live proxy during a
+ * seek (2026-08-02) found the main thread ~85% busy, and busy with WebTorrent:
+ * buffer concatenation in `uint8-util` ~15%, `_updateWire` and its wrapper ~9%,
+ * garbage collection ~5% — and no piece hashing anywhere, which had been the
+ * standing assumption. Serving a segment shares that thread, so reading an
+ * already-finished 10 MB file off SSD took 12-23 s while handing it to the
+ * channel took 125 ms. Two unrelated jobs — one talking to fifty peers in small
+ * bursts, one owing a viewer a prompt answer — were queued behind each other
+ * for no reason but sharing a thread. Three of the four cores sat idle.
+ *
+ * **Why this shape, measured rather than assumed** (see the numbers below):
+ *
+ * | approach                                   | 10 MB   |
+ * |--------------------------------------------|---------|
+ * | structured clone (copying)                 | 37 ms   |
+ * | transferable `ReadableStream` (the standard)| 104 ms  |
+ * | **this: transfer inside a stream wrapper**  | **4.8 ms** |
+ * | one whole buffer, no chunking              | 0.49 ms |
+ *
+ * The standard transferable stream is the obvious choice and the wrong one: it
+ * negotiates every chunk across the boundary and costs 22x this design. Copying
+ * is worse still. So the worker transfers ownership of large buffers, and the
+ * main thread wraps the arriving buffers in an ordinary `ReadableStream` —
+ * standard interface outside, ownership transfer inside. Callers cannot tell
+ * the difference; the cost is a tenth of a percent of a segment's playing time.
+ *
+ * Chunk size follows from the same measurements: a round trip costs ~100 µs, so
+ * 64 KB chunks would spend 13 ms per segment on overhead against 0.5 ms sent
+ * whole. {@link STREAM_CHUNK_BYTES} of 1 MB puts a 10 MB segment at ten
+ * messages — about 1 ms — while still allowing a read to be cancelled promptly
+ * and keeping peak memory bounded.
+ *
+ * Torrent objects cannot cross a thread boundary, so the main thread names them
+ * by `sourceKey` (the identifier the registry already uses) and the worker owns
+ * the objects.
+ */
+
+/**
+ * Commands sent main thread → worker.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const Command = {
+  /** Add (or join) a torrent; resolves when metadata is ready. */
+  ADD_SOURCE: "add-source",
+  /** Claim a file for reading, so it is not evicted while in use. */
+  ACQUIRE_FILE: "acquire-file",
+  /** Drop a claim; the worker applies its own idle-removal policy. */
+  RELEASE_FILE: "release-file",
+  /** File list and metadata for a source. */
+  LIST_FILES: "list-files",
+  /** Live download figures for the progress display. */
+  FILE_STATS: "file-stats",
+  /** Reorder piece selection around a read position (seek prioritisation). */
+  PRIORITIZE: "prioritize",
+  /** Read a byte range; the body arrives as CHUNK messages. */
+  READ_RANGE: "read-range",
+  /** Abandon an in-flight READ_RANGE (viewer gone, seek superseded). */
+  CANCEL_READ: "cancel-read",
+  /** Pre-fetch the head and tail a codec probe needs. */
+  PREFETCH_EDGES: "prefetch-edges",
+  /** Shut the client down, optionally deleting downloaded data. */
+  DESTROY_ALL: "destroy-all"
+};
+
+/**
+ * Messages sent worker → main thread.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const Event = {
+  /** A command completed; carries its result. */
+  RESULT: "result",
+  /** A command failed; carries a message (`Error`s do not survive the boundary). */
+  ERROR: "error",
+  /** One piece of a READ_RANGE body; its bytes are transferred, never copied. */
+  CHUNK: "chunk",
+  /** A READ_RANGE ended; no further CHUNKs bear that request id. */
+  READ_END: "read-end",
+  /** The main thread consumed a chunk — see {@link STREAM_HIGH_WATER_CHUNKS}. */
+  CHUNK_ACK: "chunk-ack",
+  /** A log line, so worker output reaches the same place as everything else. */
+  LOG: "log"
+};
+
+/**
+ * Bytes per CHUNK message. See the file header for why 1 MB.
+ */
+export const STREAM_CHUNK_BYTES = 1024 * 1024;
+
+/**
+ * How many chunks may be in flight before the worker waits for an acknowledgement.
+ *
+ * Unbounded sending would let a fast disk outrun the channel and rebuild, in the
+ * message queue, exactly the memory the transfers were saving. Two in flight
+ * keeps the pipe full without letting it grow.
+ */
+export const STREAM_HIGH_WATER_CHUNKS = 2;

package/services/torrent-worker/worker.js

@@ -0,0 +1,255 @@
+/**
+ * @file The torrent thread: WebTorrent and nothing else.
+ *
+ * Everything that made the main thread unresponsive lives here now — peer
+ * connections, buffer concatenation, piece bookkeeping, garbage collection from
+ * all of it. The main thread keeps only what owes a viewer a prompt answer.
+ *
+ * This file deliberately holds no HTTP, no session logic and no knowledge of
+ * HLS: it answers the commands in `protocol.js` and streams bytes back. That
+ * boundary is what keeps the split honest — anything added here will compete
+ * with the torrent for this thread, which is exactly the problem being solved.
+ *
+ * The existing `TorrentPool` is reused wholesale rather than reimplemented. It
+ * already carries the parts that took field failures to get right — refcounted
+ * file claims, idle removal, the global disk cap with LRU eviction, seek-aware
+ * piece prioritisation, adaptive upload — and none of that changes by moving
+ * threads.
+ */
+
+import { parentPort, workerData } from "node:worker_threads";
+import { TorrentPool } from "../torrent-pool.js";
+import { createSendStream } from "./channel.js";
+import { Command, Event, STREAM_CHUNK_BYTES } from "./protocol.js";
+
+const pool = new TorrentPool({ maxDiskBytes: workerData?.maxDiskBytes });
+
+/** Torrents by sourceKey — the main thread names them, this thread owns them. */
+const torrentsByKey = new Map();
+/** File-claim release callbacks, keyed `${sourceKey}:${fileIndex}`. */
+const releaseByClaim = new Map();
+/** In-flight reads, so a cancel can stop one mid-body. */
+const readsById = new Map();
+
+/**
+ * Forward a log line to the main thread, so worker output is not lost or
+ * interleaved separately from everything else.
+ *
+ * @param {string} message
+ * @returns {void}
+ */
+function log(message) {
+  parentPort.postMessage({ type: Event.LOG, message });
+}
+
+/**
+ * The torrent for a sourceKey, or throw a message the caller can surface.
+ *
+ * @param {string} sourceKey
+ * @returns {import("webtorrent").Torrent}
+ */
+function requireTorrent(sourceKey) {
+  const torrent = torrentsByKey.get(sourceKey);
+  if (!torrent) {
+    throw new Error(`Unknown source ${sourceKey}.`);
+  }
+  return torrent;
+}
+
+/**
+ * Stream a byte range back as CHUNK messages.
+ *
+ * Reads through WebTorrent's own read stream — which serves already-downloaded
+ * pieces from disk and waits for the rest — and forwards it in
+ * {@link STREAM_CHUNK_BYTES} pieces, transferring ownership of each so nothing
+ * is copied across the boundary. `createSendStream` applies the backpressure,
+ * so a fast disk cannot outrun the main thread and rebuild the queue in memory.
+ *
+ * @param {object} params
+ * @param {number} params.id - Request id; CHUNK/READ_END carry it.
+ * @param {string} params.sourceKey
+ * @param {number} params.fileIndex
+ * @param {number | null} params.start - Inclusive, or null for the whole file.
+ * @param {number | null} params.end - Inclusive.
+ * @returns {Promise<void>}
+ */
+async function streamRange({ id, sourceKey, fileIndex, start, end }) {
+  const torrent = requireTorrent(sourceKey);
+  const file = torrent.files?.[fileIndex];
+  if (!file) {
+    throw new Error(`File ${fileIndex} not found in ${sourceKey}.`);
+  }
+
+  const sender = createSendStream({ port: parentPort, requestId: id });
+  readsById.set(id, sender);
+
+  const options = start === null || start === undefined ? {} : { start, end };
+  const source = file.createReadStream(options);
+
+  // Coalesce WebTorrent's own chunking (piece-sized, often much smaller) up to
+  // our chunk size: a round trip costs ~100 µs, so sending its native pieces
+  // straight through would multiply the crossings for no benefit.
+  let pendingParts = [];
+  let pendingBytes = 0;
+
+  const flush = async () => {
+    if (pendingBytes === 0) {
+      return;
+    }
+    const merged = pendingParts.length === 1 ? pendingParts[0] : Buffer.concat(pendingParts, pendingBytes);
+    pendingParts = [];
+    pendingBytes = 0;
+    await sender.send(merged);
+  };
+
+  try {
+    for await (const part of source) {
+      if (sender.isCancelled()) {
+        break;
+      }
+      pendingParts.push(part);
+      pendingBytes += part.length;
+      if (pendingBytes >= STREAM_CHUNK_BYTES) {
+        await flush();
+      }
+    }
+    if (!sender.isCancelled()) {
+      await flush();
+    }
+  } finally {
+    readsById.delete(id);
+    sender.end();
+    // A cancelled read must stop the underlying torrent stream too, or the
+    // pieces keep being fetched for a viewer who has gone.
+    if (typeof source.destroy === "function") {
+      source.destroy();
+    }
+  }
+}
+
+/**
+ * Run one command and return its result.
+ *
+ * @param {string} command
+ * @param {object} params
+ * @param {number} id
+ * @returns {Promise<unknown>}
+ */
+async function runCommand(command, params, id) {
+  switch (command) {
+    case Command.ADD_SOURCE: {
+      const torrent = await pool.getTorrent(params.sourceType, params.source);
+      torrentsByKey.set(params.sourceKey, torrent);
+      return {
+        infoHash: torrent.infoHash,
+        name: torrent.name,
+        // Files cross as plain data; the objects stay here.
+        files: (torrent.files ?? []).map((file, index) => ({
+          index,
+          name: file.name,
+          path: file.path,
+          length: file.length
+        }))
+      };
+    }
+
+    case Command.LIST_FILES: {
+      const torrent = requireTorrent(params.sourceKey);
+      return (torrent.files ?? []).map((file, index) => ({
+        index,
+        name: file.name,
+        path: file.path,
+        length: file.length
+      }));
+    }
+
+    case Command.ACQUIRE_FILE: {
+      const torrent = requireTorrent(params.sourceKey);
+      const claimKey = `${params.sourceKey}:${params.fileIndex}`;
+      // One claim per key; a second acquire without release would leak the
+      // first release callback and pin the file forever.
+      if (!releaseByClaim.has(claimKey)) {
+        releaseByClaim.set(claimKey, pool.acquireFile(torrent, params.fileIndex));
+      }
+      return true;
+    }
+
+    case Command.RELEASE_FILE: {
+      const claimKey = `${params.sourceKey}:${params.fileIndex}`;
+      const release = releaseByClaim.get(claimKey);
+      if (release) {
+        releaseByClaim.delete(claimKey);
+        release();
+      }
+      return true;
+    }
+
+    case Command.FILE_STATS: {
+      const torrent = requireTorrent(params.sourceKey);
+      return pool.getFileStats(torrent, params.fileIndex, {
+        resumeAnchorByteStart: params.resumeAnchorByteStart ?? null
+      });
+    }
+
+    case Command.PRIORITIZE: {
+      const torrent = requireTorrent(params.sourceKey);
+      pool.prioritizeByteRange(torrent, params.fileIndex, params.byteStart, params.windowBytes);
+      return true;
+    }
+
+    case Command.PREFETCH_EDGES: {
+      const torrent = requireTorrent(params.sourceKey);
+      return pool.prefetchFileEdges(torrent, params.fileIndex, params.headBytes, params.tailBytes, params.timeoutMs);
+    }
+
+    case Command.READ_RANGE: {
+      // Streams its own reply; the caller's promise resolves once the body has
+      // been fully sent, which is what lets the client await completion.
+      await streamRange({
+        id,
+        sourceKey: params.sourceKey,
+        fileIndex: params.fileIndex,
+        start: params.start ?? null,
+        end: params.end ?? null
+      });
+      return true;
+    }
+
+    case Command.CANCEL_READ: {
+      readsById.get(params.readId)?.cancel();
+      return true;
+    }
+
+    case Command.DESTROY_ALL: {
+      for (const [, release] of releaseByClaim) {
+        release();
+      }
+      releaseByClaim.clear();
+      torrentsByKey.clear();
+      await pool.destroyAll();
+      return true;
+    }
+
+    default:
+      throw new Error(`Unknown torrent-worker command: ${command}`);
+  }
+}
+
+parentPort.on("message", async (message) => {
+  // Chunk acknowledgements are not commands — they release backpressure on an
+  // in-flight read.
+  if (message?.type === Event.CHUNK_ACK) {
+    readsById.get(message.id)?.ack();
+    return;
+  }
+
+  const { command, id, params } = message ?? {};
+  try {
+    const result = await runCommand(command, params ?? {}, id);
+    parentPort.postMessage({ type: Event.RESULT, id, result });
+  } catch (error) {
+    parentPort.postMessage({ type: Event.ERROR, id, error: error?.message ?? String(error) });
+  }
+});
+
+log("torrent worker started");

package/utils/perf.js

@@ -0,0 +1,121 @@
+/**
+ * @file Runtime performance instrumentation.
+ *
+ * Exists because a field seek took minutes and every explanation offered for it
+ * — encoder too slow, torrent too slow, channel too slow, event loop starved —
+ * was a guess. The numbers that would have settled it were not being recorded.
+ * This records them.
+ *
+ * Two things are measured:
+ *
+ *  - **Event loop delay** (`perf_hooks.monitorEventLoopDelay`). If synchronous
+ *    work (torrent piece hashing, large buffer handling) blocks the loop, every
+ *    read and every send waits behind it, and the symptom looks exactly like a
+ *    slow network. The histogram distinguishes the two beyond argument.
+ *  - **Named operation timings**, so a slow transfer can be attributed to the
+ *    step that actually consumed the time rather than to the whole.
+ *
+ * Deliberately cheap: a histogram sampled every 20 ms, and plain arithmetic per
+ * operation. No trace files, no profiler — `--trace-events-enabled` or
+ * `--cpu-prof` remain available for a deeper look when these figures point
+ * somewhere specific.
+ */
+
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+
+const NANOSECONDS_PER_MILLISECOND = 1e6;
+// Sampling interval for the loop-delay histogram. 20 ms is fine enough to catch
+// the stalls that matter (tens of ms and up) without measurable overhead.
+const LOOP_SAMPLE_INTERVAL_MS = 20;
+
+const loopDelay = monitorEventLoopDelay({ resolution: LOOP_SAMPLE_INTERVAL_MS });
+loopDelay.enable();
+
+/**
+ * Event-loop delay since the last {@link resetEventLoopDelay}, in milliseconds.
+ *
+ * `mean` is the everyday cost; `max` and `p99` are what a single blocking spell
+ * does to whatever was waiting. A transfer that looks network-bound but shows a
+ * large `max` here was not network-bound at all.
+ *
+ * @returns {{ meanMs: number, p99Ms: number, maxMs: number }}
+ */
+export function eventLoopDelay() {
+  return {
+    meanMs: loopDelay.mean / NANOSECONDS_PER_MILLISECOND,
+    p99Ms: loopDelay.percentile(99) / NANOSECONDS_PER_MILLISECOND,
+    maxMs: loopDelay.max / NANOSECONDS_PER_MILLISECOND
+  };
+}
+
+/**
+ * Start a fresh measurement window for the loop-delay histogram, so a reported
+ * figure describes one operation rather than the process's whole lifetime.
+ *
+ * @returns {void}
+ */
+export function resetEventLoopDelay() {
+  loopDelay.reset();
+}
+
+/**
+ * Accumulates how long the parts of one operation took.
+ *
+ * Usage: `mark()` after each step; `summary()` renders `step=12.3ms` pairs in
+ * the order they were marked.
+ */
+export class OperationTimer {
+  #startedAt;
+  #lastMarkAt;
+  #marks;
+
+  constructor() {
+    this.#startedAt = performance.now();
+    this.#lastMarkAt = this.#startedAt;
+    this.#marks = [];
+  }
+
+  /**
+   * Record the time since the previous mark under `name`.
+   *
+   * @param {string} name
+   * @returns {number} Milliseconds since the previous mark.
+   */
+  mark(name) {
+    const now = performance.now();
+    const elapsed = now - this.#lastMarkAt;
+    this.#lastMarkAt = now;
+    this.#marks.push([name, elapsed]);
+    return elapsed;
+  }
+
+  /**
+   * Add a figure measured elsewhere (a running total, a count) so it appears in
+   * the same line as the timings.
+   *
+   * @param {string} name
+   * @param {number} value
+   * @returns {void}
+   */
+  add(name, value) {
+    this.#marks.push([name, value]);
+  }
+
+  /**
+   * Total elapsed time since construction, in milliseconds.
+   *
+   * @returns {number}
+   */
+  totalMs() {
+    return performance.now() - this.#startedAt;
+  }
+
+  /**
+   * All marks as `name=12.3ms` pairs, in order.
+   *
+   * @returns {string}
+   */
+  summary() {
+    return this.#marks.map(([name, value]) => `${name}=${value.toFixed(1)}ms`).join(" ");
+  }
+}