@torrent-tv/proxy 2.9.70 → 2.9.71

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.9.71
+
+- **New**: The torrent client now runs on its own thread (`services/torrent-worker/`). Profiling a live seek (2026-08-02) found the main thread ~85% occupied by WebTorrent — buffer concatenation in `uint8-util` ~15%, `_updateWire` and its wrapper ~9%, garbage collection ~5%, and **no piece hashing at all**, which had been the standing assumption — while three of four cores idled. Serving a segment shared that thread, so reading an already-finished 10 MB file off SSD took **12-23 s** where handing it to the channel took 125 ms. Measured after the split, through the real `/stream` route: **3 MB in 0.05-0.12 s** (~500 Mbps), roughly a hundredfold improvement, with main-thread event-loop delay down from 300-390 ms to **28-38 ms**.
+- **Chore**: The transport was chosen by measurement, not preference. A 10 MB body costs 37 ms structured-cloned, **104 ms through a transferable `ReadableStream`** (the obvious standard answer, and 22x worse), and **4.8-5.3 ms** transferring ownership of 1 MB chunks behind an ordinary `ReadableStream` wrapper — standard interface outside, ownership transfer inside, which is what shipped. Chunk size follows the same arithmetic: at ~100 µs per round trip, 64 KB chunks would spend 13 ms per segment on overhead versus ~1 ms at 1 MB. Backpressure caps chunks in flight so a fast disk cannot rebuild in the message queue the memory the transfers save.
+- **Chore**: `WorkerTorrentPool` presents `TorrentPool`'s existing interface, so the switch is one line in `server.js` and none of the twelve call sites across the stream route, subtitle route, playback planner and health report changed. Torrent objects cannot cross a thread, so the worker keys them by `sourceKey` and hands back a stand-in exposing the `files[i].createReadStream()` shape callers already use.
+
 ## 2.9.70
 
 - **Chore**: Instrumentation to settle where a slow transfer actually loses its time, instead of arguing about it. Every data-channel body transfer now reports the split — `readMs` (reading the body from the local route), `chanMs` (handing chunks to the channel), `drainMs` (waiting for the channel queue) — plus `rate` and, decisively, the **event-loop delay** over the same window (`loopMean`/`loopP99`/`loopMax`, via `perf_hooks.monitorEventLoopDelay`). Synchronous work blocking the loop looks exactly like a slow network from the outside; these figures tell them apart. Prompted by a field seek where a 9.4 MB segment took 16.5 s to deliver with the channel queue **empty the whole time** (`maxBuffered=0`) while the encoder ran at 14x realtime and the file was already on disk — so none of encoder, torrent or channel capacity explained it, and no measurement existed that could. New `utils/perf.js` (`OperationTimer`, `eventLoopDelay`); deeper tools (`--trace-events-enabled`, `--cpu-prof`) remain for when these point somewhere specific.

package/package.json

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

package/server.js

@@ -29,7 +29,7 @@ import { handleApiTranscodeSessionSeekPost } from "./routes/api/transcode-sessio
 import { handleStreamGet } from "./routes/stream/get.js";
 import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
 import { createSourceRegistry } from "./store/source-registry.js";
-import { TorrentPool } from "./services/torrent-pool.js";
+import { WorkerTorrentPool } from "./services/torrent-worker/pool-adapter.js";
 import { HlsSessionManager } from "./services/hls-session-manager.js";
 import { createPlaybackPlanner } from "./services/playback-planner.js";
 import { detectVideoEncoder, benchmarkSoftwarePresets, detectTonemapSupport } from "./services/hwaccel.js";
@@ -98,7 +98,13 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   });
 
   const sourceRegistry = createSourceRegistry(200);
-  const torrentPool = new TorrentPool({ maxDiskBytes });
+  // The torrent runs on its own thread. Profiling a live seek (2026-08-02)
+  // found the main thread ~85% occupied by WebTorrent — buffer concatenation
+  // ~15%, wire updates ~9%, garbage collection ~5% — while three of four cores
+  // idled. Serving a segment shared that thread, so reading an already-finished
+  // 10 MB file took 12-23 s against 125 ms to hand it to the channel. The
+  // adapter keeps TorrentPool's interface, so nothing downstream changed.
+  const torrentPool = new WorkerTorrentPool({ maxDiskBytes });
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });

