@torrent-tv/proxy 2.9.77 → 2.9.79

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2.9.79
+
+- **New**: The last copy is gone from the read path. `/stream` now writes the response straight out of the torrent's shared memory and releases each piece only when the socket write reports completion — which is the one moment that is safe, because a piece released earlier can be evicted and its slot refilled while those exact bytes are still on their way out. Both halves of that were verified before being relied on: a socket accepts a view into a `SharedArrayBuffer`, and overwriting the pool from inside the write callback leaves the client's copy intact while overwriting it before the callback corrupts it silently. Measured on the same host, 24 MB of already-downloaded data read in 2 MB ranges: **298 ms against 1008 ms**, 675 Mbit/s against 200, and far steadier (265-308 ms against 641-1338). Callers that keep what they are given — the subtitle route, anything using the plain stream — still get a copy and are unaffected; a source with no shared pool falls back to the previous path.
+- **Chore**: Reading the response body by hand is what makes the release point observable, so the route writes and ends the response itself rather than handing Fastify a stream. A client that disconnects mid-response cancels the read, so pieces stop being fetched for a viewer who has gone.
+
+## 2.9.78
+
+- **New**: Reads cross the thread boundary as **positions instead of bytes**. The pieces already live in a `SharedArrayBuffer`, so the torrent thread now sends an offset and a length and the main thread reads those bytes where they lie. What this removes is the copy that used to sit on the critical path — 18.84 ms per 10 MB segment on the field host, spent in the same thread that runs the torrent, at the moment a viewer is waiting for that segment. A piece is **pinned** for as long as a fragment of it is outstanding, and unpinned only once the main thread confirms it has finished reading, so eviction cannot take the memory out from under a reader; one fragment is in flight at a time, because the store guarantees only two resident pieces at its smallest budget and holding two pins while asking for a third would deadlock it. Verified against a partially downloaded 5.5 GB torrent: a range read whole matches the same range read in parts, a read spanning a piece boundary matches its two halves, and ffmpeg parses the file through this path (`matroska h264/ac3 5939 s`). The arithmetic is covered by tests, including a file that does not start on a piece boundary — the case where treating file offsets as torrent offsets returns the right number of wrong bytes.
+- **Chore**: `SharedPieceStore` gained `reside`, which brings a piece into memory and reports where it sits without the copy `get` has to make (WebTorrent keeps what `get` returns), and `findSharedStore`, which walks WebTorrent's store wrappers to reach ours rather than assuming their number or order.
+- **Known**: the copy is not gone from the system, only from the torrent thread — the main thread still copies each fragment out of the pool before handing it on, because nothing tells us when the socket has finished with those bytes, and releasing the piece earlier would risk serving whatever landed in the slot next. Removing that last copy needs the body write to report completion, which is a change to the stream route rather than to this transport.
+
 ## 2.9.77
 
 - **Fix**: Anything naming a source while that source was still being added got `Unknown source` — which is false, because the source exists and is merely not ready. Adding a magnet takes as long as its metadata does, seconds to tens of seconds, and the browser polls stats and asks for a playback plan throughout that window. The worker registered the torrent only once the add had **finished**; it now registers the pending add itself, so callers wait for it. Reproduced with a magnet nobody seeds: stats, the file listing and a read all failed instantly while the add was in flight, and all three now wait. A source that was never added is still an error, and a failed add is forgotten rather than replayed to every later caller.

package/package.json

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

package/routes/stream/get.js

