@torrent-tv/proxy 2.90.0 → 2.92.0

package/services/torrent/worker/channel.js

@@ -12,6 +12,13 @@
 
 import { Event, STREAM_HIGH_WATER_CHUNKS } from "./protocol.js";
 
+/** Preserve terminal source state when a failure crosses the thread boundary. */
+export function workerReplyError(message, fallback = "Torrent worker request failed.") {
+  const error = new Error(message.error ?? fallback);
+  if (typeof message.code === "string") error.code = message.code;
+  return error;
+}
+
 /**
  * Issue request ids that stay unique for the life of a thread.
  *
@@ -77,7 +84,7 @@ export function createCaller(port) {
       }
       if (message.type === Event.ERROR) {
         pending.delete(message.id);
-        entry.reject(new Error(message.error ?? "Torrent worker request failed."));
+        entry.reject(workerReplyError(message));
         return true;
       }
       return false;

package/services/torrent/worker/client.js

@@ -19,7 +19,7 @@ import { Readable } from "node:stream";
 import { open } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { logger, writeAlreadyDecided } from "../../../utils/logger.js";
-import { createCaller, createReceiveStream } from "./channel.js";
+import { createCaller, createReceiveStream, workerReplyError } from "./channel.js";
 import { Command, Event } from "./protocol.js";
 
 const WORKER_URL = new URL("./worker.js", import.meta.url);
@@ -110,11 +110,12 @@ export class TorrentWorkerClient {
   /** @type {(event: { sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string }) => void} */
   /** @type {(event: { sourceKey: string, fileIndexes: number[] }) => void} */
   #onPiecesArrived;
+  #onSourceForgotten;
 
   /**
    * @param {{ memoryBytes?: number, stateDir?: string, onPiecesArrived?: (event: object) => void }} [options]
    */
-  constructor({ memoryBytes, stateDir, onPiecesArrived } = {}) {
+  constructor({ memoryBytes, stateDir, onPiecesArrived, onSourceForgotten } = {}) {
     this.#worker = new Worker(fileURLToPath(WORKER_URL), {
       // `stateDir` travels because the worker writes heap snapshots of its own
       // isolate there. It cannot choose a directory any other way: a worker may
@@ -124,6 +125,7 @@ export class TorrentWorkerClient {
     });
     this.#caller = createCaller(this.#worker);
     this.#onPiecesArrived = onPiecesArrived ?? (() => undefined);
+    this.#onSourceForgotten = onSourceForgotten ?? (() => undefined);
 
     this.#worker.on("message", (message) => {
       // A failed read must fail its stream. This is checked BEFORE the caller
@@ -135,13 +137,13 @@ export class TorrentWorkerClient {
       if (message?.type === Event.ERROR && this.#reads.has(message.id)) {
         const read = this.#reads.get(message.id);
         this.#reads.delete(message.id);
-        read.fail(new Error(message.error ?? "Torrent worker read failed."));
+        read.fail(workerReplyError(message, "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);
-        reader.fail(new Error(message.error ?? "Torrent worker read failed."));
+        reader.fail(workerReplyError(message, "Torrent worker read failed."));
         return;
       }
       if (this.#caller.handleReply(message)) {
@@ -233,13 +235,20 @@ export class TorrentWorkerClient {
             length: message.length,
             name: message.name
           });
+          this.#onPiecesArrived({ sourceKey: message.sourceKey ?? `torrent:${message.infoHash}`,
+            fileIndexes: [message.fileIndex], reason: "file-complete" });
+          break;
+        case Event.SOURCE_FORGOTTEN:
+          this.#onSourceForgotten({ sourceKey: message.sourceKey });
           break;
         case Event.PIECES_ARRIVED:
+        case Event.PIECES_CHANGED:
           // ANNOUNCED by the thread that owns the swarm, acted on here: the
           // subtitle walk is this thread's and needs to know a piece arrived.
           this.#onPiecesArrived({
             sourceKey: message.sourceKey,
-            fileIndexes: Array.isArray(message.fileIndexes) ? message.fileIndexes : []
+              fileIndexes: Array.isArray(message.fileIndexes) ? message.fileIndexes : [],
+              ...(typeof message.reason === "string" ? { reason: message.reason } : {})
           });
           break;
         default:
@@ -323,11 +332,11 @@ export class TorrentWorkerClient {
   /**
    * Live download figures for the progress display.
    *
-   * @param {{ sourceKey: string, fileIndex: number, resumeAnchorByteStart?: number | null }} params
+   * @param {{ sourceKey: string, fileIndex: number }} params
    * @returns {Promise<object>}
    */
-  async getFileStats({ sourceKey, fileIndex, resumeAnchorByteStart = null }) {
-    return this.#caller.call(Command.FILE_STATS, { sourceKey, fileIndex, resumeAnchorByteStart });
+  async getFileStats({ sourceKey, fileIndex, forecast = false }) {
+    return this.#caller.call(Command.FILE_STATS, { sourceKey, fileIndex, forecast });
   }
 
   /**
@@ -340,22 +349,6 @@ export class TorrentWorkerClient {
 
 
 
-  /**
-   * Start fetching the region a viewer is about to resume at.
-   *
-   * @param {{ sourceKey: string, fileIndex: number, positionSeconds: number }} params
-   * @returns {Promise<{ started: boolean }>}
-   */
-  /**
-   * Fetch one whole file in the room the viewer's own reading leaves.
-   *
-   * @param {{ sourceKey: string, fileIndex: number }} params
-   * @returns {Promise<{ started: boolean }>}
-   */
-  async fillFile({ sourceKey, fileIndex }) {
-    return this.#caller.call(Command.FILL_FILE, { sourceKey, fileIndex });
-  }
-
   /**
    * The byte ranges of one file the torrent holds WHOLE.
    *
@@ -401,6 +394,22 @@ export class TorrentWorkerClient {
     return bytes ? Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength) : null;
   }
 
+  async readHeldRanges({ sourceKey, fileIndex, ranges, maxBytes }) {
+    const whole = this.#wholeFileOf(sourceKey, fileIndex);
+    if (whole) {
+      try {
+        return await readWholeFileRanges(whole, ranges, maxBytes);
+      } catch (error) {
+        const key = `${String(sourceKey).slice("torrent:".length).toLowerCase()}/${fileIndex}`;
+        if (this.wholeFiles.get(key) === whole) this.wholeFiles.delete(key);
+        logger.info(`whole-file input ${sourceKey}:${fileIndex} is unavailable: ${error?.code ?? error?.message ?? error}`);
+        return null;
+      }
+    }
+    const answer = await this.#caller.call(Command.READ_HELD_RANGES, { sourceKey, fileIndex, ranges, maxBytes });
+    return answer?.buffers ? answer.buffers.map(bytes => Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)) : null;
+  }
+
   /**
    * The file kept whole on disk for this source and index, if there is one.
    *
@@ -423,11 +432,6 @@ export class TorrentWorkerClient {
     return this.wholeFiles.get(`${infoHash}/${fileIndex}`) ?? null;
   }
 
-  async warmResumePosition({ sourceKey, fileIndex, positionSeconds, durationSeconds }) {
-    return this.#caller.call(Command.WARM_POSITION, { sourceKey, fileIndex, positionSeconds, durationSeconds });
-  }
-
-
   /**
    * Bytes every torrent on the worker has moved, downloaded and uploaded apart.
    *
@@ -454,27 +458,6 @@ export class TorrentWorkerClient {
     return this.#caller.call(Command.HELD_TORRENTS, {});
   }
 
-  /** State conditional demand for every file in a selected torrent. */
-  async fillTorrent(sourceKey) {
-    return this.#caller.call(Command.FILL_TORRENT, { sourceKey });
-  }
-
-  /**
-   * Reorder piece selection around a read position (seek prioritisation).
-   *
-   * @param {{ sourceKey: string, fileIndex: number, byteStart: number, windowBytes?: number, wholeFileRead?: boolean }} params
-   * @returns {Promise<void>}
-   */
-  async prioritizeByteRange({ sourceKey, fileIndex, byteStart, windowBytes, wholeFileRead }) {
-    await this.#caller.call(Command.PRIORITIZE, {
-      sourceKey,
-      fileIndex,
-      byteStart,
-      windowBytes,
-      wholeFileRead
-    });
-  }
-
   /**
    * Hand the download the priority map for one file.
    *
@@ -495,16 +478,6 @@ export class TorrentWorkerClient {
     });
   }
 
-  /**
-   * Pre-fetch the head and tail the codec probe needs.
-   *
-   * @param {{ sourceKey: string, fileIndex: number, options?: { headBytes?: number, tailBytes?: number, timeoutMs?: number, awaited?: boolean } }} params
-   * @returns {Promise<unknown>}
-   */
-  async prefetchFileEdges({ sourceKey, fileIndex, options = {} }) {
-    return this.#caller.call(Command.PREFETCH_EDGES, { sourceKey, fileIndex, options });
-  }
-
   /**
    * Read a byte range as a stream.
    *
@@ -512,10 +485,10 @@ export class TorrentWorkerClient {
    * (viewer gone, seek superseded) stops the worker reading, so pieces are not
    * fetched for a stream nobody will drain.
    *
-   * @param {{ sourceKey: string, fileIndex: number, start?: number | null, end?: number | null, windowBytes?: number }} params
+   * @param {{ sourceKey: string, fileIndex: number, start?: number | null, end?: number | null }} params
    * @returns {ReadableStream<Uint8Array>}
    */
