@torrent-tv/proxy 2.72.2 → 2.73.1

package/services/orchestrators/SubtitleOrchestrator.js

@@ -13,7 +13,6 @@
 
 import { containerOrchestrator } from "./ContainerOrchestrator.js";
 import {
-  cuesHeldFor as domainCuesHeldFor,
   warmSubtitleCues as domainWarm,
   subtitleTracksOf,
   declaredSubtitleTracksOf,
@@ -65,18 +64,78 @@ export class SubtitleOrchestrator {
   }
 
   /**
-   * Cues already downloaded for one track.
+   * Cues already downloaded for one track — ASKED OF THE TORRENT WORKER, never
+   * walked here.
+   *
+   * The walk decides what it may read from `torrent.bitfield` and
+   * `torrent.pieceLength`, and a torrent stand-in on the main thread has
+   * neither: it carries `infoHash`, `name` and a `files` list whose reads go
+   * back across the boundary (`torrent-worker/client.js`). So the same code
+   * called here answers that nothing is downloaded, walks no clusters, and
+   * returns an empty document — which is not a failure anything reports,
+   * because "no cues held" is a legitimate answer.
+   *
+   * Field 2026-09-03, and it is the whole reason this method changed. An
+   * episode already downloaded from an earlier sitting had its cues found
+   * within a second and a half of the file being opened, and the first four
+   * pushes — everything before 81.7 s — went out before the browser had
+   * subscribed. The catch-up pull that exists for exactly that case answered
+   * `WEBVTT` and nothing else, with `x-subtitle-covered-clusters: 0` against
+   * 283 indexed, so the viewer watched the opening of the episode with no
+   * subtitles and the rest of it with them.
+   *
+   * There is a second reason, independent of the bitfield. The register of what
+   * has been walked, what has been found and in what ORDER lives in the module
+   * that does the walking, and the worker already keeps one — the push path
+   * fills it. Walking again on the main thread would build a SECOND register
+   * with its own `seq` counter, and the browser mixes the cursors from both
+   * paths (`#rememberCursor`): two counters would make a cursor from a pull and
+   * a cursor from a push incomparable. One register, one walk, one cursor.
+   *
+   * @param {{ getSubtitleCues?: Function }} pool - The torrent pool, which is
+   *   what holds the channel to the worker.
    * @param {object} torrent
    * @param {number} fileIndex
    * @param {string} sourceKey
    * @param {number} trackNumber - Container trackNumber
+   * @returns {Promise<{ cues: object[], coveredClusters: number, indexedClusters: number, track: object | null }>}
    */
-  async getCues(torrent, fileIndex, sourceKey, trackNumber) {
+  async getCues(pool, torrent, fileIndex, sourceKey, trackNumber) {
+    // Built fresh on each of the three paths that need it. One shared literal
+    // returned by reference would hand every caller the same array, and a
+    // single one of them appending to it would change what the next caller
+    // reads — which in a method about cue registers not leaking into each
+    // other would be a poor thing to introduce.
+    const empty = () => ({ cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
+    if (typeof pool?.getSubtitleCues !== "function") {
+      // Nothing here can read pieces, and answering an empty document would be
+      // indistinguishable from a file that genuinely holds no cues.
+      logger.warn(
+        "subtitle-orchestrator: the torrent pool cannot be asked for cues, " +
+        "so none can be served — the walk needs the thread that owns the torrent"
+      );
+      return empty();
+    }
     try {
-      return await domainCuesHeldFor(torrent, fileIndex, sourceKey, trackNumber);
+      const answer = await pool.getSubtitleCues(torrent, fileIndex, trackNumber);
+      if (!answer) {
+        return empty();
+      }
+      return {
+        cues: Array.isArray(answer.cues) ? answer.cues : [],
+        coveredClusters: answer.coveredClusters ?? 0,
+        indexedClusters: answer.indexedClusters ?? 0,
+        // The worker answers with the track's own fields flat, because a
+        // `ContainerTrack` is a class and only plain objects cross the boundary.
+        track: {
+          codecId: answer.codecId ?? "",
+          codecPrivate: answer.codecPrivate ?? "",
+          language: answer.language ?? ""
+        }
+      };
     } catch (e) {
       logger.warn(`subtitle-orchestrator: getCues failed: ${e?.message ?? e}`);
-      return { cues: [], coveredClusters: 0, indexedClusters: 0, track: null };
+      return empty();
     }
   }
 

package/services/torrent-pool.js

@@ -1800,6 +1800,52 @@ export class TorrentPool {
     }
   }
 
+  /**
+   * Fetch a bounded region in the MIDDLE of a file.
+   *
+   * The warm-up fetches a file's two edges because the codec probe reads them.
+   * A viewer resuming a film needs neither: they need the region under their own
+   * position, and until now nothing asked for it before the encoder did. Field
+   * 2026-09-03 — a retry after a crash reached the encoder 53 s after the button
+   * was pressed, and only THEN was the piece under the viewer's position first
+   * requested; it took another 46 s, and the browser gave up 0.4 s before it
+   * landed.
+   *
+   * Read as an ordinary bounded read, never as a selection: claiming a whole
+   * region alongside the readers' own windows is the mistake `#syncSelections`
+   * was written against.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {number} fileIndex
+   * @param {number} startByte
+   * @param {number} bytes
+   * @param {{ timeoutMs?: number }} [options]
+   * @returns {Promise<void>}
+   */
+  async prefetchFileRegion(torrent, fileIndex, startByte, bytes, { timeoutMs = 300_000 } = {}) {
+    const file = torrent?.files?.[fileIndex];
+    if (!file || typeof file.createReadStream !== "function") {
+      return;
+    }
+    const fileSize = file.length;
+    if (!Number.isFinite(fileSize) || fileSize <= 0 || !(bytes > 0)) {
+      return;
+    }
+    const start = Math.max(0, Math.min(Math.floor(startByte), fileSize - 1));
+    const end = Math.min(fileSize - 1, start + Math.floor(bytes) - 1);
+    if (end <= start) {
+      return;
+    }
+    const drained = new Promise((resolve) => {
+      const stream = file.createReadStream({ start, end });
+      stream.on("data", () => undefined);
+      stream.once("end", resolve);
+      stream.once("error", resolve);
+      stream.once("close", resolve);
+    });
+    await Promise.race([drained, new Promise((resolve) => setTimeout(resolve, timeoutMs))]);
+  }
+
   /**
    * The body of {@link prefetchFileEdges}, without the de-duplication.
    *

package/services/torrent-worker/client.js

@@ -349,6 +349,27 @@ export class TorrentWorkerClient {
     return this.#caller.call(Command.CONTAINER_TRACKS, { sourceKey, fileIndex });
   }
 
+  /**
+   * What one file declares about itself — format, duration, and where its own
+   * timeline begins.
+   *
+   * @param {{ sourceKey: string, fileIndex: number }} params
+   * @returns {Promise<{ info: import("../container/Container.js").ContainerMediaInfo | null }>}
+   */
+  async getContainerMediaInfo({ sourceKey, fileIndex }) {
+    return this.#caller.call(Command.CONTAINER_MEDIA_INFO, { sourceKey, fileIndex });
+  }
+
+  /**
+   * Start fetching the region a viewer is about to resume at.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, positionSeconds: number }} params
+   * @returns {Promise<{ started: boolean }>}
+   */
+  async warmResumePosition({ sourceKey, fileIndex, positionSeconds }) {
+    return this.#caller.call(Command.WARM_POSITION, { sourceKey, fileIndex, positionSeconds });
+  }
+
   /**
    * The cues of one subtitle track that can be read from what is downloaded.
    *

package/services/torrent-worker/container-tracks.js

@@ -224,6 +224,140 @@ export async function containerAudioTracksOf(torrent, fileIndex, sourceKey, opti
 /** Bytes of a file's head worth fetching before its track table is read. */
 export const CONTAINER_HEAD_BYTES = HEAD_BYTES;
 
+/**
+ * How much of the file to pull in under the viewer's resume position.
+ *
+ * One piece of a video torrent is 4-16 MB and a resume lands anywhere inside
+ * one, so anything smaller would still leave the encoder waiting for the piece
+ * it starts in. Eight megabytes covers that piece and usually the next.
+ */
+const RESUME_REGION_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Where a position in seconds falls in a file, in bytes.
+ *
+ * Proportional, and therefore approximate on a variable bitrate — which is what
+ * it is for: a prefetch that puts the swarm to work on roughly the right place
+ * while the plan and the session are still being built. The encoder's own read
+ * asks for the exact bytes a moment later and corrects it.
+ *
+ * A position past the end is clamped to the end rather than refused: a resume
+ * position can outlive the file it was recorded against, and reading the last
+ * bytes is harmless where reading past them is an error.
+ *
+ * @param {number} fileLength
+ * @param {number} durationSeconds
+ * @param {number} positionSeconds
+ * @returns {number}
+ */
+export function resumeByteOffset(fileLength, durationSeconds, positionSeconds) {
+  if (!(fileLength > 0) || !(durationSeconds > 0) || !(positionSeconds > 0)) {
+    return 0;
+  }
+  const within = Math.min(positionSeconds, durationSeconds);
+  return Math.min(fileLength - 1, Math.floor((fileLength * within) / durationSeconds));
+}
+
+/**
+ * Start fetching the region a viewer is about to resume at.
+ *
+ * Where that region IS can only be worked out from two numbers the file itself
+ * holds — its length and its duration — so this belongs beside the container
+ * read rather than in the route: the route knows a position in seconds and
+ * nothing else. The conversion is proportional and therefore approximate on a
+ * variable bitrate; it is a prefetch, and the encoder's own read corrects it.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {number} positionSeconds
+ * @param {{ prefetchEdges?: () => Promise<unknown>, fetchRegion?: (start: number, bytes: number) => Promise<unknown> }} options
+ * @returns {Promise<boolean>} Whether a region was asked for.
+ */
+export async function warmResumePosition(torrent, fileIndex, sourceKey, positionSeconds, options = {}) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !(positionSeconds > 0) || typeof options.fetchRegion !== "function") {
+    return false;
+  }
+  const info = await containerMediaInfoOf(torrent, fileIndex, sourceKey, options);
+  const duration = info?.durationSeconds;
+  if (!Number.isFinite(duration) || duration <= 0) {
+    logger.info(
+      `warm ${sourceKey.slice(0, 8)}: "${String(file.name).slice(0, 40)}" does not declare its ` +
+      "duration, so where the viewer's position falls in it cannot be worked out — " +
+      "the region under it is left to the encoder's own read"
+    );
+    return false;
+  }
+  const at = resumeByteOffset(file.length, duration, positionSeconds);
+  logger.info(
+    `warm ${sourceKey.slice(0, 8)}: fetching ${(RESUME_REGION_BYTES / (1024 * 1024)).toFixed(0)}MB under the ` +
+    `viewer's position ${positionSeconds.toFixed(1)}s of ${duration.toFixed(1)}s, which is ` +
+    `${(at / (1024 * 1024)).toFixed(1)}MB into "${String(file.name).slice(0, 40)}"`
+  );
+  await options.fetchRegion(at, RESUME_REGION_BYTES);
+  return true;
+}
+
+/**
+ * What one file declares about itself: format, duration, and where its own
+ * timeline begins.
+ *
+ * The same header the track table is read from, and the container instance is
+ * cached per file, so asking for this after the tracks costs no read at all.
+ * It exists because the alternative was a second reader: the session manager
+ * used to spawn an ffmpeg over the proxy's own HTTP to learn where a sidecar
+ * soundtrack's timeline begins, and that read cost 8121 ms in the field on
+ * 2026-09-03 while this layer had read the same header in 8 ms in the same
+ * second.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {{ prefetchEdges?: () => Promise<unknown> }} [options]
+ * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
+ */
+export async function containerMediaInfoOf(torrent, fileIndex, sourceKey, options = {}) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !Number.isFinite(file.length) || file.length <= 0) {
+    return null;
+  }
+  if (typeof options.prefetchEdges === "function") {
+    try {
+      await options.prefetchEdges();
+    } catch {
+      // A prefetch that failed is not a reason to skip the read: the read
+      // fetches what it needs itself, only more slowly.
+    }
+  }
+  const readRange = async (start, end) =>
+    readFetching(file, start, Math.min(end, file.length - 1));
+  try {
+    const info = await containerOrchestrator.getMediaInfo({
+      sourceKey,
+      fileIndex,
+      readRange,
+      fileSize: file.length,
+      label: String(file.name ?? "")
+    });
+    if (info) {
+      logger.info(
+        `container-info: "${String(file.name).slice(0, 40)}" is ${info.format}, ` +
+        `${info.durationSeconds === null ? "duration not declared" : `${info.durationSeconds.toFixed(3)}s`}, ` +
+        `${info.startTimeSeconds === null
+          ? "start of its timeline not declared"
+          : `its timeline starts at ${info.startTimeSeconds.toFixed(6)}s`}`
+      );
+    }
+    return info;
+  } catch (error) {
+    logger.warn(
+      `container-info: "${String(file.name).slice(0, 40)}" could not be read: ${error?.message ?? error}`
+    );
+    return null;
+  }
+}
+
 /**
  * Forget one file's tracks, or every file of a source.
  *

package/services/torrent-worker/fastest-wires.js

@@ -24,6 +24,19 @@
  * instead of staying with whoever got it first.
  */
 
