@torrent-tv/proxy 2.9.126 → 2.9.128

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.9.127
+
+- **Fix**: A read that ends because the reader left is no longer reported as a failure. ffmpeg is terminated on every seek and whenever the look-ahead bound suspends it, and its connection closes with it, so `write ECANCELED` on the stream route is the ordinary end of a read — yet it was logged as a warning several times a minute through healthy playback. On 2026-08-09 it was read as the cause of broken audio, which it was not. The line now says whose end it was: a reader that disconnected is recorded at debug and says so, anything else stays a warning.
+
+## 2.9.127
+
+- **New**: A read that hands the file over out of order now says so. A sequential read walks forwards, so each fragment either continues the piece before it or moves to the very next one; anything else means the bytes reaching the decoder are not the file's bytes in order. Measured 2026-08-09 on a 1080p file with an AC-3 track: the encoder ran at 7.7-9.3x, produced its first segment in 9.1 s, reached 00:02:19 of 02:29:58 — and the AC-3 decoder reported "new coupling strategy must be present in block 0", "exponent 26 is out-of-range" and "invalid coupling range" while the piece store showed no spills and 100% of reads served from memory. Video was being COPIED in the same run, so the viewer lost the picture and the sound together: one fault, not two. The bounds check added in 2.9.126 catches a fragment outside the shared pool and stayed silent throughout, so the bytes came from the pool legitimately and belonged somewhere else. This names which piece arrived where.
+
 ## 2.9.126
 
 - **Fix**: A read whose offset lies outside its piece pool ends short and says so, instead of taking the whole source down without a word. The pool is a growable `SharedArrayBuffer` shared with the torrent thread, and an offset only means anything against the buffer of the store that produced it; when the two disagreed, building the view threw `RangeError: Invalid typed array length: 8388608` — one piece — which the process-wide handler swallowed. Reads then stopped answering for good. Measured 2026-08-09: ffmpeg was fed cut-up frames and reported them as a broken AC-3 stream ("new coupling strategy must be present in block 0"), no segment could be closed because no audio frames were produced, and segment #305 was held for a minute eight times running while 76 seeders delivered 35 MB/s. The file was fine; the reads were not. The log line now carries the offset, the length and the pool's size, so a recurrence names its own cause instead of being reconstructed from a decoder's complaints.

package/package.json

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

package/routes/stream/get.js

