@torrent-tv/proxy 2.73.0 → 2.73.1

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.73.1
+
+- **Fix**: The catch-up pull for embedded subtitles is answered by the thread that owns the torrent, so a viewer no longer loses the beginning of an episode. Field 2026-09-03 on `[HorribleSubs] Drifters - 04 [1080p].mkv`: the file had been downloaded in an earlier sitting, so the worker's cluster walk found cues 1.5 s after it was opened and pushed four batches — cursor 1 to 31, everything up to 81.7 s — before the browser had subscribed. The browser then did the pull that exists for exactly that case and got a seven-byte `WEBVTT` with `x-subtitle-covered-clusters: 0` against 283 indexed; it held 330 cues spanning 81.7-1310.2 s, which is precisely the first push it saw. The parsing was never at fault — the same file put through this proxy's own reader produces clean English from 5.4 s onward — the pull was simply running on the MAIN thread, where the torrent is a stand-in with no `bitfield` and no `pieceLength`, so every range read as "not downloaded" and nothing was walked. It goes to the worker now, over the command that already existed and had no caller. That also settles a second thing: the found-order cursor the browser follows comes from ONE register, so a cursor from a pull and a cursor from a push are comparable, which two separate walks could not guarantee.
+- **Fix**: A walk asked of a torrent that cannot say which pieces it holds says so in the log instead of returning an empty document. Emptiness is the right answer for a file with no cues yet, and that is how the defect above stayed invisible for a whole session.
+
 ## 2.73.0
 
 - **New**: `Container.readMediaInfo()` — what a file declares about ITSELF: its format, its duration, and where its own timeline begins. Matroska reads Duration and TimestampScale from `Info` and takes the start from the first Cluster's timestamp (RFC 9559 states no start-time element, so that IS the start); MP4 reads `mvhd` and the empty edit of `elst` (ISO/IEC 14496-12 §8.6.6); AVI multiplies microseconds per frame by the frame count. `null` means the container does not declare the field, which is a final answer rather than "ask someone else".

package/package.json

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

package/services/controllers/SubtitleController.js