+/**
+ * How short a piece's remaining tail must be for a second copy of it to be
+ * worth asking for.
+ *
+ * Sixteen blocks is 256 KB against the 4-16 MB piece they hold up. The figure
+ * comes from what was measured rather than chosen for roundness: the tails a
+ * blocked reader waits on were 2 to 14 blocks of 512 on 2026-08-19, and 3 of
+ * 512 in the field failure of 2026-09-03 that took 46.3 s. Above this the piece
+ * is still arriving normally and duplicating would spend the shared link on
+ * bytes already on their way.
+ */
+const SHORT_TAIL_BLOCKS = 16;
+
 /**
  * The library's own request entry. Internal, so its absence must be noticed
  * rather than swallowed: without it this lever silently does nothing.
@@ -269,6 +282,15 @@ export function duplicateTailFor(torrent, pieceIndex) {
     return { duplicated: 0, missing: missing.length, wires: candidates.length };
   }
 
+  // A tail this short is what a blocked read is actually waiting on, and a
+  // second copy of it costs a few dozen kilobytes. A longer one is a piece
+  // still arriving normally, where duplicating would spend the shared link on
+  // bytes that are already coming — measured 2026-08-19, the tails a reader
+  // waits on are 2 to 14 blocks of 512.
+  if (missing.length > SHORT_TAIL_BLOCKS) {
+    return { duplicated: 0, missing: missing.length, wires: candidates.length };
+  }
+
   let duplicated = 0;
   // One block per wire: that is what the pipelines can usefully take at once,
   // and it needs no number of its own.
@@ -281,13 +303,14 @@ export function duplicateTailFor(torrent, pieceIndex) {
     // or it would free a THIRD wire's block as well.
     if (torrent._request(candidates[index], pieceIndex, false) === true) {
       duplicated += 1;
-      continue;
     }
-    // The wire's pipeline is full. The block stays in the piece's cancellation
-    // stack and will be handed to whoever asks next, which is harmless — it is
-    // already in flight elsewhere — but there is no point asking the remaining
-    // wires, whose pipelines are no emptier.
-    break;
+    // A refusal means THAT wire's pipeline is full, and says nothing about the
+    // next one's — pipelines are per wire. This used to stop the whole pass on
+    // the first refusal, on the stated reasoning that the remaining wires were
+    // "no emptier", which is an assumption about other peers' queues that
+    // nothing here measures. The block whose reservation was freed stays in the
+    // piece's cancellation stack and is handed to whoever asks next, which is
+    // harmless: it is already in flight elsewhere.
   }
   return { duplicated, missing: missing.length, wires: candidates.length };
 }

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

@@ -950,11 +950,18 @@ export async function* readFragments({
           const result = askFastestWiresFor(torrent, pieceIndex);
           if (result.asked === 0) {
             tailWhenNothingPlaced = describePieceTail(torrent, pieceIndex);
-            // Nothing could be placed the ordinary way, which means every block
-            // is spoken for. That is exactly when a second copy of the last
-            // blocks is worth asking for.
-            duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
           }
+          // Every attempt, not only the ones where nothing else could be placed.
+          // The ordinary steering asks for whatever blocks are still free; the
+          // read, meanwhile, ends when the LAST block arrives, and that block is
+          // reserved to one wire whether or not other blocks could be asked for.
+          // Field 2026-09-03: 46.3 s on one piece, ordinary requests placed on
+          // 54 of 87 attempts throughout, and a tail of 3 blocks of 512 held by
+          // wires at 51-99 KB/s to the end — while duplication, which ran only
+          // on the 33 attempts that placed nothing, managed 5 blocks in the
+          // whole wait. `duplicateTailFor` bounds itself by the tail's length,
+          // so a piece that is merely still arriving is left alone.
+          duplicated += duplicateTailFor(torrent, pieceIndex).duplicated;
           pushed = {
             asked: pushed.asked + result.asked,
             refusedWhileReserved:

package/services/torrent-worker/pool-adapter.js

@@ -204,6 +204,41 @@ export class WorkerTorrentPool {
     return Array.isArray(answer?.tracks) ? answer.tracks : [];
   }
 
+  /**
+   * Start fetching the region a viewer is about to resume at. Named in seconds
+   * here; the worker turns it into bytes, where the file's duration is readable.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} positionSeconds
+   * @returns {Promise<boolean>}
+   */
+  async warmResumePosition(torrent, fileIndex, positionSeconds) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return false;
+    }
+    const answer = await this.#client.warmResumePosition({ sourceKey, fileIndex, positionSeconds });
+    return answer?.started === true;
+  }
+
+  /**
+   * What one file declares about itself: format, duration, and where its own
+   * timeline begins.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
+   */
+  async getContainerMediaInfo(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    const answer = await this.#client.getContainerMediaInfo({ sourceKey, fileIndex });
+    return answer?.info ?? null;
+  }
+
   /**
    * The audio tracks one file declares, in the order ffmpeg numbers them
    * `0:a:N`.

package/services/torrent-worker/protocol.js

@@ -81,6 +81,18 @@ export const Command = {
    * file beside it, which is the same question about a different file.
    */
   CONTAINER_TRACKS: "container-tracks",