package/services/torrent-worker/channel.js

@@ -0,0 +1,222 @@
+/**
+ * @file The transport both sides of the torrent worker share.
+ *
+ * One place holds the request/reply bookkeeping and the streaming rules, so the
+ * worker and its main-thread client cannot drift apart on the details that
+ * matter: which side transfers, which side acknowledges, and when a stream is
+ * allowed to keep going.
+ *
+ * See `protocol.js` for why the design is what it is — every number in it came
+ * from a measurement, not a preference.
+ */
+
+import { Event, STREAM_HIGH_WATER_CHUNKS } from "./protocol.js";
+
+/**
+ * Issue request ids that stay unique for the life of a thread.
+ *
+ * @returns {() => number}
+ */
+export function createRequestIds() {
+  let next = 0;
+  return () => (next += 1);
+}
+
+/**
+ * Wrap a port's messages into request/reply calls.
+ *
+ * Callers get promises; the plumbing of matching replies to requests, and of
+ * turning a worker-side failure back into a rejection, lives here. `Error`
+ * objects do not survive a thread boundary, so failures cross as messages and
+ * are rebuilt into `Error`s on arrival — a caller sees an ordinary rejection.
+ *
+ * @param {import("node:worker_threads").MessagePort | import("node:worker_threads").Worker} port
+ * @returns {{
+ *   call: (command: string, params?: object) => Promise<unknown>,
+ *   handleReply: (message: object) => boolean,
+ *   rejectAll: (reason: Error) => void
+ * }}
+ */
+export function createCaller(port) {
+  const nextId = createRequestIds();
+  const pending = new Map();
+
+  return {
+    call(command, params = {}) {
+      return new Promise((resolve, reject) => {
+        const id = nextId();
+        pending.set(id, { resolve, reject });
+        port.postMessage({ command, id, params });
+      });
+    },
+
+    /**
+     * Feed a message in; returns true when it was a reply this caller owned.
+     */
+    handleReply(message) {
+      const entry = pending.get(message?.id);
+      if (!entry) {
+        return false;
+      }
+      if (message.type === Event.RESULT) {
+        pending.delete(message.id);
+        entry.resolve(message.result);
+        return true;
+      }
+      if (message.type === Event.ERROR) {
+        pending.delete(message.id);
+        entry.reject(new Error(message.error ?? "Torrent worker request failed."));
+        return true;
+      }
+      return false;
+    },
+
+    /**
+     * Fail everything outstanding — the worker died, or is being shut down.
+     */
+    rejectAll(reason) {
+      for (const [, entry] of pending) {
+        entry.reject(reason);
+      }
+      pending.clear();
+    }
+  };
+}
+
+/**
+ * Receive a chunked body as an ordinary `ReadableStream`.
+ *
+ * This is the half that makes the design pay off: chunks arrive as transferred
+ * buffers (no copying), and are handed on through a standard stream, so callers
+ * treat it exactly like any other body. Each chunk is acknowledged as it is
+ * enqueued, which is what lets the worker keep only
+ * {@link STREAM_HIGH_WATER_CHUNKS} in flight.
+ *
+ * Cancelling the stream — a viewer navigating away, a superseded seek — sends
+ * the cancel command, so the worker stops reading rather than filling a queue
+ * nobody will drain.
+ *
+ * @param {object} params
+ * @param {import("node:worker_threads").Worker} params.port
+ * @param {number} params.requestId
+ * @param {() => void} params.onCancel - Sends CANCEL_READ for this request.
+ * @returns {{ stream: ReadableStream<Uint8Array>, push: (bytes: Uint8Array) => void, close: () => void, fail: (error: Error) => void }}
+ */
+export function createReceiveStream({ port, requestId, onCancel }) {
+  let controller = null;
+  let finished = false;
+
+  const stream = new ReadableStream({
+    start(streamController) {
+      controller = streamController;
+    },
+    cancel() {
+      if (!finished) {
+        finished = true;
+        onCancel();
+      }
+    }
+  });
+
+  return {
+    stream,
+
+    push(bytes) {
+      if (finished || !controller) {
+        return;
+      }
+      controller.enqueue(bytes);
+      // Acknowledge only once the data is in the stream's own queue, so the
+      // worker's in-flight count reflects what has actually been taken up.
+      port.postMessage({ type: Event.CHUNK_ACK, id: requestId });
+    },
+
+    close() {
+      if (finished || !controller) {
+        return;
+      }
+      finished = true;
+      controller.close();
+    },
+
+    fail(error) {
+      if (finished || !controller) {
+        return;
+      }
+      finished = true;
+      controller.error(error);
+    }
+  };
+}
+
+/**
+ * Send a body as chunks, pausing when too many are unacknowledged.
+ *
+ * The worker side of the same arrangement. `waitForCapacity` resolves when the
+ * main thread has taken up enough of what was sent; without it a fast disk
+ * would outrun the channel and rebuild in the message queue exactly the memory
+ * the transfers were saving.
+ *
+ * @param {object} params
+ * @param {import("node:worker_threads").MessagePort} params.port
+ * @param {number} params.requestId
+ * @returns {{ send: (bytes: Buffer) => Promise<void>, end: () => void, ack: () => void, cancel: () => void, isCancelled: () => boolean }}
+ */
+export function createSendStream({ port, requestId }) {
+  let inFlight = 0;
+  let cancelled = false;
+  let wake = null;
+
+  const waitForCapacity = () => {
+    if (cancelled || inFlight < STREAM_HIGH_WATER_CHUNKS) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      wake = resolve;
+    });
+  };
+
+  return {
+    async send(bytes) {
+      await waitForCapacity();
+      if (cancelled) {
+        return;
+      }
+      inFlight += 1;
+      // Transfer the underlying memory rather than copying it — the whole point
+      // of the design, and the difference between 4.8 ms and 37 ms per 10 MB.
+      port.postMessage(
+        { type: Event.CHUNK, id: requestId, bytes },
+        [bytes.buffer]
+      );
+    },
+
+    end() {
+      if (!cancelled) {
+        port.postMessage({ type: Event.READ_END, id: requestId });
+      }
+    },
+
+    ack() {
+      inFlight = Math.max(0, inFlight - 1);
+      if (wake) {
+        const resume = wake;
+        wake = null;
+        resume();
+      }
+    },
+
+    cancel() {
+      cancelled = true;
+      if (wake) {
+        const resume = wake;
+        wake = null;
+        resume();
+      }
+    },
+
+    isCancelled() {
+      return cancelled;
+    }
+  };
+}