@@ -84,7 +84,7 @@ export class SubtitleController {
       const target = track ?? domainTracks.find((t) => t.declaredIndex === idx) ?? null;
       const trackNumber = target?.trackNumber ?? track?.trackNumber;
       if (trackNumber != null) {
-        held = await this.orchestrator.getCues(torrent, fileIndex, sourceKey, trackNumber);
+        held = await this.orchestrator.getCues(this.torrentPool, torrent, fileIndex, sourceKey, trackNumber);
       }
     } catch {}
     if (held && Array.isArray(held.cues)) {

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-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/test/subtitle-cue-source.test.js

@@ -0,0 +1,104 @@
+/**
+ * @file WHICH THREAD answers a pull for subtitle cues.
+ *
+ * Field 2026-09-03, on `[HorribleSubs] Drifters - 04 [1080p].mkv`. The file had
+ * been downloaded in an earlier sitting, so the torrent worker's cluster walk
+ * found cues 1.5 s after the file was opened and pushed four batches — cursor 1
+ * to 31, covering everything up to 81.7 s — before the browser had subscribed.
+ * The browser's catch-up pull, which exists for exactly that case, answered a
+ * seven-byte `WEBVTT` with `x-subtitle-covered-clusters: 0` against 283
+ * indexed. So the viewer watched the first 82 s with no subtitles and the rest
+ * of the episode with them.
+ *
+ * The pull ran on the MAIN thread, where the torrent is a stand-in carrying
+ * `infoHash`, `name` and a `files` list — no `bitfield`, no `pieceLength`. The
+ * walk decides what it may read from those two, so every range read as "not
+ * downloaded", nothing was walked, and an empty document came back. An empty
+ * document is also the right answer for a file that holds no cues yet, which is
+ * why nothing reported a failure.
+ *
+ * These checks pin the two halves of the repair: the pull is addressed to the
+ * thread that owns the torrent, and a walk asked of a torrent that cannot say
+ * what it holds says so rather than answering emptily.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { SubtitleOrchestrator } from "../services/orchestrators/SubtitleOrchestrator.js";
+import { cuesHeldFor } from "../services/torrent-worker/subtitle-cues.js";
+
+/** The stand-in the main thread holds: a name, a file list, and no pieces. */
+function mainThreadTorrent() {
+  return {
+    infoHash: "0".repeat(40),
+    name: "[HorribleSubs] Drifters - 04 [1080p].mkv",
+    sourceKey: "a".repeat(40),
+    files: [{ name: "[HorribleSubs] Drifters - 04 [1080p].mkv", length: 567_535_843, createReadStream: () => { throw new Error("not reached"); } }]
+  };
+}
+
+test("a pull is answered by the thread that owns the torrent, not walked here", async () => {
+  const asked = [];
+  const pool = {
+    async getSubtitleCues(torrent, fileIndex, trackNumber) {
+      asked.push({ sourceKey: torrent.sourceKey, fileIndex, trackNumber });
+      return {
+        cues: [{ startSeconds: 5.4, endSeconds: 9.1, text: "So what if you brought them over?", seq: 1 }],
+        coveredClusters: 283,
+        indexedClusters: 283,
+        codecId: "S_TEXT/ASS",
+        codecPrivate: "",
+        language: ""
+      };
+    }
+  };
+
+  const orchestrator = new SubtitleOrchestrator({ forget() {} });
+  const held = await orchestrator.getCues(pool, mainThreadTorrent(), 33, "a".repeat(40), 3);
+
+  assert.deepEqual(asked, [{ sourceKey: "a".repeat(40), fileIndex: 33, trackNumber: 3 }]);
+  assert.equal(held.cues.length, 1);
+  assert.equal(held.coveredClusters, 283, "the walk's own figure travels back, so the header cannot claim 0 of 283");
+  // The worker answers with the track's fields flat — only plain objects cross
+  // the boundary — and the caller reads them through `held.track`.
+  assert.equal(held.track.codecId, "S_TEXT/ASS");
+});
+
+test("the cursor of a pulled cue is the found-order the worker assigned", async () => {
+  // The browser mixes cursors from pulls and pushes. Walking a second time on
+  // another thread would start a second `seq` counter and the two would not be
+  // comparable, which is the deeper reason the pull is not served locally.
+  const pool = {
+    async getSubtitleCues() {
+      return {
+        cues: [
+          { startSeconds: 5.4, endSeconds: 9.1, text: "one", seq: 1 },
+          { startSeconds: 81.7, endSeconds: 84.0, text: "two", seq: 31 }
+        ],
+        coveredClusters: 12,
+        indexedClusters: 283,
+        codecId: "S_TEXT/ASS",
+        codecPrivate: "",
+        language: ""
+      };
+    }
+  };
+  const orchestrator = new SubtitleOrchestrator({ forget() {} });
+  const held = await orchestrator.getCues(pool, mainThreadTorrent(), 33, "a".repeat(40), 3);
+  assert.deepEqual(held.cues.map((cue) => cue.seq), [1, 31]);
+});
+
+test("a pool with no channel to the worker is refused, not answered emptily", async () => {
+  const orchestrator = new SubtitleOrchestrator({ forget() {} });
+  const held = await orchestrator.getCues({}, mainThreadTorrent(), 33, "a".repeat(40), 3);
+  assert.deepEqual(held, { cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
+});
+
+test("the walk refuses a torrent that cannot say which pieces it holds", async () => {
+  // Called directly, as the main thread used to call it. Without this guard the
+  // answer is an empty list indistinguishable from a file with no cues, which
+  // is what hid the defect for a whole session.
+  const held = await cuesHeldFor(mainThreadTorrent(), 33, "b".repeat(40), 3);
+  assert.deepEqual(held, { cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
+});