-  createReadStream({ sourceKey, fileIndex, start = null, end = null, windowBytes }) {
+  createReadStream({ sourceKey, fileIndex, start = null, end = null }) {
     // Same id sequence as commands — see `nextId` in `channel.js`.
     const readId = this.#caller.nextId();
     const receive = createReceiveStream({
@@ -534,7 +507,7 @@ export class TorrentWorkerClient {
     this.#worker.postMessage({
       command: Command.READ_RANGE,
       id: readId,
-      params: { sourceKey, fileIndex, start, end, windowBytes }
+      params: { sourceKey, fileIndex, start, end }
     });
 
     return receive.stream;
@@ -554,10 +527,10 @@ export class TorrentWorkerClient {
    * 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, windowBytes?: number }} params
+   * @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, windowBytes }) {
+  createFragmentReader({ sourceKey, fileIndex, start = null, end = null }) {
     const readId = this.#caller.nextId();
     /** @type {{ bytes: Uint8Array, release: () => void }[]} */
     const queue = [];
@@ -598,7 +571,7 @@ export class TorrentWorkerClient {
     this.#worker.postMessage({
       command: Command.READ_RANGE,
       id: readId,
-      params: { sourceKey, fileIndex, start, end, windowBytes }
+      params: { sourceKey, fileIndex, start, end }
     });
 
     return {
@@ -661,7 +634,7 @@ export class TorrentWorkerClient {
       files: info.files.map((file) => ({
         ...file,
         /**
-         * @param {{ start?: number, end?: number, windowBytes?: number }} [options]
+         * @param {{ start?: number, end?: number }} [options]
          * @returns {ReadableStream<Uint8Array>}
          */
         createReadStream(options = {}) {
@@ -674,8 +647,7 @@ export class TorrentWorkerClient {
               sourceKey,
               fileIndex: file.index,
               start: options.start ?? null,
-              end: options.end ?? null,
-              windowBytes: options.windowBytes
+              end: options.end ?? null
             })
           );
         },
@@ -684,7 +656,7 @@ export class TorrentWorkerClient {
          * 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, windowBytes?: number }} [options]
+         * @param {{ start?: number, end?: number }} [options]
          * @returns {ReturnType<TorrentWorkerClient["createFragmentReader"]>}
          */
         createFragmentReader(options = {}) {
@@ -692,8 +664,7 @@ export class TorrentWorkerClient {
             sourceKey,
             fileIndex: file.index,
             start: options.start ?? null,
-            end: options.end ?? null,
-            windowBytes: options.windowBytes
+            end: options.end ?? null
           });
         }
       }))
@@ -834,3 +805,34 @@ export async function readWholeFile(whole, start, end) {
     await handle.close();
   }
 }
+
+/** One open descriptor holds the complete file throughout segment acquisition. */
+export async function readWholeFileRanges(whole, ranges, maxBytes) {
+  if (!Array.isArray(ranges) || ranges.length === 0 || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) return null;
+  let wanted = 0;
+  for (const range of ranges) {
+    if (!Array.isArray(range) || range.length !== 2) return null;
+    const [start, end] = range;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end >= whole.length) return null;
+    wanted += end - start + 1;
+    if (!Number.isSafeInteger(wanted) || wanted > maxBytes) return null;
+  }
+  const handle = await open(whole.path, "r");
+  try {
+    if ((await handle.stat()).size !== whole.length) return null;
+    const result = [];
+    for (const [start, end] of ranges) {
+      const bytes = Buffer.allocUnsafeSlow(end - start + 1);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, start + offset);
+        if (bytesRead === 0) return null;
+        offset += bytesRead;
+      }
+      result.push(bytes);
+    }
+    return result;
+  } finally {
+    await handle.close();
+  }
+}