+  /**
+   * What a file declares about itself as a whole — format, duration, and where
+   * its own timeline begins. Read from the same header, by the same reader, as
+   * the track table above; the alternative was a second ffmpeg over the proxy's
+   * own HTTP reading the same bytes again.
+   */
+  CONTAINER_MEDIA_INFO: "container-media-info",
+  /**
+   * Start fetching the region a viewer is about to resume at, named in seconds
+   * and turned into bytes here, where the file's own duration can be read.
+   */
+  WARM_POSITION: "warm-position",
   /** Cues of one subtitle track, from the clusters already downloaded. */
   SUBTITLE_CUES: "subtitle-cues",
   /** Shut the client down, optionally deleting downloaded data. */

package/services/torrent-worker/subtitle-cues.js

@@ -311,6 +311,21 @@ function nextSeq(state, trackNumber) {
  */
 export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
   const key = `${sourceKey}:${fileIndex}`;
+  // A torrent that cannot say which pieces it holds makes every range read as
+  // "not downloaded", so the walk reads nothing and returns an empty list —
+  // which is also what a file with no cues yet returns, and that is how this
+  // went unnoticed for a session (2026-09-03: 283 clusters indexed, 0 walked,
+  // the browser served `WEBVTT` and nothing else). The stand-in the main thread
+  // holds is exactly such a torrent; only the thread that owns the object has
+  // the bitfield. Nothing here can repair that, so it says so instead.
+  if (!torrent?.bitfield || !(Number(torrent?.pieceLength) > 0)) {
+    logger.warn(
+      `subtitles: asked for cues of "${String(torrent?.name ?? sourceKey).slice(0, 40)}" ` +
+      "on a torrent that cannot say which pieces it holds — no cluster can be read here, " +
+      "and the answer would be an empty document indistinguishable from a file with no cues"
+    );
+    return { cues: [], coveredClusters: 0, indexedClusters: 0, track: null };
+  }
   const plan = await planFor(torrent, fileIndex, key);
   const state = stateFor(key);
   const track = plan?.tracks?.find((candidate) => candidate.trackNumber === trackNumber) ?? null;

package/services/torrent-worker/worker.js

@@ -28,7 +28,12 @@ import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
 import { readFragments, supplyFiguresFor } from "./piece-reader.js";
 import { cuesHeldFor, declaredSubtitleTracksOf, subtitleTracksOf, warmSubtitleCues } from "./subtitle-cues.js";
-import { CONTAINER_HEAD_BYTES, containerTracksOf } from "./container-tracks.js";
+import {
+  CONTAINER_HEAD_BYTES,
+  containerMediaInfoOf,
+  containerTracksOf,
+  warmResumePosition
+} from "./container-tracks.js";
 import { fillFileInBackground } from "./background-fill.js";
 import { Command, Event } from "./protocol.js";
 import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../memory-report.js";
@@ -418,6 +423,45 @@ async function runCommand(command, params, id) {
       };
     }
 