@@ -1,141 +1,192 @@
-/**
- * @file Byte-range aware torrent file streaming endpoint.
- *
- * Accepts either a `sourceKey` (registered via POST /api/sources) or a raw
- * `sourceType` + `source` pair.  Responds with HTTP 206 for range requests
- * and HTTP 200 for full-file requests.
- */
-
-import { parseRange } from "../../utils/parse-range.js";
-
-/**
- * Resolve source parameters from the query string.
- * Prefers a registered `sourceKey`; falls back to inline `sourceType`+`source`.
- *
- * @param {import("fastify").FastifyRequest["query"]} query
- * @param {ReturnType<import("../../store/source-registry.js").createSourceRegistry>} sourceRegistry
- * @returns {{ sourceType: string, source: string }}
- */
-function getSourceParams(query, sourceRegistry) {
-  const sourceKey = typeof query.sourceKey === "string" ? query.sourceKey : "";
-  const sourceTypeFromQuery = typeof query.sourceType === "string" ? query.sourceType : "";
-  const sourceFromQuery = typeof query.source === "string" ? query.source : "";
-
-  const sourceRecord = sourceKey ? sourceRegistry.get(sourceKey) : null;
-  const sourceType = sourceRecord?.sourceType ?? sourceTypeFromQuery;
-  const source = sourceRecord?.source ?? sourceFromQuery;
-  return { sourceType, source };
-}
-
-/**
- * Stream a torrent file over HTTP with byte-range support.
- *
- * GET /stream
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ sourceRegistry: ReturnType<import("../../store/source-registry.js").createSourceRegistry>, torrentPool: import("../../services/torrent-pool.js").TorrentPool }} deps
- * @returns {Promise<void>}
- */
-export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool }) {
-  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
-  const fileIndex = Number(fileIndexRaw);
-  const { sourceType, source } = getSourceParams(req.query, sourceRegistry);
-
-  if (!sourceType || !source || !Number.isInteger(fileIndex) || fileIndex < 0) {
-    return reply
-      .code(400)
-      .send({ error: "sourceKey or sourceType+source with fileIndex are required." });
-  }
-
-  let torrent;
-  try {
-    torrent = await torrentPool.getTorrent(sourceType, source);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return reply.code(500).send({ error: `Failed to load torrent source: ${message}` });
-  }
-
-  const file = torrent.files[fileIndex];
-  if (!file) {
-    return reply.code(404).send({ error: "File index was not found in torrent." });
-  }
-
-  // HEAD asks what a GET would return, not for the bytes. Fastify serves HEAD
-  // from this same handler, which used to mean a HEAD started a read of the
-  // WHOLE file: the body was discarded by Node, but the read ran on, the
-  // response never finished, and the next request on that keep-alive connection
-  // waited behind it. Measured on the field host: the keyframe-index HEAD
-  // returned headers in 23 ms and then held the connection until its 15 s
-  // timeout, which is where the 73 s transcode-session create went.
-  if (req.method === "HEAD") {
-    // Written to the raw response on purpose. Answering through `reply.send()`
-    // with no payload makes Fastify set `content-length: 0`, which is worse
-    // than useless here: the keyframe index asks for the file size with this
-    // very request and treats 0 as "no index available", silently falling back
-    // to an invented segment grid. Hijacking leaves the response to us, and
-    // Node omits the body for HEAD by itself.
-    reply.hijack();
-    reply.raw.writeHead(200, {
-      "Accept-Ranges": "bytes",
-      "Content-Type": "application/octet-stream",
-      "Content-Length": String(file.length),
-      "Content-Disposition": `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`
-    });
-    reply.raw.end();
-    return;
-  }
-
-  const releaseFile = torrentPool.acquireFile(torrent, fileIndex);
-
-  const range = parseRange(req.headers.range, file.length);
-  // Prioritize the pieces at this read position so a seek (a request at a new
-  // byte offset) downloads first instead of waiting behind the sequential
-  // backlog — this is what caused ~15-18 s stalls when seeking into an
-  // undownloaded region.
-  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0);
-  reply.header("Accept-Ranges", "bytes");
-  reply.header("Content-Type", "application/octet-stream");
-  reply.header("Content-Disposition", `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`);
-
-  if (!range) {
-    reply.header("Content-Length", String(file.length));
-    const stream = file.createReadStream();
-    bindRelease(stream, reply, releaseFile);
-    return reply.send(stream);
-  }
-
-  const contentLength = range.end - range.start + 1;
-  reply.code(206);
-  reply.header("Content-Length", String(contentLength));
-  reply.header("Content-Range", `bytes ${range.start}-${range.end}/${file.length}`);
-  const stream = file.createReadStream({ start: range.start, end: range.end });
-  bindRelease(stream, reply, releaseFile);
-  return reply.send(stream);
-}
-
-/**
- * Attach event listeners that release the file reference exactly once when
- * the stream or the underlying HTTP connection closes.
- *
- * @param {import("node:stream").Readable} stream
- * @param {import("fastify").FastifyReply} reply
- * @param {() => void} release
- * @returns {void}
- */
-function bindRelease(stream, reply, release) {
-  let released = false;
-  const releaseOnce = () => {
-    if (released) {
-      return;
-    }
-    released = true;
-    release();
-  };
-
-  stream.on("close", releaseOnce);
-  stream.on("end", releaseOnce);
-  stream.on("error", releaseOnce);
-  reply.raw.once("close", releaseOnce);
-  reply.raw.once("finish", releaseOnce);
-}
+/**
+ * @file Byte-range aware torrent file streaming endpoint.
+ *
+ * Accepts either a `sourceKey` (registered via POST /api/sources) or a raw
+ * `sourceType` + `source` pair.  Responds with HTTP 206 for range requests
+ * and HTTP 200 for full-file requests.
+ */
+
+import { parseRange } from "../../utils/parse-range.js";
+
+/**
+ * Resolve source parameters from the query string.
+ * Prefers a registered `sourceKey`; falls back to inline `sourceType`+`source`.
+ *
+ * @param {import("fastify").FastifyRequest["query"]} query
+ * @param {ReturnType<import("../../store/source-registry.js").createSourceRegistry>} sourceRegistry
+ * @returns {{ sourceType: string, source: string }}
+ */
+function getSourceParams(query, sourceRegistry) {
+  const sourceKey = typeof query.sourceKey === "string" ? query.sourceKey : "";
+  const sourceTypeFromQuery = typeof query.sourceType === "string" ? query.sourceType : "";
+  const sourceFromQuery = typeof query.source === "string" ? query.source : "";
+
+  const sourceRecord = sourceKey ? sourceRegistry.get(sourceKey) : null;
+  const sourceType = sourceRecord?.sourceType ?? sourceTypeFromQuery;
+  const source = sourceRecord?.source ?? sourceFromQuery;
+  return { sourceType, source };
+}
+
+/**
+ * Stream a torrent file over HTTP with byte-range support.
+ *
+ * GET /stream
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ sourceRegistry: ReturnType<import("../../store/source-registry.js").createSourceRegistry>, torrentPool: import("../../services/torrent-pool.js").TorrentPool }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool }) {
+  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
+  const fileIndex = Number(fileIndexRaw);
+  const { sourceType, source } = getSourceParams(req.query, sourceRegistry);
+
+  if (!sourceType || !source || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply
+      .code(400)
+      .send({ error: "sourceKey or sourceType+source with fileIndex are required." });
+  }
+
+  let torrent;
+  try {
+    torrent = await torrentPool.getTorrent(sourceType, source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return reply.code(500).send({ error: `Failed to load torrent source: ${message}` });
+  }
+
+  const file = torrent.files[fileIndex];
+  if (!file) {
+    return reply.code(404).send({ error: "File index was not found in torrent." });
+  }
+
+  // HEAD asks what a GET would return, not for the bytes. Fastify serves HEAD
+  // from this same handler, which used to mean a HEAD started a read of the
+  // WHOLE file: the body was discarded by Node, but the read ran on, the
+  // response never finished, and the next request on that keep-alive connection
+  // waited behind it. Measured on the field host: the keyframe-index HEAD
+  // returned headers in 23 ms and then held the connection until its 15 s
+  // timeout, which is where the 73 s transcode-session create went.
+  if (req.method === "HEAD") {
+    // Written to the raw response on purpose. Answering through `reply.send()`
+    // with no payload makes Fastify set `content-length: 0`, which is worse
+    // than useless here: the keyframe index asks for the file size with this
+    // very request and treats 0 as "no index available", silently falling back
+    // to an invented segment grid. Hijacking leaves the response to us, and
+    // Node omits the body for HEAD by itself.
+    reply.hijack();
+    reply.raw.writeHead(200, {
+      "Accept-Ranges": "bytes",
+      "Content-Type": "application/octet-stream",
+      "Content-Length": String(file.length),
+      "Content-Disposition": `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`
+    });
+    reply.raw.end();
+    return;
+  }
+
+  const releaseFile = torrentPool.acquireFile(torrent, fileIndex);
+
+  const range = parseRange(req.headers.range, file.length);
+  // Prioritize the pieces at this read position so a seek (a request at a new
+  // byte offset) downloads first instead of waiting behind the sequential
+  // backlog — this is what caused ~15-18 s stalls when seeking into an
+  // undownloaded region.
+  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0);
+
+  const start = range ? range.start : 0;
+  const end = range ? range.end : file.length - 1;
+  const contentLength = end - start + 1;
+
+  // Written straight out of the torrent's shared memory when that is available:
+  // no copy on either thread, at the cost of doing the writing by hand, because
+  // only the write callback tells us when a piece may be released. Falls back to
+  // the ordinary stream for sources without a shared pool.
+  const fragments = typeof file.createFragmentReader === "function"
+    ? file.createFragmentReader({ start, end })
+    : null;
+
+  if (fragments) {
+    reply.hijack();
+    reply.raw.writeHead(range ? 206 : 200, {
+      "Accept-Ranges": "bytes",
+      "Content-Type": "application/octet-stream",
+      "Content-Length": String(contentLength),
+      "Content-Disposition": `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`,
+      ...(range ? { "Content-Range": `bytes ${start}-${end}/${file.length}` } : {})
+    });
+
+    // A client that goes away mid-response must stop the read, or pieces keep
+    // being fetched for nobody.
+    reply.raw.once("close", () => fragments.cancel());
+
+    try {
+      for await (const fragment of fragments) {
+        if (reply.raw.writableEnded || reply.raw.destroyed) {
+          fragment.release();
+          break;
+        }
+        await new Promise((resolve, reject) => {
+          reply.raw.write(fragment.bytes, (error) => (error ? reject(error) : resolve()));
+        });
+        // Only now are these bytes gone: the piece can be unpinned, and the
+        // slot it occupies reused. Releasing before this point corrupts the
+        // response silently.
+        fragment.release();
+      }
+      reply.raw.end();
+    } catch {
+      // The body is already committed by its headers, so there is nothing
+      // useful to send instead — drop the connection and let the client retry.
+      reply.raw.destroy();
+    } finally {
+      releaseFile();
+    }
+    return;
+  }
+
+  reply.header("Accept-Ranges", "bytes");
+  reply.header("Content-Type", "application/octet-stream");
+  reply.header("Content-Disposition", `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`);
+
+  if (!range) {
+    reply.header("Content-Length", String(file.length));
+    const stream = file.createReadStream();
+    bindRelease(stream, reply, releaseFile);
+    return reply.send(stream);
+  }
+
+  reply.code(206);
+  reply.header("Content-Length", String(contentLength));
+  reply.header("Content-Range", `bytes ${start}-${end}/${file.length}`);
+  const stream = file.createReadStream({ start, end });
+  bindRelease(stream, reply, releaseFile);
+  return reply.send(stream);
+}
+
+/**
+ * Attach event listeners that release the file reference exactly once when
+ * the stream or the underlying HTTP connection closes.
+ *
+ * @param {import("node:stream").Readable} stream
+ * @param {import("fastify").FastifyReply} reply
+ * @param {() => void} release
+ * @returns {void}
+ */
+function bindRelease(stream, reply, release) {
+  let released = false;
+  const releaseOnce = () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    release();
+  };
+
+  stream.on("close", releaseOnce);
+  stream.on("end", releaseOnce);
+  stream.on("error", releaseOnce);
+  reply.raw.once("close", releaseOnce);
+  reply.raw.once("finish", releaseOnce);
+}

