@torrent-tv/proxy 2.9.127 → 2.9.129

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.9.129
+
+- **New**: A held segment says why it is held. A hold was silent, and that silence has now cost three releases: a file that exists, a route answering "not yet", and nothing saying which of the several reasons applied. Measured 2026-08-09 — a run begun mid-file at segment #317 produced two minutes of video from #317 upwards at 10.5x while #317 itself was held for 46 116 ms and then answered 404, once the browser had already given up. At most once every five seconds per file it now names the reason (not on disk, or present but the next segment has not been started), together with the index the run began at, where the viewer is, and whether the encoder is alive. The readiness rule — a segment counts as finished once the NEXT one exists — is the suspect for a resume, because for the first segment of a mid-file run that rule decides whether playback begins at all.
+
+## 2.9.128
+
+- **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.127",
+  "version": "2.9.129",
   "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);
+}