+    case Command.CONTAINER_MEDIA_INFO: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return {
+        info: await containerMediaInfoOf(torrent, params.fileIndex, params.sourceKey, {
+          // Same reason as the track table above: the file this is asked about
+          // is often one nobody has played yet, so its head has to be fetched
+          // before there is anything to read.
+          prefetchEdges: () =>
+            pool.prefetchFileEdges(torrent, params.fileIndex, {
+              headBytes: CONTAINER_HEAD_BYTES,
+              tailBytes: 0,
+              timeoutMs: 60_000
+            })
+        })
+      };
+    }
+
+    case Command.WARM_POSITION: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return {
+        started: await warmResumePosition(
+          torrent,
+          params.fileIndex,
+          params.sourceKey,
+          params.positionSeconds,
+          {
+            prefetchEdges: () =>
+              pool.prefetchFileEdges(torrent, params.fileIndex, {
+                headBytes: CONTAINER_HEAD_BYTES,
+                tailBytes: 0,
+                timeoutMs: 60_000
+              }),
+            fetchRegion: (start, bytes) =>
+              pool.prefetchFileRegion(torrent, params.fileIndex, start, bytes)
+          }
+        )
+      };
+    }
+
     case Command.SUBTITLE_CUES: {
       const torrent = await requireTorrent(params.sourceKey);
       const held = await cuesHeldFor(torrent, params.fileIndex, params.sourceKey, params.trackNumber);