package/services/piece-store/shared-piece-store.js

@@ -51,6 +51,31 @@ export function collectStoreStats() {
   return [...liveStores].map((store) => store.stats());
 }
 
+/**
+ * The shared store behind a torrent, or `null` if it is not one of ours.
+ *
+ * WebTorrent wraps whatever store it is given — today in `ImmediateChunkStore`,
+ * and historically in a piece cache as well — and offers no way to ask for the
+ * innermost one. Walking the `store` chain finds it regardless of how many
+ * wrappers there are or what order they sit in, which is sturdier than reaching
+ * for a fixed `torrent.store.store`.
+ *
+ * @param {{ store?: object } | null | undefined} torrent
+ * @returns {SharedPieceStore | null}
+ */
+export function findSharedStore(torrent) {
+  let candidate = torrent?.store;
+  // Bounded rather than `while (candidate)`: a store that referenced itself
+  // would otherwise hang the thread instead of failing.
+  for (let depth = 0; candidate && depth < 8; depth += 1) {
+    if (candidate instanceof SharedPieceStore) {
+      return candidate;
+    }
+    candidate = candidate.store;
+  }
+  return null;
+}
+
 /**
  * Ceiling for the automatic budget, and the share of free memory it will take.
  *
@@ -389,6 +414,53 @@ export class SharedPieceStore {
     fetch().then((bytes) => done(null, bytes), (error) => done(error));
   }
 
+  /**
+   * Ensure a piece is in memory and say where it sits — without copying it.
+   *
+   * This is {@link get} minus its final copy, and it exists for exactly one
+   * caller: the reader that hands pieces to the other thread. That thread maps
+   * the same {@link sharedBuffer}, so an offset and a length are all it needs,
+   * and the bytes never move. `get` cannot serve that purpose because
+   * WebTorrent keeps what `get` returns while the slot underneath may be
+   * reused.
+   *
+   * The caller MUST hold a pin across the whole read — the returned offset
+   * stays valid only while the piece is pinned.
+   *
+   * @param {number} index
+   * @returns {Promise<{ offset: number, length: number } | null>} `null` when
+   *   the store holds no such piece, in memory or on disk.
+   */
+  async reside(index) {
+    if (this.#closed) {
+      throw new Error("Piece store is closed.");
+    }
+
+    const slot = this.#slotOf.get(index);
+    if (slot !== undefined) {
+      this.#lru.touch(index);
+      this.#counters.fromMemory += 1;
+      return this.locate(index);
+    }
+
+    if (!this.#disk.has(index)) {
+      return null;
+    }
+
+    const pieceLength = this.#lengthOf(index);
+    const revived = await this.#claimSlot();
+    const target = this.#pool.subarray(
+      revived * this.#chunkLength,
+      revived * this.#chunkLength + pieceLength
+    );
+    await this.#disk.read(index, target);
+    this.#slotOf.set(index, revived);
+    this.#lru.touch(index);
+    this.#counters.fromDisk += 1;
+    this.#counters.revivals += 1;
+    return this.locate(index);
+  }
+
   /**
    * Close the store, keeping the spill file.
    *

package/services/torrent-worker/client.js

@@ -37,6 +37,12 @@ export class TorrentWorkerClient {
   #caller;
   /** Receive-side handles for in-flight reads, keyed by request id. */
   #reads = new Map();