package/services/torrent/worker/files-in-use.js

@@ -33,3 +33,12 @@ export function filesInUse({ torrent, windows, openReads }) {
   }
   return used;
 }
+
+/** Range admission owns its read before any asynchronous storage operation. */
+export async function readWhileInUse(openReads, id, torrent, fileIndex, read) {
+  if (!torrent) return read();
+  const entry = { torrent, fileIndex };
+  openReads.set(id, entry);
+  try { return await read(); }
+  finally { if (openReads.get(id) === entry) openReads.delete(id); }
+}

package/services/torrent/worker/handle-state.js

@@ -21,3 +21,15 @@
 export function isUsableTorrentHandle(torrent) {
   return Boolean(torrent) && torrent.destroyed !== true && (torrent.files?.length ?? 0) > 0;
 }
+
+/** Resolve only the source lifetime that the caller originally observed. */
+export async function requireCurrentTorrent(handles, sourceKey, pending = handles.get(sourceKey)) {
+  const torrent = pending ? await pending : null;
+  if (!pending || handles.get(sourceKey) !== pending || !isUsableTorrentHandle(torrent)) {
+    if (pending && handles.get(sourceKey) === pending) handles.delete(sourceKey);
+    const error = new Error(`Source ${sourceKey} is no longer available.`);
+    error.code = "SOURCE_FORGOTTEN";
+    throw error;
+  }
+  return torrent;
+}

package/services/torrent/worker/held-bytes.js

@@ -1,9 +1,12 @@
+import { pieceStoreOf } from "../piece-store-of.js";
+
 /**
  * @file What of a file the torrent already HOLDS, and reading it without
  * asking the swarm for anything.
  *
- * Two questions, and both are the torrent's own: which pieces have arrived is
- * its bitfield, and reading a piece it has is its store. They are here because
+ * Storage answers both questions: which pieces remain available, and how to
+ * read them. The library bitfield is not a second availability authority.
+ * They are here because
  * of that and for no other reason — everything else that used to keep them
  * company, the subtitle plan and the cue walk and the cursor a browser follows,
  * is what a FILE says about itself and moved to the thread the sessions are on
@@ -27,8 +30,8 @@
 /**
  * The byte ranges of one file that are downloaded WHOLE.
  *
- * Whole because a piece is the unit the swarm delivers and the unit the
- * bitfield counts: a range that is half a piece short cannot be read, so
+ * Whole because a piece is the unit storage retains: a range that is half a
+ * piece short cannot be read, so
  * reporting it would be reporting bytes that are not there.
  *
  * @param {object} torrent
@@ -40,7 +43,8 @@
 export function heldRangesOf(torrent, fileIndex) {
   const file = torrent?.files?.[fileIndex];
   const pieceLength = Number(torrent?.pieceLength);
-  if (!file || !Number.isFinite(pieceLength) || pieceLength <= 0 || !torrent?.bitfield) {
+  const store = pieceStoreOf(torrent);
+  if (!file || !Number.isSafeInteger(pieceLength) || pieceLength <= 0 || typeof store?.locationOf !== "function") {
     return [];
   }
   const offset = Number(file.offset) || 0;
@@ -54,7 +58,7 @@ export function heldRangesOf(torrent, fileIndex) {
   const ranges = [];
   let runStart = -1;
   for (let index = first; index <= last; index += 1) {
-    if (torrent.bitfield.get(index)) {
+    if (store.locationOf(index) !== "missing") {
       if (runStart < 0) {
         runStart = index;
       }
@@ -99,14 +103,16 @@ function rangeWithin(firstPiece, lastPiece, pieceLength, offset, length) {
 export function isRangeHeld(torrent, fileIndex, start, end) {
   const file = torrent?.files?.[fileIndex];
   const pieceLength = Number(torrent?.pieceLength);
-  if (!file || !Number.isFinite(pieceLength) || pieceLength <= 0 || !torrent?.bitfield) {
+  const store = pieceStoreOf(torrent);
+  if (!file || !Number.isSafeInteger(pieceLength) || pieceLength <= 0 || typeof store?.locationOf !== "function" ||
+      !Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end >= file.length) {
     return false;
   }
   const offset = Number(file.offset) || 0;
   const first = Math.floor((offset + start) / pieceLength);
   const last = Math.floor((offset + end) / pieceLength);
   for (let index = first; index <= last; index += 1) {
-    if (!torrent.bitfield.get(index)) {
+    if (store.locationOf(index) === "missing") {
       return false;
     }
   }
@@ -114,105 +120,82 @@ export function isRangeHeld(torrent, fileIndex, start, end) {
 }
 
 /**
- * How long a read of bytes the torrent HOLDS may take before it is taken to be
- * a fault.
- *
- * Not a measurement and nothing is derived from it: the bytes are checked to be
- * held before the read starts, so a read that does not finish is a store that
- * failed to serve what it has, and the line it writes says so. Until 2026-10-01
- * this read was started on bytes that had NOT arrived, the stream waited for
- * them, and this was the bound that gave it up — 36 such reads gave up at once
- * at a torrent's open, and one of them was the Cues table of the file being
- * watched.
- */
-const READ_ABANDON_MS = 30_000;
-
-/**
- * Read a byte range of a file straight from the store, without asking the swarm
- * for anything.
- *
- * Answered at once with null where any piece under the range has not arrived:
- * "not here" is the whole answer, and nothing is waited for or requested.
- *
- * The bytes come back in a buffer that owns its whole memory — not a slice of
- * Node's shared pool and not a view of the store's own blocks — so the reply can
- * hand that memory to the other thread instead of copying it, and nothing the
- * store or another read still uses goes with it.
- *
- * @param {object} torrent
- * @param {number} fileIndex
- * @param {number} start
- * @param {number} end - Inclusive.
- * @param {{ info: Function }} [logger]
- * @returns {Promise<Buffer | null>}
+ * Read downloaded bytes through storage only. Availability and acquisition of
+ * all input holds are one synchronous operation before the first disk read.
+ * Missing input returns null without selecting pieces or opening a torrent
+ * file stream. The returned allocation can be transferred to another thread.
  */
