@torrent-tv/proxy 2.9.93 → 2.9.95

package/services/torrent-worker/worker.js

@@ -1,410 +1,412 @@
-/**
- * @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.
- */
-
-// MUST stay first: it redirects `webrtc-polyfill` to a JavaScript WebRTC stack
-// before WebTorrent can reach the native one. Two isolates using
-// node-datachannel at once abort the process, and the torrent's wss trackers
-// create peer connections of their own.
-import "./install-webrtc-shim.js";
-import { parentPort, workerData } from "node:worker_threads";
-import { createSendStream } from "./channel.js";
-import { createFileClaims } from "./file-claims.js";
-import { readFragments } from "./piece-reader.js";
-import { Command, Event } from "./protocol.js";
-
-// Imported dynamically, and that is load-bearing: static imports are RESOLVED
-// during linking, before any module body runs, so a statically imported pool
-// would drag in WebTorrent — and with it the real `webrtc-polyfill` — before
-// the hook above had a chance to register. Verified the hard way: with a static
-// import the process still aborted, and the stack named the genuine polyfill.
-const { TorrentPool } = await import("../torrent-pool.js");
-const { collectStoreStats, findSharedStore } = await import("../piece-store/shared-piece-store.js");
-
-const pool = new TorrentPool({
-  maxDiskBytes: workerData?.maxDiskBytes,
-  memoryBytes: workerData?.memoryBytes
-});
-
-/** Torrents by sourceKey — the main thread names them, this thread owns them. */
-const torrentsByKey = new Map();
-/** File claims, each with its own identity — see `file-claims.js`. */
-const fileClaims = createFileClaims();
-/** 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, waiting for it if it is still being added.
- *
- * The map holds a PROMISE, registered the moment the add begins rather than
- * when it finishes. That distinction is the whole fix: adding a magnet takes as
- * long as its metadata does — seconds to tens of seconds — and until 2.9.77
- * everything naming that source in the meantime was told `Unknown source`,
- * which is false. The source exists; it is not ready. Reproduced with a magnet
- * nobody seeds: stats, the file listing and a read all failed instantly while
- * the add was still in flight, which on the loading screen shows up as no
- * peers, no progress, and a plan request that fails before the torrent has had
- * a chance to start.
- *
- * A source that was never added still throws, which is the honest answer.
- *
- * @param {string} sourceKey
- * @returns {Promise<import("webtorrent").Torrent>}
- */
-async function requireTorrent(sourceKey) {
-  const pending = torrentsByKey.get(sourceKey);
-  if (!pending) {
-    throw new Error(`Unknown source ${sourceKey}.`);
-  }
-  return pending;
-}
-
-/**
- * Fragments waiting for the main thread to say it has finished reading them,
- * keyed by request id. One per read, because only one fragment is in flight.
- *
- * @type {Map<number, () => void>}
- */
-const fragmentWaiters = new Map();
-
-/**
- * Wake a read that is waiting for a fragment to be confirmed.
- *
- * Used both by the confirmation itself and by cancellation — a cancelled read
- * will never be confirmed, and without this it would wait forever holding a pin.
- *
- * @param {number} id
- * @returns {void}
- */
-function settleFragment(id) {
-  const done = fragmentWaiters.get(id);
-  if (done) {
-    fragmentWaiters.delete(id);
-    done();
-  }
-}
-
-/**
- * Send one fragment's position and wait until the main thread is done with it.
- *
- * The pin is dropped only after the confirmation, because until then the other
- * thread may still be reading those exact bytes.
- *
- * @param {number} id
- * @param {import("./piece-reader.js").PieceFragment} fragment
- * @returns {Promise<void>}
- */
-function sendFragment(id, fragment) {
-  return new Promise((resolve) => {
-    fragmentWaiters.set(id, () => {
-      fragment.release();
-      resolve();
-    });
-    parentPort.postMessage({
-      type: Event.FRAGMENT,
-      id,
-      pieceIndex: fragment.pieceIndex,
-      offset: fragment.offset,
-      length: fragment.length
-    });
-  });
-}
-
-/**
- * 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 = await 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 rangeStart = start ?? 0;
-  const rangeEnd = end ?? file.length - 1;
-
-  let failed = false;
-  try {
-    // Positions in shared memory, not bytes: the main thread maps the same pool
-    // and reads each fragment in place, so nothing is copied and nothing is
-    // transferred. See `piece-reader.js`.
-    for await (const fragment of readFragments({
-      torrent,
-      fileIndex,
-      start: rangeStart,
-      end: rangeEnd,
-      cancellation: sender
-    })) {
-      if (sender.isCancelled()) {
-        fragment.release();
-        break;
-      }
-      // One fragment in flight at a time. Each one holds a piece pinned, and
-      // the store guarantees only two resident pieces at its smallest budget —
-      // holding two pins while asking for a third would deadlock it against
-      // itself. The round trip costs ~100 µs against a piece worth megabytes,
-      // so there is nothing to win by overlapping them.
-      await sendFragment(id, fragment);
-    }
-  } catch (error) {
-    // The end-of-read marker means "the body is complete". Sending it after a
-    // failure told the reader the file simply ended — a truncated segment that
-    // ffmpeg reported as `Stream ends prematurely`, with the real cause thrown
-    // away. Let the error propagate instead; the command handler reports it and
-    // the main thread fails the stream.
-    failed = true;
-    throw error;
-  } finally {
-    readsById.delete(id);
-    // Any fragment still awaiting confirmation will never get one now; settling
-    // it here releases its pin rather than leaking a held slot.
-    settleFragment(id);
-    releaseRead();
-    if (!failed) {
-      sender.end();
-    }
-    // Nothing else to tear down: the reader owns no stream of its own, and a
-    // cancelled read stops at its next fragment boundary because it polls the
-    // same `sender` for cancellation.
-  }
-}
-
-/**
- * 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: {
-      // Registered before it resolves, so anything naming this source while it
-      // is being added waits for it instead of being told it does not exist.
-      // Reusing the same promise for a repeated add also collapses two callers
-      // racing to open the same torrent into one.
-      let pending = torrentsByKey.get(params.sourceKey);
-      if (!pending) {
-        pending = pool.getTorrent(params.sourceType, params.source);
-        torrentsByKey.set(params.sourceKey, pending);
-        // A failed add must not be remembered, or every later attempt at this
-        // source replays the same failure. The handler also marks the rejection
-        // as observed, so it cannot surface as an unhandled one.
-        pending.catch(() => {
-          if (torrentsByKey.get(params.sourceKey) === pending) {
-            torrentsByKey.delete(params.sourceKey);
-          }
-        });
-      }
-      const torrent = await pending;
-      return {
-        infoHash: torrent.infoHash,
-        name: torrent.name,
-        // The piece pool itself. A `SharedArrayBuffer` crosses as a reference to
-        // the same memory rather than a copy, which is what lets the main thread
-        // read a piece where it already lies instead of being sent its bytes.
-        sharedBuffer: findSharedStore(torrent)?.sharedBuffer ?? null,
-        // 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 = await 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 = await requireTorrent(params.sourceKey);
-      // Every acquire is its own claim. Sharing one per file meant the first
-      // reader to finish released the hold while others were still reading.
-      return fileClaims.open(
-        params.sourceKey,
-        params.fileIndex,
-        pool.acquireFile(torrent, params.fileIndex)
-      );
-    }
-
-    case Command.RELEASE_FILE: {
-      const released = fileClaims.close(params.claimId);
-      if (!released) {
-        // Not fatal — but it means a release arrived twice or after teardown,
-        // and silence here is what let the previous scheme look healthy.
-        log(`release for unknown file claim ${params.claimId}`);
-      }
-      return released;
-    }
-
-    case Command.FILE_STATS: {
-      const torrent = await requireTorrent(params.sourceKey);
-      return pool.getFileStats(torrent, params.fileIndex, {
-        resumeAnchorByteStart: params.resumeAnchorByteStart ?? null
-      });
-    }
-
-    case Command.PRIORITIZE: {
-      const torrent = await requireTorrent(params.sourceKey);
-      pool.prioritizeByteRange(torrent, params.fileIndex, params.byteStart, params.windowBytes, {
-        wholeFileRead: params.wholeFileRead === true
-      });
-      return true;
-    }
-
-    case Command.PREFETCH_EDGES: {
-      const torrent = await requireTorrent(params.sourceKey);
-      return pool.prefetchFileEdges(torrent, params.fileIndex, params.options ?? {});
-    }
-
-    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();
-      // A cancelled read will never have its outstanding fragment confirmed, so
-      // wake it here — otherwise it waits forever with a piece pinned.
-      settleFragment(params.readId);
-      return true;
-    }
-
-    case Command.DESTROY_ALL: {
-      fileClaims.closeAll();
-      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;
-  }
-
-  // The main thread has finished reading a fragment out of shared memory, so
-  // its piece may be unpinned and the read may continue.
-  if (message?.type === Event.FRAGMENT_DONE) {
-    settleFragment(message.id);
-    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) });
-  }
-});
-
-/**
- * How often the piece store reports what it has been doing.
- *
- * The store decides whether a read costs nothing or costs a disk trip, and
- * until 2.9.75 nothing about it reached the log — a field oddity would have had
- * no evidence to work from. Reported only when something changed, so an idle
- * proxy stays quiet.
- */
-const STORE_REPORT_INTERVAL_MS = 60_000;
-
-/** Last reported figures per store, so unchanged ones stay silent. */
-const lastReported = new Map();
-
-setInterval(() => {
-  for (const stats of collectStoreStats()) {
-    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}`;
-    if (lastReported.get(stats.name) === signature) {
-      continue;
-    }
-    lastReported.set(stats.name, signature);
-
-    const reads = stats.fromMemory + stats.fromDisk;
-    const fromMemoryShare = reads > 0 ? ((stats.fromMemory / reads) * 100).toFixed(1) : "—";
-    log(
-      `piece-store "${stats.name.slice(0, 40)}": resident=${stats.resident}/${stats.capacity} ` +
-      `pinned=${stats.pinned} spilled=${stats.spilled} reads=${reads} (${fromMemoryShare}% from memory) ` +
-      `spills=${stats.spills} revivals=${stats.revivals}` +
-      (stats.blockedByPins > 0 ? ` blocked-by-pins=${stats.blockedByPins}` : "")
-    );
-  }
-}, STORE_REPORT_INTERVAL_MS).unref();
-
-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.
+ */
+
+// MUST stay first: it redirects `webrtc-polyfill` to a JavaScript WebRTC stack
+// before WebTorrent can reach the native one. Two isolates using
+// node-datachannel at once abort the process, and the torrent's wss trackers
+// create peer connections of their own.
+import "./install-webrtc-shim.js";
+import { parentPort, workerData } from "node:worker_threads";
+import { createSendStream } from "./channel.js";
+import { createFileClaims } from "./file-claims.js";
+import { readFragments } from "./piece-reader.js";
+import { Command, Event } from "./protocol.js";
+
+// Imported dynamically, and that is load-bearing: static imports are RESOLVED
+// during linking, before any module body runs, so a statically imported pool
+// would drag in WebTorrent — and with it the real `webrtc-polyfill` — before
+// the hook above had a chance to register. Verified the hard way: with a static
+// import the process still aborted, and the stack named the genuine polyfill.
+const { TorrentPool } = await import("../torrent-pool.js");
+const { collectStoreStats, findSharedStore } = await import("../piece-store/shared-piece-store.js");
+
+const pool = new TorrentPool({
+  maxDiskBytes: workerData?.maxDiskBytes,
+  memoryBytes: workerData?.memoryBytes
+});
+
+/** Torrents by sourceKey — the main thread names them, this thread owns them. */
+const torrentsByKey = new Map();
+/** File claims, each with its own identity — see `file-claims.js`. */
+const fileClaims = createFileClaims();
+/** 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, waiting for it if it is still being added.
+ *
+ * The map holds a PROMISE, registered the moment the add begins rather than
+ * when it finishes. That distinction is the whole fix: adding a magnet takes as
+ * long as its metadata does — seconds to tens of seconds — and until 2.9.77
+ * everything naming that source in the meantime was told `Unknown source`,
+ * which is false. The source exists; it is not ready. Reproduced with a magnet
+ * nobody seeds: stats, the file listing and a read all failed instantly while
+ * the add was still in flight, which on the loading screen shows up as no
+ * peers, no progress, and a plan request that fails before the torrent has had
+ * a chance to start.
+ *
+ * A source that was never added still throws, which is the honest answer.
+ *
+ * @param {string} sourceKey
+ * @returns {Promise<import("webtorrent").Torrent>}
+ */
+async function requireTorrent(sourceKey) {
+  const pending = torrentsByKey.get(sourceKey);
+  if (!pending) {
+    throw new Error(`Unknown source ${sourceKey}.`);
+  }
+  return pending;
+}
+
+/**
+ * Fragments waiting for the main thread to say it has finished reading them,
+ * keyed by request id. One per read, because only one fragment is in flight.
+ *
+ * @type {Map<number, () => void>}
+ */
+const fragmentWaiters = new Map();
+
+/**
+ * Wake a read that is waiting for a fragment to be confirmed.
+ *
+ * Used both by the confirmation itself and by cancellation — a cancelled read
+ * will never be confirmed, and without this it would wait forever holding a pin.
+ *
+ * @param {number} id
+ * @returns {void}
+ */
+function settleFragment(id) {
+  const done = fragmentWaiters.get(id);
+  if (done) {
+    fragmentWaiters.delete(id);
+    done();
+  }
+}
+
+/**
+ * Send one fragment's position and wait until the main thread is done with it.
+ *
+ * The pin is dropped only after the confirmation, because until then the other
+ * thread may still be reading those exact bytes.
+ *
+ * @param {number} id
+ * @param {import("./piece-reader.js").PieceFragment} fragment
+ * @returns {Promise<void>}
+ */
+function sendFragment(id, fragment) {
+  return new Promise((resolve) => {
+    fragmentWaiters.set(id, () => {
+      fragment.release();
+      resolve();
+    });
+    parentPort.postMessage({
+      type: Event.FRAGMENT,
+      id,
+      pieceIndex: fragment.pieceIndex,
+      offset: fragment.offset,
+      length: fragment.length
+    });
+  });
+}
+
+/**
+ * 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, windowBytes }) {
+  const torrent = await 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 rangeStart = start ?? 0;
+  const rangeEnd = end ?? file.length - 1;
+
+  let failed = false;
+  try {
+    // Positions in shared memory, not bytes: the main thread maps the same pool
+    // and reads each fragment in place, so nothing is copied and nothing is
+    // transferred. See `piece-reader.js`.
+    for await (const fragment of readFragments({
+      torrent,
+      fileIndex,
+      start: rangeStart,
+      end: rangeEnd,
+      cancellation: sender,
+      windowBytes
+    })) {
+      if (sender.isCancelled()) {
+        fragment.release();
+        break;
+      }
+      // One fragment in flight at a time. Each one holds a piece pinned, and
+      // the store guarantees only two resident pieces at its smallest budget —
+      // holding two pins while asking for a third would deadlock it against
+      // itself. The round trip costs ~100 µs against a piece worth megabytes,
+      // so there is nothing to win by overlapping them.
+      await sendFragment(id, fragment);
+    }
+  } catch (error) {
+    // The end-of-read marker means "the body is complete". Sending it after a
+    // failure told the reader the file simply ended — a truncated segment that
+    // ffmpeg reported as `Stream ends prematurely`, with the real cause thrown
+    // away. Let the error propagate instead; the command handler reports it and
+    // the main thread fails the stream.
+    failed = true;
+    throw error;
+  } finally {
+    readsById.delete(id);
+    // Any fragment still awaiting confirmation will never get one now; settling
+    // it here releases its pin rather than leaking a held slot.
+    settleFragment(id);
+    releaseRead();
+    if (!failed) {
+      sender.end();
+    }
+    // Nothing else to tear down: the reader owns no stream of its own, and a
+    // cancelled read stops at its next fragment boundary because it polls the
+    // same `sender` for cancellation.
+  }
+}
+
+/**
+ * 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: {
+      // Registered before it resolves, so anything naming this source while it
+      // is being added waits for it instead of being told it does not exist.
+      // Reusing the same promise for a repeated add also collapses two callers
+      // racing to open the same torrent into one.
+      let pending = torrentsByKey.get(params.sourceKey);
+      if (!pending) {
+        pending = pool.getTorrent(params.sourceType, params.source);
+        torrentsByKey.set(params.sourceKey, pending);
+        // A failed add must not be remembered, or every later attempt at this
+        // source replays the same failure. The handler also marks the rejection
+        // as observed, so it cannot surface as an unhandled one.
+        pending.catch(() => {
+          if (torrentsByKey.get(params.sourceKey) === pending) {
+            torrentsByKey.delete(params.sourceKey);
+          }
+        });
+      }
+      const torrent = await pending;
+      return {
+        infoHash: torrent.infoHash,
+        name: torrent.name,
+        // The piece pool itself. A `SharedArrayBuffer` crosses as a reference to
+        // the same memory rather than a copy, which is what lets the main thread
+        // read a piece where it already lies instead of being sent its bytes.
+        sharedBuffer: findSharedStore(torrent)?.sharedBuffer ?? null,
+        // 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 = await 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 = await requireTorrent(params.sourceKey);
+      // Every acquire is its own claim. Sharing one per file meant the first
+      // reader to finish released the hold while others were still reading.
+      return fileClaims.open(
+        params.sourceKey,
+        params.fileIndex,
+        pool.acquireFile(torrent, params.fileIndex)
+      );
+    }
+
+    case Command.RELEASE_FILE: {
+      const released = fileClaims.close(params.claimId);
+      if (!released) {
+        // Not fatal — but it means a release arrived twice or after teardown,
+        // and silence here is what let the previous scheme look healthy.
+        log(`release for unknown file claim ${params.claimId}`);
+      }
+      return released;
+    }
+
+    case Command.FILE_STATS: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return pool.getFileStats(torrent, params.fileIndex, {
+        resumeAnchorByteStart: params.resumeAnchorByteStart ?? null
+      });
+    }
+
+    case Command.PRIORITIZE: {
+      const torrent = await requireTorrent(params.sourceKey);
+      pool.prioritizeByteRange(torrent, params.fileIndex, params.byteStart, params.windowBytes, {
+        wholeFileRead: params.wholeFileRead === true
+      });
+      return true;
+    }
+
+    case Command.PREFETCH_EDGES: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return pool.prefetchFileEdges(torrent, params.fileIndex, params.options ?? {});
+    }
+
+    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,
+        windowBytes: params.windowBytes
+      });
+      return true;
+    }
+
+    case Command.CANCEL_READ: {
+      readsById.get(params.readId)?.cancel();
+      // A cancelled read will never have its outstanding fragment confirmed, so
+      // wake it here — otherwise it waits forever with a piece pinned.
+      settleFragment(params.readId);
+      return true;
+    }
+
+    case Command.DESTROY_ALL: {
+      fileClaims.closeAll();
+      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;
+  }
+
+  // The main thread has finished reading a fragment out of shared memory, so
+  // its piece may be unpinned and the read may continue.
+  if (message?.type === Event.FRAGMENT_DONE) {
+    settleFragment(message.id);
+    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) });
+  }
+});
+
+/**
+ * How often the piece store reports what it has been doing.
+ *
+ * The store decides whether a read costs nothing or costs a disk trip, and
+ * until 2.9.75 nothing about it reached the log — a field oddity would have had
+ * no evidence to work from. Reported only when something changed, so an idle
+ * proxy stays quiet.
+ */
+const STORE_REPORT_INTERVAL_MS = 60_000;
+
+/** Last reported figures per store, so unchanged ones stay silent. */
+const lastReported = new Map();
+
+setInterval(() => {
+  for (const stats of collectStoreStats()) {
+    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}`;
+    if (lastReported.get(stats.name) === signature) {
+      continue;
+    }
+    lastReported.set(stats.name, signature);
+
+    const reads = stats.fromMemory + stats.fromDisk;
+    const fromMemoryShare = reads > 0 ? ((stats.fromMemory / reads) * 100).toFixed(1) : "—";
+    log(
+      `piece-store "${stats.name.slice(0, 40)}": resident=${stats.resident}/${stats.capacity} ` +
+      `pinned=${stats.pinned} spilled=${stats.spilled} reads=${reads} (${fromMemoryShare}% from memory) ` +
+      `spills=${stats.spills} revivals=${stats.revivals}` +
+      (stats.blockedByPins > 0 ? ` blocked-by-pins=${stats.blockedByPins}` : "")
+    );
+  }
+}, STORE_REPORT_INTERVAL_MS).unref();
+
+log("torrent worker started");