+  /** Each torrent's piece pool, so a fragment can be read where it lies. */
+  #poolBySource = new Map();
+  /** Which pool an in-flight read belongs to, keyed by request id. */
+  #poolByRead = new Map();
+  /** Reads consuming fragments in place, keyed by request id. */
+  #fragmentReaders = new Map();
 
   /**
    * @param {{ maxDiskBytes?: number, memoryBytes?: number }} [options]
@@ -60,10 +66,45 @@ export class TorrentWorkerClient {
         read.fail(new Error(message.error ?? "Torrent worker read failed."));
         return;
       }
+      if (message?.type === Event.ERROR && this.#fragmentReaders.has(message.id)) {
+        const reader = this.#fragmentReaders.get(message.id);
+        this.#fragmentReaders.delete(message.id);
+        this.#poolByRead.delete(message.id);
+        reader.fail(new Error(message.error ?? "Torrent worker read failed."));
+        return;
+      }
       if (this.#caller.handleReply(message)) {
         return;
       }
       switch (message?.type) {
+        case Event.FRAGMENT: {
+          const pool = this.#poolByRead.get(message.id);
+          if (!pool) {
+            // No pool means no way to read the fragment; confirm it so the
+            // worker is not left waiting, and let the read end short.
+            this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
+            break;
+          }
+          const view = new Uint8Array(pool, message.offset, message.length);
+
+          const reader = this.#fragmentReaders.get(message.id);
+          if (reader) {
+            // Handed on as a view into the pool — no copy anywhere. The piece
+            // stays pinned until the consumer says it is done with these exact
+            // bytes, which for a response body means the socket write has
+            // completed.
+            reader.push(view, () => {
+              this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
+            });
+            break;
+          }
+
+          // Plain-stream consumers keep what they are given while the slot may
+          // be reused, so they get a copy and the piece is released at once.
+          this.#reads.get(message.id)?.push(Uint8Array.prototype.slice.call(view));
+          this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
+          break;
+        }
         case Event.CHUNK: {
           const bytes = message.bytes;
           this.#reads.get(message.id)?.push(
@@ -74,6 +115,9 @@ export class TorrentWorkerClient {
         case Event.READ_END:
           this.#reads.get(message.id)?.close();
           this.#reads.delete(message.id);
+          this.#fragmentReaders.get(message.id)?.close();
+          this.#fragmentReaders.delete(message.id);
+          this.#poolByRead.delete(message.id);
           break;
         case Event.LOG:
           logger.info(`torrent-worker: ${message.message}`);
@@ -190,9 +234,16 @@ export class TorrentWorkerClient {
       onCancel: () => {
         void this.#caller.call(Command.CANCEL_READ, { readId }).catch(() => undefined);
         this.#reads.delete(readId);
+        this.#poolByRead.delete(readId);
       }
     });
     this.#reads.set(readId, receive);
+    // Which pool this read's fragments will point into. Recorded before the
+    // command is sent, because the first fragment can arrive immediately.
+    const pool = this.#poolBySource.get(sourceKey);
+    if (pool) {
+      this.#poolByRead.set(readId, pool);
+    }
 
     // The worker replies to READ_RANGE only once the body is fully sent; a
     // failure before that must surface on the stream, not vanish.
@@ -205,6 +256,104 @@ export class TorrentWorkerClient {
     return receive.stream;
   }
 
+  /**
+   * Read a byte range as fragments of shared memory, without copying.
+   *
+   * Each fragment is a view straight into the torrent's piece pool, and the
+   * piece behind it stays pinned until `release()` is called — so the consumer
+   * must call it once it is genuinely finished with those bytes. For a response
+   * body that means after the socket write has completed, not when it was
+   * queued: verified that writing a shared-memory view and then overwriting the
+   * pool from the write callback leaves the client's copy intact, and that
+   * overwriting it earlier corrupts it silently.
+   *
+   * Returns `null` when this source has no shared pool, so the caller can fall
+   * back to {@link createReadStream}.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, start?: number | null, end?: number | null }} params
+   * @returns {{ [Symbol.asyncIterator]: () => AsyncGenerator<{ bytes: Uint8Array, release: () => void }>, cancel: () => void } | null}
+   */
+  createFragmentReader({ sourceKey, fileIndex, start = null, end = null }) {
+    const pool = this.#poolBySource.get(sourceKey);
+    if (!pool) {
+      return null;
+    }
+
+    const readId = this.#caller.nextId();
+    /** @type {{ bytes: Uint8Array, release: () => void }[]} */
+    const queue = [];
+    let wake = null;
+    let finished = false;
+    let failure = null;
+
+    const notify = () => {
+      const resume = wake;
+      wake = null;
+      resume?.();
+    };
+
+    this.#fragmentReaders.set(readId, {
+      push(bytes, confirm) {
+        queue.push({ bytes, release: confirm });
+        notify();
+      },
+      close() {
+        finished = true;
+        notify();
+      },
+      fail(error) {
+        failure = error;
+        finished = true;
+        notify();
+      }
+    });
+    this.#poolByRead.set(readId, pool);
+
+    const cancel = () => {
+      if (this.#fragmentReaders.delete(readId)) {
+        this.#poolByRead.delete(readId);
+        void this.#caller.call(Command.CANCEL_READ, { readId }).catch(() => undefined);
+      }
+      finished = true;
+      notify();
+    };
+
+    this.#worker.postMessage({
+      command: Command.READ_RANGE,
+      id: readId,
+      params: { sourceKey, fileIndex, start, end }
+    });
+
+    return {
+      cancel,
+      async *[Symbol.asyncIterator]() {
+        try {
+          for (;;) {
+            while (queue.length > 0) {
+              yield queue.shift();
+            }
+            if (failure) {
+              throw failure;
+            }
+            if (finished) {
+              return;
+            }
+            await new Promise((resolve) => {
+              wake = resolve;
+            });
+          }
+        } finally {
+          // Covers the consumer breaking out early — a client that hung up, a
+          // superseded seek — which must stop the read rather than leave it
+          // fetching pieces nobody will take.
+          if (!finished) {
+            cancel();
+          }
+        }
+      }
+    };
+  }
+
   /**
    * A stand-in for the WebTorrent torrent object, backed by the worker.
    *
@@ -224,6 +373,11 @@ export class TorrentWorkerClient {
    */
   async getTorrent({ sourceKey, sourceType, source }) {
     const info = await this.addSource({ sourceKey, sourceType, source });
+    // The torrent's piece pool. Both threads now hold the same memory, so a
+    // read can be answered with an offset instead of with bytes.
+    if (info.sharedBuffer) {
+      this.#poolBySource.set(sourceKey, info.sharedBuffer);
+    }
     const client = this;
     return {
       infoHash: info.infoHash,
@@ -250,6 +404,22 @@ export class TorrentWorkerClient {
               end: options.end ?? null
             })
           );