-export function readHeldBytes(torrent, fileIndex, start, end, logger = null) {
+export async function readHeldBytes(torrent, fileIndex, start, end, logger = null) {
   const file = torrent?.files?.[fileIndex];
-  if (!file || !(end >= start) || !(start >= 0)) {
-    return Promise.resolve(null);
-  }
+  const pieceLength = Number(torrent?.pieceLength);
+  const store = pieceStoreOf(torrent);
+  if (!file || !store || !Number.isSafeInteger(start) || !Number.isSafeInteger(end) ||
+      start < 0 || end < start || start >= Number(file.length) || !(pieceLength > 0)) return null;
   const last = Math.min(end, Number(file.length) - 1);
-  if (!isRangeHeld(torrent, fileIndex, start, last)) {
-    return Promise.resolve(null);
-  }
-  return new Promise((resolve) => {
-    const chunks = [];
-    let stream;
-    try {
-      stream = file.createReadStream({ start, end: last });
-    } catch {
-      resolve(null);
-      return;
+  const absoluteStart = (Number(file.offset) || 0) + start;
+  const absoluteEnd = (Number(file.offset) || 0) + last;
+  const firstPiece = Math.floor(absoluteStart / pieceLength);
+  const lastPiece = Math.floor(absoluteEnd / pieceLength);
+  const indexes = Array.from({ length: lastPiece - firstPiece + 1 }, (_, index) => firstPiece + index);
+  const release = store.holdAvailable(indexes);
+  if (!release) return null;
+  try {
+    const owned = Buffer.allocUnsafeSlow(last - start + 1);
+    for (const index of indexes) {
+      const from = Math.max(absoluteStart, index * pieceLength);
+      const to = Math.min(absoluteEnd, (index + 1) * pieceLength - 1);
+      const wanted = to - from + 1;
+      const bytes = await new Promise((resolve, reject) => {
+        store.get(index, { offset: from - index * pieceLength, length: wanted }, (error, value) => {
+          if (error) reject(error);
+          else resolve(value);
+        });
+      });
+      if (!bytes || bytes.length !== wanted) return null;
+      owned.set(bytes, from - absoluteStart);
     }
-    let settled = false;
-    /** @type {ReturnType<typeof setTimeout> | null} */
-    let abandon = null;
-    const settle = (value) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      if (abandon !== null) {
-        clearTimeout(abandon);
-      }
-      if (value === null) {
-        stream.destroy?.();
-      }
-      resolve(value);
-    };
-    abandon = setTimeout(() => {
-      logger?.info(
-        `subtitles: a read of ${start}-${last} in "${String(file.name).slice(0, 40)}" ` +
-        `was held but not served in ${READ_ABANDON_MS / 1000}s and was given up — the store failed to serve bytes it has`
-      );
-      settle(null);
-    }, READ_ABANDON_MS);
-    abandon.unref?.();
-    stream.on("data", (chunk) => chunks.push(chunk));
-    stream.on("end", () => settle(ownedCopyOf(chunks)));
-    stream.on("error", () => settle(null));
-  });
+    return owned;
+  } catch (error) {
+    logger?.info?.(`held read ${fileIndex}:${start}-${last} failed: ${error?.message ?? error}`);
+    return null;
+  } finally {
+    release();
+  }
 }
 
-/**
- * The chunks as one buffer over memory of its own.
- *
- * @param {Uint8Array[]} chunks
- * @returns {Buffer}
- */
-function ownedCopyOf(chunks) {
-  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  // `allocUnsafeSlow` never takes from the shared pool, so the buffer is the
-  // whole of its ArrayBuffer and may be transferred.
-  const owned = Buffer.allocUnsafeSlow(total);
-  let at = 0;
-  for (const chunk of chunks) {
-    owned.set(chunk, at);
-    at += chunk.length;
+/** Acquire every input piece before copying any of the segment's ranges. */
+export async function readHeldRanges(torrent, fileIndex, ranges, maxBytes, logger = null) {
+  const file = torrent?.files?.[fileIndex];
+  const pieceLength = Number(torrent?.pieceLength);
+  const store = pieceStoreOf(torrent);
+  if (!file || !store || !Array.isArray(ranges) || ranges.length === 0 ||
+    !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || !(pieceLength > 0)) return null;
+  const indexes = new Set();
+  let bytes = 0;
+  for (const range of ranges) {
+    if (!Array.isArray(range) || range.length !== 2) return null;
+    const [start, end] = range;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end >= file.length) return null;
+    bytes += end - start + 1;
+    if (!Number.isSafeInteger(bytes) || bytes > maxBytes) return null;
+    const first = Math.floor(((Number(file.offset) || 0) + start) / pieceLength);
+    const last = Math.floor(((Number(file.offset) || 0) + end) / pieceLength);
+    for (let index = first; index <= last; index++) indexes.add(index);
+  }
+  const release = store.holdAvailable([...indexes]);
+  if (!release) return null;
+  try {
+    const result = [];
+    for (const [start, end] of ranges) {
+      const owned = await readHeldBytes(torrent, fileIndex, start, end, logger);
+      if (!owned) return null;
+      result.push(owned);
+    }
+    return result;
+  } finally {
+    release();
   }
-  return owned;
 }
-
 /**
  * Whether a buffer may be TRANSFERRED to another thread: it must be the whole of
  * a plain ArrayBuffer. A slice of the shared pool would take every other

package/services/torrent/worker/held-file-bytes.js

@@ -0,0 +1,17 @@
+import { readHeldBytes } from "./held-bytes.js";
+
+/** Whole-file assembly reads held storage pieces without creating download demand. */
+export async function* heldFileBytes(torrent, fileIndex) {
+  const file = torrent?.files?.[fileIndex];
+  const pieceLength = Number(torrent?.pieceLength), offset = Number(file?.offset) || 0;
+  if (!file || !Number.isSafeInteger(file.length) || file.length <= 0 || !Number.isSafeInteger(pieceLength) || pieceLength <= 0) {
+    throw new Error("Whole-file assembly requires a declared file and piece length.");
+  }
+  for (let start = 0; start < file.length;) {
+    const end = Math.min(file.length - 1, (Math.floor((offset + start) / pieceLength) + 1) * pieceLength - offset - 1);
+    const bytes = await readHeldBytes(torrent, fileIndex, start, end);
+    if (!bytes) throw new Error(`Whole-file assembly lost held bytes ${start}-${end} of file ${fileIndex}.`);
+    yield bytes;
+    start = end + 1;
+  }
+}