@@ -1,270 +1,283 @@
-/**
- * @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";
-import { logger } from "../../utils/logger.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 };
-}
-
-/**
- * How long a request may wait for a torrent that is still being added.
- *
- * Adding a magnet takes as long as its metadata does — seconds when peers
- * answer, forever when none do — and `getTorrent` waits for it. Awaiting that
- * with no bound is what made this route answer nothing at all.
- */
-const TORRENT_READY_TIMEOUT_MS = 10_000;
-
-/**
- * The torrent for a source, or a `TORRENT_NOT_READY` error once the wait has
- * gone on long enough to be worth reporting.
- *
- * The underlying add is NOT cancelled: it keeps running and warms the pool, so
- * the client's next attempt is likely to find it ready.
- *
- * @param {import("../../services/torrent-pool.js").TorrentPool} torrentPool
- * @param {string} sourceType
- * @param {string} source
- * @returns {Promise<import("webtorrent").Torrent>}
- */
-async function waitForTorrent(torrentPool, sourceType, source) {
-  let timer = null;
-  const expiry = new Promise((_resolve, reject) => {
-    timer = setTimeout(() => {
-      const error = new Error("Torrent metadata is not available yet.");
-      error.code = "TORRENT_NOT_READY";
-      reject(error);
-    }, TORRENT_READY_TIMEOUT_MS);
-    timer.unref?.();
-  });
-  try {
-    return await Promise.race([torrentPool.getTorrent(sourceType, source), expiry]);
-  } finally {
-    if (timer) {
-      clearTimeout(timer);
-    }
-  }
-}
-
-/**
- * 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 waitForTorrent(torrentPool, sourceType, source);
-  } catch (error) {
-    if (error instanceof Error && error.code === "TORRENT_NOT_READY") {
-      // Say so, rather than holding the connection until the client gives up.
-      // Reproduced 2026-08-04 on a magnet whose metadata never arrived: both a
-      // ranged GET and a HEAD returned nothing at all for the full 30 s the
-      // probe was willing to wait, and the route had written neither a status
-      // nor a header — from the client that is indistinguishable from the proxy
-      // having died, and it left no trace in the log either.
-      reply.header("Retry-After", "1");
-      return reply.code(503).send({ error: "Torrent metadata is not available yet." });
-    }
-    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.
-  // Only the encoder's own input read tracks where the viewer is. Everything
-  // else that comes through here — the codec probe, the keyframe index, a
-  // subtitle fetch — reads the file's edges, and treating those as a viewer
-  // position made every session start and every encoder restart look like a
-  // burst of seeks (measured: two spurious "the viewer moved" per start).
-  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0, undefined, {
-    wholeFileRead: range === null,
-    isPlaybackRead: req.query.reader === "playback"
-  });
-
-  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.
-  // How far ahead of its own read head this reader should ask the swarm for.
-  // Supplied by whoever knows the media's byte rate — the transcode session
-  // puts it on the ffmpeg input URL, sized in seconds of playback — because
-  // this thread knows only bytes, and 32 MB is half a minute of a 1080p film
-  // but four seconds of a disc remux. Absent or unusable, the reader's own
-  // default stands.
-  const windowBytesRaw = Number(req.query.windowBytes);
-  const windowBytes =
-    Number.isFinite(windowBytesRaw) && windowBytesRaw > 0 ? windowBytesRaw : undefined;
-
-  const fragments = typeof file.createFragmentReader === "function"
-    ? file.createFragmentReader({ start, end, windowBytes })
-    : 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());
-
-    let sent = 0;
-    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()));
-        });
-        sent += fragment.bytes.length;
-        // 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 (error) {
-      // The body is already committed by its headers, so there is nothing
-      // useful to send instead — drop the connection and let the client retry.
-      // But say why: swallowing this made the route close connections with no
-      // status and no trace, which from the client looks like the proxy died
-      // and from the log looks like nothing happened at all.
-      logger.warn(
-        `stream: read of "${file.name}" bytes ${start}-${end} failed after ` +
-        `${sent} of ${contentLength} bytes: ${error instanceof Error ? error.message : String(error)}`
-      );
-      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);
-}
+/**
+ * @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";
+import { logger } from "../../utils/logger.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 };
+}
+
+/**
+ * How long a request may wait for a torrent that is still being added.
+ *
+ * Adding a magnet takes as long as its metadata does — seconds when peers
+ * answer, forever when none do — and `getTorrent` waits for it. Awaiting that
+ * with no bound is what made this route answer nothing at all.
+ */
+const TORRENT_READY_TIMEOUT_MS = 10_000;
+
+/**
+ * The torrent for a source, or a `TORRENT_NOT_READY` error once the wait has
+ * gone on long enough to be worth reporting.
+ *
+ * The underlying add is NOT cancelled: it keeps running and warms the pool, so
+ * the client's next attempt is likely to find it ready.
+ *
+ * @param {import("../../services/torrent-pool.js").TorrentPool} torrentPool
+ * @param {string} sourceType
+ * @param {string} source
+ * @returns {Promise<import("webtorrent").Torrent>}
+ */
+async function waitForTorrent(torrentPool, sourceType, source) {
+  let timer = null;
+  const expiry = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error("Torrent metadata is not available yet.");
+      error.code = "TORRENT_NOT_READY";
+      reject(error);
+    }, TORRENT_READY_TIMEOUT_MS);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([torrentPool.getTorrent(sourceType, source), expiry]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * 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 waitForTorrent(torrentPool, sourceType, source);
+  } catch (error) {
+    if (error instanceof Error && error.code === "TORRENT_NOT_READY") {
+      // Say so, rather than holding the connection until the client gives up.
+      // Reproduced 2026-08-04 on a magnet whose metadata never arrived: both a
+      // ranged GET and a HEAD returned nothing at all for the full 30 s the
+      // probe was willing to wait, and the route had written neither a status
+      // nor a header — from the client that is indistinguishable from the proxy
+      // having died, and it left no trace in the log either.
+      reply.header("Retry-After", "1");
+      return reply.code(503).send({ error: "Torrent metadata is not available yet." });
+    }
+    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.
+  // Only the encoder's own input read tracks where the viewer is. Everything
+  // else that comes through here — the codec probe, the keyframe index, a
+  // subtitle fetch — reads the file's edges, and treating those as a viewer
+  // position made every session start and every encoder restart look like a
+  // burst of seeks (measured: two spurious "the viewer moved" per start).
+  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0, undefined, {
+    wholeFileRead: range === null,
+    isPlaybackRead: req.query.reader === "playback"
+  });
+
+  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.
+  // How far ahead of its own read head this reader should ask the swarm for.
+  // Supplied by whoever knows the media's byte rate — the transcode session
+  // puts it on the ffmpeg input URL, sized in seconds of playback — because
+  // this thread knows only bytes, and 32 MB is half a minute of a 1080p film
+  // but four seconds of a disc remux. Absent or unusable, the reader's own
+  // default stands.
+  const windowBytesRaw = Number(req.query.windowBytes);
+  const windowBytes =
+    Number.isFinite(windowBytesRaw) && windowBytesRaw > 0 ? windowBytesRaw : undefined;
+
+  const fragments = typeof file.createFragmentReader === "function"
+    ? file.createFragmentReader({ start, end, windowBytes })
+    : 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());
+
+    let sent = 0;
+    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()));
+        });
+        sent += fragment.bytes.length;
+        // 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 (error) {
+      // The body is already committed by its headers, so there is nothing
+      // useful to send instead — drop the connection and let the client retry.
+      // But say why: swallowing this made the route close connections with no
+      // status and no trace, which from the client looks like the proxy died
+      // and from the log looks like nothing happened at all.
+      // WHOSE end it was. A write cancelled because the consumer went away is
+      // the ordinary end of a read: ffmpeg is terminated on every seek and
+      // whenever the look-ahead bound suspends it, and its connection closes
+      // with it. Reported as a failure, that line fired several times a minute
+      // during healthy playback — and on 2026-08-09 it was read as the cause of
+      // broken audio, which it was not. A read that ends because the reader
+      // left is not a fault and must not be dressed as one; anything else is.
+      const message = error instanceof Error ? error.message : String(error);
+      const consumerLeft = req.raw.aborted || reply.raw.destroyed || /ECANCELED|EPIPE|ERR_STREAM_DESTROYED/.test(message);
+      const line =
+        `stream: read of "${file.name}" bytes ${start}-${end} ended after ` +
+        `${sent} of ${contentLength} bytes: ${message}`;
+      if (consumerLeft) {
+        logger.debug(`${line} (the reader disconnected — expected on an encoder restart)`);
+      } else {
+        logger.warn(line);
+      }
+      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/torrent-worker/client.js