+        },
+
+        /**
+         * Fragments of shared memory, for a caller that can say when it has
+         * finished with each one. `null` when this source has no shared pool.
+         *
+         * @param {{ start?: number, end?: number }} [options]
+         * @returns {ReturnType<TorrentWorkerClient["createFragmentReader"]>}
+         */
+        createFragmentReader(options = {}) {
+          return client.createFragmentReader({
+            sourceKey,
+            fileIndex: file.index,
+            start: options.start ?? null,
+            end: options.end ?? null
+          });
         }
       }))
     };

package/services/torrent-worker/piece-reader.js

@@ -0,0 +1,175 @@
+/**
+ * @file Reading a byte range as positions in shared memory, not as bytes.
+ *
+ * The pieces already live in a `SharedArrayBuffer` the main thread can map. So
+ * the torrent thread does not need to hand over any bytes at all: it can say
+ * *where* a piece sits and let the other side read it there. What crosses the
+ * boundary is two numbers per piece.
+ *
+ * That is the whole point of the exercise. The alternative — copying each piece
+ * into memory we own and transferring it — costs 18.84 ms per 10 MB segment on
+ * the field host, and costs it **on the critical path**, in the thread that is
+ * also running the torrent, at the moment a viewer is waiting for that segment.
+ * Here the copy is gone entirely rather than moved.
+ *
+ * Two obligations come with it, and both are enforced rather than assumed:
+ *
+ *  - a piece being read is **pinned**, so eviction cannot take the memory out
+ *    from under the reader mid-read;
+ *  - the pin is released only once the other thread reports it has finished
+ *    with those bytes — not when they were sent, because nothing was sent.
+ */
+
+import { findSharedStore } from "../piece-store/shared-piece-store.js";
+
+/**
+ * Wait until a piece has been downloaded and verified.
+ *
+ * WebTorrent announces this as `verified`. The bitfield is re-checked after the
+ * listener is attached because the piece can complete in between, and a missed
+ * event here would wait forever.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {number} index
+ * @param {{ isCancelled: () => boolean }} cancellation
+ * @returns {Promise<void>}
+ */
+function whenPieceReady(torrent, index, cancellation) {
+  if (torrent.bitfield?.get(index)) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve, reject) => {
+    /** @param {number} verifiedIndex */
+    const onVerified = (verifiedIndex) => {
+      if (verifiedIndex === index) {
+        cleanup();
+        resolve();
+      }
+    };
+    const onDestroyed = () => {
+      cleanup();
+      reject(new Error(`Torrent went away while waiting for piece ${index}.`));
+    };
+    // Cancellation is polled rather than pushed: a superseded seek destroys the
+    // read, and without this the wait would outlive it and hold a pin.
+    const poll = setInterval(() => {
+      if (cancellation.isCancelled()) {
+        cleanup();
+        reject(new Error(`Read cancelled while waiting for piece ${index}.`));
+      }
+    }, 250);
+
+    function cleanup() {
+      clearInterval(poll);
+      torrent.removeListener("verified", onVerified);
+      torrent.removeListener("close", onDestroyed);
+    }
+
+    torrent.on("verified", onVerified);
+    torrent.once("close", onDestroyed);
+
+    // The piece may have arrived between the check above and this listener.
+    if (torrent.bitfield?.get(index)) {
+      cleanup();
+      resolve();
+    }
+  });
+}
+
+/**
+ * A fragment of a read: where to find it, and how to let it go.
+ *
+ * @typedef {object} PieceFragment
+ * @property {number} pieceIndex
+ * @property {number} offset - Byte offset into the shared pool.
+ * @property {number} length
+ * @property {() => void} release - Drops this fragment's pin. Call exactly once.
+ */
+
+/**
+ * Walk a byte range of a file, yielding each piece's position in shared memory.
+ *
+ * Yields at most one fragment per piece; the first and last are usually partial.
+ * The caller must `release()` every fragment it receives, including on failure —
+ * an unreleased pin permanently costs a slot.
+ *
+ * @param {object} params
+ * @param {import("webtorrent").Torrent} params.torrent
+ * @param {number} params.fileIndex
+ * @param {number} params.start - Inclusive, relative to the file.
+ * @param {number} params.end - Inclusive, relative to the file.
+ * @param {{ isCancelled: () => boolean }} params.cancellation
+ * @returns {AsyncGenerator<PieceFragment>}
+ */
+export async function* readFragments({ torrent, fileIndex, start, end, cancellation }) {
+  const store = findSharedStore(torrent);
+  if (!store) {
+    throw new Error("This torrent is not backed by a shared piece store.");
+  }
+
+  const file = torrent.files?.[fileIndex];
+  if (!file) {
+    throw new Error(`File ${fileIndex} not found.`);
+  }
+
+  const pieceLength = torrent.pieceLength;
+  // Piece numbers are torrent-wide, so a file's own offsets have to be lifted
+  // into the torrent's address space first.
+  const absoluteStart = file.offset + start;
+  const absoluteEnd = file.offset + end;
+  const firstPiece = Math.floor(absoluteStart / pieceLength);
+  const lastPiece = Math.floor(absoluteEnd / pieceLength);
+
+  // Ask for these pieces first. `select` puts them in the download set at all;
+  // `critical` marks them as wanted now, which is what allows a piece to be
+  // fetched out of sequential order for a reader that is waiting on it.
+  if (typeof torrent.select === "function") {
+    torrent.select(firstPiece, lastPiece, 1);
+  }
+  if (typeof torrent.critical === "function") {
+    torrent.critical(firstPiece, lastPiece);
+  }
+
+  for (let pieceIndex = firstPiece; pieceIndex <= lastPiece; pieceIndex += 1) {
+    if (cancellation.isCancelled()) {
+      return;
+    }
+
+    const pieceStart = pieceIndex * pieceLength;
+    const fromWithinPiece = Math.max(absoluteStart, pieceStart) - pieceStart;
+    const toWithinPiece = Math.min(absoluteEnd, pieceStart + pieceLength - 1) - pieceStart;
+
+    await whenPieceReady(torrent, pieceIndex, cancellation);
+
+    // Pinned BEFORE it is located, and before any await that could let an
+    // eviction run: the offset is only meaningful while the piece is held.
+    store.pin(pieceIndex);
+    let located = null;
+    try {
+      located = await store.reside(pieceIndex);
+    } catch (error) {
+      store.unpin(pieceIndex);
+      throw error;
+    }
+
+    if (!located) {
+      store.unpin(pieceIndex);
+      throw new Error(`Piece ${pieceIndex} is verified but absent from the store.`);
+    }
+
+    let releasedThisPiece = false;
+    yield {
+      pieceIndex,
+      offset: located.offset + fromWithinPiece,
+      length: toWithinPiece - fromWithinPiece + 1,
+      release() {
+        if (releasedThisPiece) {
+          return;
+        }
+        releasedThisPiece = true;
+        store.unpin(pieceIndex);
+      }
+    };
+  }
+}

