@torrent-tv/proxy 2.9.71 → 2.9.72

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.72
+
+- **Fix**: Playback broke entirely after the torrent moved to its own thread (2.9.71): the torrent was deleted **with its downloaded data** while still being read, after which every read hung and ffmpeg saw an empty input (`Stream ends prematurely at 0, should be 3303133078`), and the container-index read took 73 s to return nothing. Cause: `acquireFile` was dispatched without awaiting while its release was sent normally, so a release could overtake the acquire it belonged to; the reader count then hit zero mid-read and the idle sweep fired (`removed idle torrent ... and its store`). Two fixes, each sufficient alone: the release is now chained onto the acquire so it can never arrive first, and the worker additionally holds the file for the whole duration of the read — a claim that lives inside the read and so cannot be reordered against it. Not reproducible locally, where the test torrent was fully downloaded and never went idle.
+
 ## 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**.

package/package.json

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

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

@@ -1,171 +1,179 @@
-/**
- * @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();
-  }
-}
+/**
+ * @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;
+    }
+    // Dispatched, not awaited — callers use the result immediately and inspect
+    // nothing. But the release MUST NOT overtake it: both are ordinary messages
+    // to the worker, and if release arrives first the reader count drops to zero
+    // while a read is still running. The idle sweep then removes the torrent AND
+    // its downloaded data out from under the encoder — field 2026-08-02:
+    // "removed idle torrent ... and its store" mid-playback, after which every
+    // read hung and ffmpeg saw an empty input ("Stream ends prematurely at 0").
+    // Chaining the release onto the acquire keeps them in order.
+    const acquired = this.#client.acquireFile(sourceKey, fileIndex).catch(() => undefined);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      void acquired.then(() => 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/worker.js

@@ -1,255 +1,265 @@
-/**
- * @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");
+/**
+ * @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);
+
+  // Hold the file for as long as this read runs. The caller also acquires it,
+  // but that acquire and its release are separate messages from another thread
+  // and can be reordered; this one cannot, because it lives entirely inside the
+  // read. Without it the idle sweep saw a zero reader count and removed the
+  // torrent AND its store mid-read — field 2026-08-02: "removed idle torrent
+  // ... and its store", after which every subsequent read hung and ffmpeg got
+  // an empty input.
+  const releaseRead = pool.acquireFile(torrent, fileIndex);
+
+  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);
+    releaseRead();
+    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");