@@ -37,6 +37,14 @@ export class TorrentWorkerClient {
   #caller;
   /** Receive-side handles for in-flight reads, keyed by request id. */
   #reads = new Map();
+
+  /**
+   * The last piece served to each open read, so a fragment arriving out of
+   * order can be named. Cleared when the read ends.
+   *
+   * @type {Map<number, number>}
+   */
+  #lastPieceByRead = 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. */
@@ -104,6 +112,25 @@ export class TorrentWorkerClient {
             this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
             break;
           }
+          // A sequential read walks the file forwards, so each fragment either
+          // continues the piece before it or moves to the very next one.
+          // Anything else means the bytes handed to the decoder are not the
+          // file's bytes in order — which is what a decoder complaining about
+          // its input has twice turned out to mean (2.9.126, and the AC-3
+          // failure of 2026-08-09: the encoder ran at 9.3x, the piece store
+          // reported no spills and 100% of reads from memory, and the decoder
+          // still saw "new coupling strategy must be present in block 0"). The
+          // bounds check catches a fragment outside the pool; this catches one
+          // inside it that belongs somewhere else.
+          const lastPiece = this.#lastPieceByRead.get(message.id);
+          if (lastPiece !== undefined && message.pieceIndex !== lastPiece && message.pieceIndex !== lastPiece + 1) {
+            logger.warn(
+              `torrent-worker: read ${message.id} jumped from piece ${lastPiece} to ` +
+              `${message.pieceIndex} (${message.length}B at pool offset ${message.offset}) — ` +
+              "the consumer is being handed the file out of order"
+            );
+          }
+          this.#lastPieceByRead.set(message.id, message.pieceIndex);
           const view = new Uint8Array(pool, message.offset, message.length);
 
           const reader = this.#fragmentReaders.get(message.id);
@@ -132,6 +159,7 @@ export class TorrentWorkerClient {
           break;
         }
         case Event.READ_END:
+          this.#lastPieceByRead.delete(message.id);
           this.#reads.get(message.id)?.close();
           this.#reads.delete(message.id);
           this.#fragmentReaders.get(message.id)?.close();
@@ -260,6 +288,7 @@ export class TorrentWorkerClient {
         void this.#caller.call(Command.CANCEL_READ, { readId }).catch(() => undefined);
         this.#reads.delete(readId);
         this.#poolByRead.delete(readId);
+        this.#lastPieceByRead.delete(readId);
       }
     });
     this.#reads.set(readId, receive);