package/services/torrent-worker/protocol.js

@@ -80,6 +80,18 @@ export const Event = {
   ERROR: "error",
   /** One piece of a READ_RANGE body; its bytes are transferred, never copied. */
   CHUNK: "chunk",
+  /**
+   * Where a piece of the body sits in the torrent's shared pool — an offset and
+   * a length, no bytes at all. The main thread maps the same memory and reads it
+   * in place; see `piece-reader.js` for why this replaces sending the bytes.
+   */
+  FRAGMENT: "fragment",
+  /**
+   * The main thread has finished with a FRAGMENT and its pin may be dropped.
+   * Distinct from {@link CHUNK_ACK}, which only reports queue capacity: this one
+   * is a promise that nothing is reading those bytes any more.
+   */
+  FRAGMENT_DONE: "fragment-done",
   /** 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}. */

package/services/torrent-worker/worker.js

@@ -25,7 +25,8 @@ import "./install-webrtc-shim.js";
 import { parentPort, workerData } from "node:worker_threads";
 import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
-import { Command, Event, STREAM_CHUNK_BYTES } from "./protocol.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
@@ -33,7 +34,7 @@ import { Command, Event, STREAM_CHUNK_BYTES } from "./protocol.js";
 // 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 } = await import("../piece-store/shared-piece-store.js");
+const { collectStoreStats, findSharedStore } = await import("../piece-store/shared-piece-store.js");
 
 const pool = new TorrentPool({
   maxDiskBytes: workerData?.maxDiskBytes,
@@ -84,6 +85,57 @@ async function requireTorrent(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.
  *
@@ -120,39 +172,31 @@ async function streamRange({ id, sourceKey, fileIndex, start, end }) {
   // 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);
-  };
+  const rangeStart = start ?? 0;
+  const rangeEnd = end ?? file.length - 1;
 
   let failed = false;
   try {
-    for await (const part of source) {
+    // 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;
       }
-      pendingParts.push(part);
-      pendingBytes += part.length;
-      if (pendingBytes >= STREAM_CHUNK_BYTES) {
-        await flush();
-      }
-    }
-    if (!sender.isCancelled()) {
-      await flush();
+      // 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
@@ -164,15 +208,16 @@ async function streamRange({ id, sourceKey, fileIndex, start, end }) {
     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();
     }
-    // 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();
-    }
+    // 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.
   }
 }
 
@@ -208,6 +253,10 @@ async function runCommand(command, params, id) {
       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,
@@ -282,6 +331,9 @@ async function runCommand(command, params, id) {
 
     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;
     }
 
@@ -305,6 +357,13 @@ parentPort.on("message", async (message) => {
     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);

package/test/piece-reader.test.js

@@ -0,0 +1,162 @@
+/**
+ * @file Turning a byte range into positions in shared memory.
+ *
+ * This arithmetic fails silently when it is wrong: the response comes back the
+ * right length and full of the wrong bytes. Piece numbers are torrent-wide
+ * while a read is expressed in file coordinates, and the first and last pieces
+ * of a range are almost always partial — so every case here is a boundary.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { readFragments } from "../services/torrent-worker/piece-reader.js";
+import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+const PIECE = 1024;
+
+/**
+ * A torrent whose pieces are all present, backed by a real store so that
+ * `locate`/`reside`/`pin` behave as they do in production.
+ *
+ * @param {{ fileOffset: number, fileLength: number, totalLength: number }} shape
+ */
+async function fakeTorrent({ fileOffset, fileLength, totalLength }) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "piece-reader-test-"));
+  const store = new SharedPieceStore(PIECE, {
+    length: totalLength,
+    memoryBytes: 64 * PIECE,
+    path: directory,
+    name: "test"
+  });
+
+  const pieceCount = Math.ceil(totalLength / PIECE);
+  for (let index = 0; index < pieceCount; index += 1) {
+    const length = index === pieceCount - 1 ? totalLength - index * PIECE : PIECE;
+    const piece = Buffer.alloc(length);
+    // Each byte encodes its own absolute position, so a misplaced offset is
+    // visible in the value itself rather than only in the length.
+    for (let at = 0; at < length; at += 1) {
+      piece[at] = (index * PIECE + at) % 251;
+    }
+    await new Promise((resolve, reject) => {
+      store.put(index, piece, (error) => (error ? reject(error) : resolve()));
+    });
+  }
+
+  const torrent = Object.assign(new EventEmitter(), {
+    pieceLength: PIECE,
+    store,
+    bitfield: { get: () => true },
+    files: [{ offset: fileOffset, length: fileLength, name: "file.bin" }],
+    select() {},
+    critical() {}
+  });
+
+  return { torrent, store, directory };
+}
+
+/** Collect a range through the reader, as the worker does. */
+async function readRange(torrent, start, end) {
+  const collected = [];
+  const positions = [];
+  const pool = Buffer.from(torrent.store.sharedBuffer);
+  for await (const fragment of readFragments({
+    torrent,
+    fileIndex: 0,
+    start,
+    end,
+    cancellation: { isCancelled: () => false }
+  })) {
+    collected.push(Buffer.from(pool.subarray(fragment.offset, fragment.offset + fragment.length)));
+    positions.push({ piece: fragment.pieceIndex, length: fragment.length });
+    fragment.release();
+  }
+  return { bytes: Buffer.concat(collected), positions };
+}
+
+/** What the bytes at an absolute torrent offset should be. */
+function expectedBytes(absoluteStart, length) {
+  const expected = Buffer.alloc(length);
+  for (let at = 0; at < length; at += 1) {
+    expected[at] = (absoluteStart + at) % 251;
+  }
+  return expected;
+}
+
+test("a range inside one piece is read from that piece only", async () => {
+  const { torrent, store, directory } = await fakeTorrent({
+    fileOffset: 0,
+    fileLength: 4 * PIECE,
+    totalLength: 4 * PIECE
+  });
+  try {
+    const { bytes, positions } = await readRange(torrent, 100, 199);
+    assert.equal(positions.length, 1);
+    assert.deepEqual(bytes, expectedBytes(100, 100));
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a range spanning pieces reassembles in order", async () => {
+  const { torrent, store, directory } = await fakeTorrent({
+    fileOffset: 0,
+    fileLength: 4 * PIECE,
+    totalLength: 4 * PIECE
+  });
+  try {
+    const start = PIECE - 10;
+    const end = 2 * PIECE + 9;
+    const { bytes, positions } = await readRange(torrent, start, end);
+    assert.deepEqual(positions.map((entry) => entry.piece), [0, 1, 2]);
+    assert.deepEqual(bytes, expectedBytes(start, end - start + 1));
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a file that does not start at a piece boundary is still read correctly", async () => {
+  // The usual case in a multi-file torrent, and the one where using file
+  // offsets as if they were torrent offsets returns the wrong bytes at the
+  // right length.
+  const fileOffset = PIECE + 300;
+  const { torrent, store, directory } = await fakeTorrent({
+    fileOffset,
+    fileLength: 2 * PIECE,
+    totalLength: 5 * PIECE
+  });
+  try {
+    const { bytes } = await readRange(torrent, 0, 1499);
+    assert.deepEqual(bytes, expectedBytes(fileOffset, 1500));
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("every fragment releases its pin, so nothing stays held", async () => {
+  const { torrent, store, directory } = await fakeTorrent({
+    fileOffset: 0,
+    fileLength: 4 * PIECE,
+    totalLength: 4 * PIECE
+  });
+  try {
+    await readRange(torrent, 0, 4 * PIECE - 1);
+    // With every piece unpinned the store can still make room; if a pin leaked
+    // it would eventually refuse.
+    const before = store.stats().blockedByPins;
+    for (let index = 0; index < 200; index += 1) {
+      await store.reside(index % 4);
+    }
+    assert.equal(store.stats().blockedByPins, before, "a pin was left behind");
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/test/worker-channel.test.js

@@ -156,6 +156,11 @@ test("a read of an unknown source fails the stream rather than hanging", async (
   // the reader waited forever. A unit test on either half alone passes happily.
   const client = new TorrentWorkerClient({ memoryBytes: 8 * 1024 * 1024 });
   try {
+    // Starting the worker takes several seconds — it builds a torrent client
+    // and a DHT — so the first request would measure startup, not the failure
+    // path under test.
+    await client.listFiles("warm-up").catch(() => undefined);
+
     const stream = client.createReadStream({ sourceKey: "no-such-source", fileIndex: 0 });
     const reader = stream.getReader();