@torrent-tv/proxy 2.86.0 → 2.87.0

package/services/{torrent-worker → torrent/worker}/client.js

@@ -17,7 +17,7 @@
 import { Worker } from "node:worker_threads";
 import { Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
-import { logger, writeAlreadyDecided } from "../../utils/logger.js";
+import { logger, writeAlreadyDecided } from "../../../utils/logger.js";
 import { createCaller, createReceiveStream } from "./channel.js";
 import { Command, Event } from "./protocol.js";
 
@@ -107,21 +107,22 @@ export class TorrentWorkerClient {
   wholeFiles = new Map();
 
   /** @type {(event: { sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string }) => void} */
-  #onSubtitleCues;
+  /** @type {(event: { sourceKey: string, fileIndexes: number[] }) => void} */
+  #onPiecesArrived;
 
   /**
-   * @param {{ maxDiskBytes?: number, memoryBytes?: number, stateDir?: string, onSubtitleCues?: (event: object) => void }} [options]
+   * @param {{ memoryBytes?: number, stateDir?: string, onPiecesArrived?: (event: object) => void }} [options]
    */
-  constructor({ maxDiskBytes, memoryBytes, stateDir, onSubtitleCues } = {}) {
+  constructor({ memoryBytes, stateDir, onPiecesArrived } = {}) {
     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
       // not change the process's working directory, and the isolate that has
       // died three times is the one no snapshot has ever been taken of.
-      workerData: { maxDiskBytes, memoryBytes, stateDir }
+      workerData: { memoryBytes, stateDir }
     });
     this.#caller = createCaller(this.#worker);
-    this.#onSubtitleCues = onSubtitleCues ?? (() => undefined);
+    this.#onPiecesArrived = onPiecesArrived ?? (() => undefined);
 
     this.#worker.on("message", (message) => {
       // A failed read must fail its stream. This is checked BEFORE the caller
@@ -232,14 +233,12 @@ export class TorrentWorkerClient {
             name: message.name
           });
           break;
-        case Event.SUBTITLE_CUES_READY:
-          this.#onSubtitleCues({
+        case Event.PIECES_ARRIVED:
+          // 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,
-            fileIndex: message.fileIndex,
-            trackIndex: message.trackIndex,
-            cues: message.cues,
-            language: message.language,
-            cursor: message.cursor
+            fileIndexes: Array.isArray(message.fileIndexes) ? message.fileIndexes : []
           });
           break;
         default:
@@ -336,75 +335,54 @@ export class TorrentWorkerClient {
    * @param {{ sourceKey: string, fileIndex: number }} params
    * @returns {Promise<{ tracks: object[] }>}
    */
-  /**
-   * 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 });
-  }
 
-  async getSubtitleTracks({ sourceKey, fileIndex }) {
-    return this.#caller.call(Command.SUBTITLE_TRACKS, { sourceKey, fileIndex });
-  }
+
+
 
   /**
-   * Every track one file declares, read from its own header.
-   *
-   * Asked of the picture for the flags ffmpeg's banner does not carry, and of a
-   * soundtrack shipped as its own file beside it — the same question about a
-   * different file, which is why there is one command rather than two.
+   * Start fetching the region a viewer is about to resume at.
    *
-   * @param {{ sourceKey: string, fileIndex: number }} params
-   * @returns {Promise<{ tracks: object[] }>}
+   * @param {{ sourceKey: string, fileIndex: number, positionSeconds: number }} params
+   * @returns {Promise<{ started: boolean }>}
    */
-  async getContainerTracks({ sourceKey, fileIndex }) {
-    return this.#caller.call(Command.CONTAINER_TRACKS, { sourceKey, fileIndex });
-  }
-
   /**
-   * What one file declares about itself — format, duration, and where its own
-   * timeline begins.
+   * Fetch one whole file in the room the viewer's own reading leaves.
    *
    * @param {{ sourceKey: string, fileIndex: number }} params
-   * @returns {Promise<{ info: import("../container/Container.js").ContainerMediaInfo | null }>}
+   * @returns {Promise<{ started: boolean }>}
    */
-  async getContainerMediaInfo({ sourceKey, fileIndex }) {
-    return this.#caller.call(Command.CONTAINER_MEDIA_INFO, { sourceKey, fileIndex });
+  async fillFile({ sourceKey, fileIndex }) {
+    return this.#caller.call(Command.FILL_FILE, { sourceKey, fileIndex });
   }
 
   /**
-   * Where one file's keyframes are, from the container's own table.
+   * The byte ranges of one file the torrent holds WHOLE.
    *
    * @param {{ sourceKey: string, fileIndex: number }} params
-   * @returns {Promise<{ index: { times: number[], tolerance: number } | null }>}
+   * @returns {Promise<Array<[number, number]>>}
    */
-  async getContainerKeyframes({ sourceKey, fileIndex }) {
-    return this.#caller.call(Command.CONTAINER_KEYFRAMES, { sourceKey, fileIndex });
+  async heldRanges({ sourceKey, fileIndex }) {
+    const answer = await this.#caller.call(Command.HELD_RANGES, { sourceKey, fileIndex });
+    return Array.isArray(answer?.ranges) ? answer.ranges : [];
   }
 
   /**
-   * Start fetching the region a viewer is about to resume at.
+   * Bytes of a range the torrent already holds. Never fetched: null where they
+   * are not there.
    *
-   * @param {{ sourceKey: string, fileIndex: number, positionSeconds: number }} params
-   * @returns {Promise<{ started: boolean }>}
+   * @param {{ sourceKey: string, fileIndex: number, start: number, end: number }} params
+   * @returns {Promise<Buffer | null>}
    */
-  async warmResumePosition({ sourceKey, fileIndex, positionSeconds }) {
-    return this.#caller.call(Command.WARM_POSITION, { sourceKey, fileIndex, positionSeconds });
+  async readHeld({ sourceKey, fileIndex, start, end }) {
+    const answer = await this.#caller.call(Command.READ_HELD, { sourceKey, fileIndex, start, end });
+    return answer?.bytes ? Buffer.from(answer.bytes) : null;
   }
 
-  /**
-   * The cues of one subtitle track that can be read from what is downloaded.
-   *
-   * @param {{ sourceKey: string, fileIndex: number, trackNumber: number }} params
-   * @returns {Promise<object>}
-   */
-  async getSubtitleCues({ sourceKey, fileIndex, trackNumber }) {
-    return this.#caller.call(Command.SUBTITLE_CUES, { sourceKey, fileIndex, trackNumber });
+  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.
    *
@@ -684,6 +662,47 @@ export class TorrentWorkerClient {
    */
   spilledBytes = 0;
 
+  /**
+   * Tell the piece stores on the torrent thread their share of MEMORY.
+   *
+   * The same owner divides memory and disk, because the two trade: pieces that
+   * do not fit in memory are spilled to disk, so what the stores are given here
+   * decides how much disk they need there.
+   *
+   * @param {number} bytes
+   * @returns {Promise<{ held: number, wanted: number }>}
+   */
+  async allowMemoryBytes(bytes) {
+    try {
+      const claim = await this.#caller.call(Command.MEMORY_ALLOWANCE, { bytes });
+      this.memoryClaim = {
+        held: Number(claim?.held) || 0,
+        wanted: Number(claim?.wanted) || 0
+      };
+    } catch {
+      // The thread is gone or busy; the next revision says it again.
+    }
+    return this.memoryClaim ?? { held: 0, wanted: 0 };
+  }
+
+  /**
+   * Tell the whole files on the torrent thread their share of the disk.
+   *
+   * Same shape as the spilled pieces, and for the same reason: they hold bytes
+   * on this machine and the owner of the disk is on the other thread.
+   *
+   * @param {number} bytes
+   * @returns {Promise<number>} What they hold after it.
+   */
+  async allowWholeFileBytes(bytes) {
+    try {
+      this.wholeFileBytes = Number(await this.#caller.call(Command.WHOLE_FILES_ALLOWANCE, { bytes })) || 0;
+    } catch {
+      // The thread is gone or busy; the next revision says it again.
+    }
+    return this.wholeFileBytes ?? 0;
+  }
+
   /**
    * Say how much disk the spilled pieces on this thread may take between them.
    *

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

@@ -0,0 +1,155 @@
+/**
+ * @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
+ * 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
+ * (2026-09-15).
+ *
+ * **Why the subtitle walk cannot use the ordinary range read.** That one
+ * declares demand: it registers a window, steers the swarm toward the piece it
+ * is stopped on, and waits. Right for a viewer waiting on a segment, wrong
+ * here — switching subtitles on must never pull bytes the viewer is not waiting
+ * for, which is the rule the walk has kept since it was written. So these two
+ * read the store and say "not here" rather than fetching.
+ *
+ * **The held ranges are answered as a LIST, not asked piece by piece.** The
+ * walk asks "is this cluster downloaded" for every cluster of the file — on the
+ * field files that is hundreds of questions per pass, and a pass runs every
+ * three seconds. One list per pass costs one message; the same answers asked
+ * one at a time cost hundreds of round trips for a walk that is meant to be
+ * free when there is nothing new to find.
+ */
+
+/**
+ * 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
+ * reporting it would be reporting bytes that are not there.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @returns {Array<[number, number]>} Ascending, non-overlapping, inclusive
+ *   offsets WITHIN the file. Empty when nothing of it has arrived, or when the
+ *   torrent cannot say — which reads the same way: nothing may be walked yet.
+ */
+export function heldRangesOf(torrent, fileIndex) {
+  const file = torrent?.files?.[fileIndex];
+  const pieceLength = Number(torrent?.pieceLength);
+  if (!file || !Number.isFinite(pieceLength) || pieceLength <= 0 || !torrent?.bitfield) {
+    return [];
+  }
+  const offset = Number(file.offset) || 0;
+  const length = Number(file.length) || 0;
+  if (!(length > 0)) {
+    return [];
+  }
+  const first = Math.floor(offset / pieceLength);
+  const last = Math.floor((offset + length - 1) / pieceLength);
+  /** @type {Array<[number, number]>} */
+  const ranges = [];
+  let runStart = -1;
+  for (let index = first; index <= last; index += 1) {
+    if (torrent.bitfield.get(index)) {
+      if (runStart < 0) {
+        runStart = index;
+      }
+      continue;
+    }
+    if (runStart >= 0) {
+      ranges.push(rangeWithin(runStart, index - 1, pieceLength, offset, length));
+      runStart = -1;
+    }
+  }
+  if (runStart >= 0) {
+    ranges.push(rangeWithin(runStart, last, pieceLength, offset, length));
+  }
+  return ranges;
+}
+
+/**
+ * A run of whole pieces, as offsets within the file.
+ *
+ * @param {number} firstPiece
+ * @param {number} lastPiece
+ * @param {number} pieceLength
+ * @param {number} offset - Where the file begins in the torrent.
+ * @param {number} length - How long the file is.
+ * @returns {[number, number]}
+ */
+function rangeWithin(firstPiece, lastPiece, pieceLength, offset, length) {
+  const start = Math.max(0, firstPiece * pieceLength - offset);
+  const end = Math.min(length - 1, (lastPiece + 1) * pieceLength - 1 - offset);
+  return [start, end];
+}
+
+/**
+ * How long a read of bytes the torrent already holds may take before it is
+ * given up.
+ *
+ * Not a measurement and nothing is derived from it: such a read either answers
+ * or it does not, and this is the point past which it is presumed lost — so
+ * that one stream which never ends cannot hold a file's walk, and with it the
+ * browser's own request for its subtitles, for the rest of the session.
+ */
+const READ_ABANDON_MS = 30_000;
+
+/**
+ * Read a byte range of a file straight from the store, without asking the swarm
+ * for anything.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {number} start
+ * @param {number} end - Inclusive.
+ * @param {{ info: Function }} [logger]
+ * @returns {Promise<Buffer | null>}
+ */
+export function readHeldBytes(torrent, fileIndex, start, end, logger = null) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !(end >= start) || !(start >= 0)) {
+    return Promise.resolve(null);
+  }
+  const last = Math.min(end, Number(file.length) - 1);
+  return new Promise((resolve) => {
+    const chunks = [];
+    let stream;
+    try {
+      stream = file.createReadStream({ start, end: last });
+    } catch {
+      resolve(null);
+      return;
+    }
+    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)}" ` +
+        `did not finish in ${READ_ABANDON_MS / 1000}s and was given up`
+      );
+      settle(null);
+    }, READ_ABANDON_MS);
+    abandon.unref?.();
+    stream.on("data", (chunk) => chunks.push(chunk));
+    stream.on("end", () => settle(Buffer.concat(chunks)));
+    stream.on("error", () => settle(null));
+  });
+}