package/services/torrent-worker/client.js

@@ -0,0 +1,264 @@
+/**
+ * @file Main-thread face of the torrent worker.
+ *
+ * Presents the same operations the routes and session manager already use, so
+ * moving the torrent to its own thread does not ripple through calling code.
+ * The one unavoidable change is that torrents are named by `sourceKey` instead
+ * of passed around as objects — objects cannot cross a thread boundary, and
+ * pretending otherwise would mean copying them on every call.
+ *
+ * Reads come back as an ordinary `ReadableStream`, so `/stream` and the codec
+ * probe consume them exactly as they consume WebTorrent's own streams today.
+ * What that hides is the part that matters: chunks arrive as transferred
+ * buffers, never copied — 5.3 ms per 10 MB against 37 ms if cloned and 104 ms
+ * through a transferable stream (measured 2026-08-02, see `protocol.js`).
+ */
+
+import { Worker } from "node:worker_threads";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { logger } from "../../utils/logger.js";
+import { createCaller, createReceiveStream } from "./channel.js";
+import { Command, Event } from "./protocol.js";
+
+const WORKER_URL = new URL("./worker.js", import.meta.url);
+
+/**
+ * Runs the torrent client on its own thread and exposes it to the main thread.
+ *
+ * Why this exists at all: profiling during a live seek found the main thread
+ * ~85% busy with WebTorrent (buffer concatenation ~15%, wire updates ~9%,
+ * garbage collection ~5%), while three of four cores idled. Serving a segment
+ * queued behind that work, so reading a finished 10 MB file took 12-23 s where
+ * handing it to the channel took 125 ms.
+ */
+export class TorrentWorkerClient {
+  #worker;
+  #caller;
+  /** Receive-side handles for in-flight reads, keyed by request id. */
+  #reads = new Map();
+  /** Monotonic ids for reads, independent of the caller's own numbering. */
+  #nextReadId = 0;
+
+  /**
+   * @param {{ maxDiskBytes?: number }} [options]
+   */
+  constructor({ maxDiskBytes } = {}) {
+    this.#worker = new Worker(fileURLToPath(WORKER_URL), {
+      workerData: { maxDiskBytes }
+    });
+    this.#caller = createCaller(this.#worker);
+
+    this.#worker.on("message", (message) => {
+      if (this.#caller.handleReply(message)) {
+        return;
+      }
+      switch (message?.type) {
+        case Event.CHUNK: {
+          const bytes = message.bytes;
+          this.#reads.get(message.id)?.push(
+            new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length)
+          );
+          break;
+        }
+        case Event.READ_END:
+          this.#reads.get(message.id)?.close();
+          this.#reads.delete(message.id);
+          break;
+        case Event.LOG:
+          logger.info(`torrent-worker: ${message.message}`);
+          break;
+        default:
+          break;
+      }
+    });
+
+    this.#worker.on("error", (error) => {
+      logger.error(`torrent-worker crashed: ${error?.message ?? error}`);
+      // Fail everything outstanding rather than leaving callers hanging: a dead
+      // worker will never answer, and a stalled request is worse than an error
+      // the loading flow can retry.
+      const reason = new Error("Torrent worker stopped unexpectedly.");
+      this.#caller.rejectAll(reason);
+      for (const [, read] of this.#reads) {
+        read.fail(reason);
+      }
+      this.#reads.clear();
+    });
+  }
+
+  /**
+   * Add (or join) a torrent and register it under `sourceKey`.
+   *
+   * @param {{ sourceKey: string, sourceType: "magnet" | "torrent", source: string }} params
+   * @returns {Promise<{ infoHash: string, name: string, files: { index: number, name: string, path: string, length: number }[] }>}
+   */
+  async addSource({ sourceKey, sourceType, source }) {
+    return this.#caller.call(Command.ADD_SOURCE, { sourceKey, sourceType, source });
+  }
+
+  /**
+   * The torrent's files, as plain data.
+   *
+   * @param {string} sourceKey
+   * @returns {Promise<{ index: number, name: string, path: string, length: number }[]>}
+   */
+  async listFiles(sourceKey) {
+    return this.#caller.call(Command.LIST_FILES, { sourceKey });
+  }
+
+  /**
+   * Claim a file so it is not evicted while being read.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @returns {Promise<void>}
+   */
+  async acquireFile(sourceKey, fileIndex) {
+    await this.#caller.call(Command.ACQUIRE_FILE, { sourceKey, fileIndex });
+  }
+
+  /**
+   * Drop a claim taken with {@link acquireFile}.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @returns {Promise<void>}
+   */
+  async releaseFile(sourceKey, fileIndex) {
+    await this.#caller.call(Command.RELEASE_FILE, { sourceKey, fileIndex });
+  }
+
+  /**
+   * Live download figures for the progress display.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, resumeAnchorByteStart?: number | null }} params
+   * @returns {Promise<object>}
+   */
+  async getFileStats({ sourceKey, fileIndex, resumeAnchorByteStart = null }) {
+    return this.#caller.call(Command.FILE_STATS, { sourceKey, fileIndex, resumeAnchorByteStart });
+  }
+
+  /**
+   * Reorder piece selection around a read position (seek prioritisation).
+   *
+   * @param {{ sourceKey: string, fileIndex: number, byteStart: number, windowBytes?: number }} params
+   * @returns {Promise<void>}
+   */
+  async prioritizeByteRange({ sourceKey, fileIndex, byteStart, windowBytes }) {
+    await this.#caller.call(Command.PRIORITIZE, { sourceKey, fileIndex, byteStart, windowBytes });
+  }
+
+  /**
+   * Pre-fetch the head and tail the codec probe needs.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, headBytes?: number, tailBytes?: number, timeoutMs?: number }} params
+   * @returns {Promise<unknown>}
+   */
+  async prefetchFileEdges({ sourceKey, fileIndex, headBytes, tailBytes, timeoutMs }) {
+    return this.#caller.call(Command.PREFETCH_EDGES, {
+      sourceKey,
+      fileIndex,
+      headBytes,
+      tailBytes,
+      timeoutMs
+    });
+  }
+
+  /**
+   * Read a byte range as a stream.
+   *
+   * Returns immediately with a stream that fills as chunks arrive; cancelling it
+   * (viewer gone, seek superseded) stops the worker reading, so pieces are not
+   * fetched for a stream nobody will drain.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, start?: number | null, end?: number | null }} params
+   * @returns {ReadableStream<Uint8Array>}
+   */
+  createReadStream({ sourceKey, fileIndex, start = null, end = null }) {
+    const readId = (this.#nextReadId += 1);
+    const receive = createReceiveStream({
+      port: this.#worker,
+      requestId: readId,
+      onCancel: () => {
+        void this.#caller.call(Command.CANCEL_READ, { readId }).catch(() => undefined);
+        this.#reads.delete(readId);
+      }
+    });
+    this.#reads.set(readId, receive);
+
+    // The worker replies to READ_RANGE only once the body is fully sent; a
+    // failure before that must surface on the stream, not vanish.
+    this.#worker.postMessage({
+      command: Command.READ_RANGE,
+      id: readId,
+      params: { sourceKey, fileIndex, start, end }
+    });
+
+    return receive.stream;
+  }
+
+  /**
+   * A stand-in for the WebTorrent torrent object, backed by the worker.
+   *
+   * Callers already hold a torrent and reach into `torrent.files[i]` — for the
+   * length, the name, or a read stream. Handing back an object of the same
+   * shape keeps every one of those call sites working unchanged, which matters:
+   * they are spread across the stream route, the subtitle route, the playback
+   * planner and the health report, and rewriting all of them to thread a
+   * `sourceKey` through would be a large change with nothing to show for it.
+   *
+   * Only what is actually used is provided. Anything else would be a promise we
+   * cannot keep — the real object lives on the other thread and its methods are
+   * not reachable from here.
+   *
+   * @param {{ sourceKey: string, sourceType: "magnet" | "torrent", source: string }} params
+   * @returns {Promise<{ infoHash: string, name: string, sourceKey: string, files: object[] }>}
+   */
+  async getTorrent({ sourceKey, sourceType, source }) {
+    const info = await this.addSource({ sourceKey, sourceType, source });
+    const client = this;
+    return {
+      infoHash: info.infoHash,
+      name: info.name,
+      // Carried so helpers that receive only the torrent can still name it to
+      // the worker.
+      sourceKey,
+      files: info.files.map((file) => ({
+        ...file,
+        /**
+         * @param {{ start?: number, end?: number }} [options]
+         * @returns {ReadableStream<Uint8Array>}
+         */
+        createReadStream(options = {}) {
+          // Node stream, not a web one: Fastify replies and the ffmpeg pipe
+          // both expect that shape, and every existing call site passes the
+          // result straight to one of them. `Readable.fromWeb` adds no copy —
+          // it wraps the same buffers.
+          return Readable.fromWeb(
+            client.createReadStream({
+              sourceKey,
+              fileIndex: file.index,
+              start: options.start ?? null,
+              end: options.end ?? null
+            })
+          );
+        }
+      }))
+    };
+  }
+
+  /**
+   * Shut the torrent client down and stop the thread.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroyAll() {
+    try {
+      await this.#caller.call(Command.DESTROY_ALL, {});
+    } catch {
+      // Already gone — termination below is what matters.
+    }
+    await this.#worker.terminate();
+  }
+}

package/services/torrent-worker/pool-adapter.js

@@ -0,0 +1,171 @@
+/**
+ * @file `TorrentPool`'s interface, served from the worker thread.
+ *
+ * The routes, the planner, the health report and the session manager all reach
+ * for a torrent pool and use it the same handful of ways. Rather than rewrite
+ * every one of them to thread a `sourceKey` through and await what used to be
+ * immediate, this presents the shape they already expect and does the thread
+ * hop behind it. Swapping the implementation is then a one-line change at
+ * construction, and the call sites are untouched — which is what keeps a change
+ * of this size reviewable.
+ *
+ * Two accommodations are needed, and both are deliberate:
+ *
+ *  - **`acquireFile` and `prioritizeByteRange` stay synchronous.** They return
+ *    nothing the caller inspects, so the command is dispatched and not awaited.
+ *    `acquireFile` hands back a release function exactly as before, which sends
+ *    its own command when called. Awaiting them would mean touching every call
+ *    site for no observable gain.
+ *  - **`getTorrent` needs a `sourceKey`.** Torrent objects cannot cross a
+ *    thread, so the worker keys them. Callers that have one pass it; the rest
+ *    get one derived from the source itself, so the identity stays stable
+ *    across calls for the same torrent.
+ */
+
+import crypto from "node:crypto";
+import { TorrentWorkerClient } from "./client.js";
+
+/**
+ * Stable key for a source, matching how the worker keys its torrents.
+ *
+ * Derived from the source itself rather than handed out per request, so two
+ * routes asking for the same torrent name the same thing on the worker side.
+ *
+ * @param {"magnet" | "torrent"} sourceType
+ * @param {string} source
+ * @returns {string}
+ */
+function deriveSourceKey(sourceType, source) {
+  return `${sourceType}:${crypto.createHash("sha1").update(source).digest("hex")}`;
+}
+
+/**
+ * A torrent pool whose work happens on another thread.
+ *
+ * See `protocol.js` for why: the torrent was taking ~85% of the main thread and
+ * everything owed to a viewer queued behind it.
+ */
+export class WorkerTorrentPool {
+  #client;
+  /** Stand-ins by source key, so repeat calls return the same object. */
+  #torrents = new Map();
+
+  /**
+   * @param {{ maxDiskBytes?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.#client = new TorrentWorkerClient(options);
+  }
+
+  /**
+   * Load (or join) a torrent and return a stand-in for it.
+   *
+   * @param {"magnet" | "torrent"} sourceType
+   * @param {string} source
+   * @returns {Promise<object>}
+   */
+  async getTorrent(sourceType, source) {
+    const sourceKey = deriveSourceKey(sourceType, source);
+    const existing = this.#torrents.get(sourceKey);
+    if (existing) {
+      return existing;
+    }
+    const torrent = await this.#client.getTorrent({ sourceKey, sourceType, source });
+    this.#torrents.set(sourceKey, torrent);
+    return torrent;
+  }
+
+  /**
+   * Claim a file for reading; the returned function releases it.
+   *
+   * Synchronous by design — see the file header.
+   *
+   * @param {object} torrent - A stand-in from {@link getTorrent}.
+   * @param {number} fileIndex
+   * @returns {() => void}
+   */
+  acquireFile(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return () => undefined;
+    }
+    void this.#client.acquireFile(sourceKey, fileIndex).catch(() => undefined);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      void this.#client.releaseFile(sourceKey, fileIndex).catch(() => undefined);
+    };
+  }
+
+  /**
+   * Live download figures for the progress display.
+   *
+   * @param {object} torrent
+   * @param {number | null} [fileIndex]
+   * @param {{ resumeAnchorByteStart?: number | null }} [options]
+   * @returns {Promise<object | null>}
+   */
+  async getFileStats(torrent, fileIndex = null, options = {}) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    return this.#client.getFileStats({
+      sourceKey,
+      fileIndex,
+      resumeAnchorByteStart: options?.resumeAnchorByteStart ?? null
+    });
+  }
+
+  /**
+   * Reorder piece selection around a read position.
+   *
+   * Synchronous by design — see the file header.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} byteStart
+   * @param {number} [windowBytes]
+   * @returns {void}
+   */
+  prioritizeByteRange(torrent, fileIndex, byteStart, windowBytes) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return;
+    }
+    void this.#client
+      .prioritizeByteRange({ sourceKey, fileIndex, byteStart, windowBytes })
+      .catch(() => undefined);
+  }
+
+  /**
+   * Pre-fetch the head and tail the codec probe needs.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} [headBytes]
+   * @param {number} [tailBytes]
+   * @param {number} [timeoutMs]
+   * @returns {Promise<unknown>}
+   */
+  async prefetchFileEdges(torrent, fileIndex, headBytes, tailBytes, timeoutMs) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    return this.#client.prefetchFileEdges({ sourceKey, fileIndex, headBytes, tailBytes, timeoutMs });
+  }
+
+  /**
+   * Shut the torrent client down and stop the thread.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroyAll() {
+    this.#torrents.clear();
+    await this.#client.destroyAll();
+  }
+}

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");