package/services/{torrent-worker → torrent/worker}/install-webrtc-shim.js

@@ -3,7 +3,7 @@
  *
  * Imported for its side effect, and imported FIRST by `worker.js` — ES module
  * bodies run in import order, so registering the hook here happens before
- * `torrent-pool.js` pulls in WebTorrent, which is what reaches
+ * `torrent/torrent-pool.js` pulls in WebTorrent, which is what reaches
  * `@thaunknown/simple-peer` and, through it, `webrtc-polyfill`.
  *
  * Scope is deliberately narrow. The hook lives in the worker's isolate, so the

package/services/{torrent-worker → torrent/worker}/piece-reader.js

@@ -20,10 +20,10 @@
  *    with those bytes — not when they were sent, because nothing was sent.
  */
 
-import { findSharedStore } from "../piece-store/shared-piece-store.js";
+import { pieceStoreOf } from "../piece-store-of.js";
 import { bytesOf, Urgency, urgencyName } from "../demand/index.js";
 import { demandFor } from "../download/registry.js";
-import { logger } from "../../utils/logger.js";
+import { logger } from "../../../utils/logger.js";
 import {
   askFastestWiresFor,
   canPlaceRequests,
@@ -144,7 +144,7 @@ export function pieceSupply(torrent, pieceIndex) {
  *
  * @param {import("webtorrent").Torrent} torrent
  * @param {number} index
- * @param {{ isCancelled: () => boolean }} cancellation
+ * @param {{ isCancelled: () => boolean, onCancel?: (listener: () => void) => () => void }} cancellation
  * @returns {Promise<void>}
  */
 function whenPieceReady(torrent, index, cancellation) {
@@ -164,17 +164,21 @@ function whenPieceReady(torrent, index, cancellation) {
       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);
+    // A superseded seek destroys the read, and without this the wait would
+    // outlive it and hold a pin. The read's own stream says so the moment it
+    // happens; it was polled every 250 ms before. A cancellation that cannot
+    // announce itself is one that is never cancelled (a test's plain object).
+    if (cancellation.isCancelled()) {
+      reject(new Error(`Read cancelled while waiting for piece ${index}.`));
+      return;
+    }
+    const stopListening = cancellation.onCancel?.(() => {
+      cleanup();
+      reject(new Error(`Read cancelled while waiting for piece ${index}.`));
+    }) ?? (() => {});
 
     function cleanup() {
-      clearInterval(poll);
+      stopListening();
       torrent.removeListener("verified", onVerified);
       torrent.removeListener("close", onDestroyed);
     }
@@ -301,20 +305,8 @@ export function supplyFiguresFor(infoHash, fileName, segmentSeconds) {
 const waitsBySteering = new Map();
 
 /**
- * Record one wait against the band the reader was stopped in.
- *
- * What this replaces: until 2026-09-02 each read was assigned at random to one
- * of two ways of claiming — one band or four — and the waits were sorted by
- * which. The comparison never decided anything, and could not: the split halved
- * the sample for each arm, so on 2026-08-28 there were nine reads in one arm and
- * three in the other and the ten-wait threshold was never reached in either; on
- * 2026-08-29 the two arms printed together for the first and only time, as forty
- * waits against one.
- *
- * This is the more useful question anyway. A wait belongs to a LEVEL, and the
- * level says whether a width is wrong rather than whether the whole scheme is:
- * long waits in the band being watched mean the urgent window is too narrow,
- * long waits further out mean the lead is.
+ * Record one wait against the priority level of the requested piece. The level
+ * identifies which part of the priority map needs more lead time.
  *
  * @param {string} key
  * @param {number} waitedMs
@@ -536,7 +528,7 @@ export async function* readFragments({
   cancellation,
   windowBytes = READ_WINDOW_BYTES
 }) {
-  const store = findSharedStore(torrent);
+  const store = pieceStoreOf(torrent);
   if (!store) {
     throw new Error("This torrent is not backed by a shared piece store.");
   }
@@ -649,9 +641,8 @@ export async function* readFragments({
   /**
    * State one band as a need, in bytes.
    *
-   * The claimant carries the level, so the four bands of one reader are four
-   * claimants and each is replaced on its own — restating the near band does
-   * not disturb what was said about the tail.
+   * The urgency is part of the claimant key, so this blocked-read claim can be
+   * withdrawn without changing the priority map's claims for the same file.
    *
    * @param {{ from: number, to: number, urgency: number }} band
    * @returns {void}