@torrent-tv/proxy 2.88.5 → 2.89.0

package/test/reads-not-yet-arrived.test.js

@@ -0,0 +1,218 @@
+/**
+ * @file A read whose bytes have not arrived is not an answer about the file.
+ *
+ * Field 2026-10-01: the subtitle plan of an episode was read while its Cues
+ * table was still downloading, the read was given up, and the plan kept "no
+ * clusters" for the life of the process — the track showed nothing for a whole
+ * session while the same table, read eleven seconds later for the keyframes,
+ * was there. The same shape was in the container choice, the track table, the
+ * keyframe table, MP4's `moov` and AVI's `idx1`. Every check here makes the
+ * bytes missing first and present afterwards, and asks the same object again.
+ *
+ * Fakes only: a buffer and a reader over it. No torrent, no thread.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { MatroskaContainer } from "../services/media/container/MatroskaContainer.js";
+import { Mp4Container } from "../services/media/container/Mp4Container.js";
+import { AviContainer } from "../services/media/container/AviContainer.js";
+import { ContainerOrchestrator } from "../services/media/ContainerOrchestrator.js";
+import { KeyframeTables } from "../services/media/KeyframeTables.js";
+import { isUnavailable } from "../services/media/container/unavailable.js";
+import {
+  ID,
+  buildMatroska,
+  clusterData,
+  cueBlock,
+  element,
+  readerOver,
+  stringElement,
+  trackEntry,
+  uintElement
+} from "./helpers/matroska-file.js";
+
+const quiet = { info() {}, warn() {} };
+
+function episode({ subtitleLanguage = null, cuesBeforeClusters = false, cues = [1], extraTrack = null } = {}) {
+  const tracks = [
+    trackEntry({ number: 1, type: 1, codecId: "V_MPEG4/ISO/AVC", language: "jpn" }),
+    trackEntry({ number: 3, type: 17, codecId: "S_TEXT/UTF8", language: subtitleLanguage })
+  ];
+  if (extraTrack) {
+    tracks.push(extraTrack);
+  }
+  return buildMatroska({
+    tracks,
+    cues,
+    cuesBeforeClusters,
+    clusters: [
+      { ticks: 0, data: clusterData({ ticks: 0, blocks: [cueBlock({ track: 3, relativeTicks: 100, durationTicks: 900, text: "one" })] }) },
+      { ticks: 5000, data: clusterData({ ticks: 5000, blocks: [cueBlock({ track: 3, relativeTicks: 0, durationTicks: 900, text: "two" })] }) }
+    ]
+  });
+}
+
+test("a subtitle plan read before the Cues table arrived is not kept; read again, it names the clusters", async () => {
+  const { file, cuesAt, clusterAt } = episode({ cues: [1, 3] });
+  let tailHere = false;
+  const { read } = readerOver(file, { missing: (start) => !tailHere && start >= cuesAt });
+  const container = new MatroskaContainer({ readRange: read, fileSize: file.length });
+
+  await assert.rejects(container.readSubtitlePlan(), (error) => isUnavailable(error));
+
+  tailHere = true;
+  const plan = await container.readSubtitlePlan();
+  assert.equal(plan.cuesState, "complete");
+  assert.deepEqual(plan.tracks[0].clusterPositions, clusterAt, "both clusters the table names for the track");
+});
+
+test("a read that returns fewer bytes than asked is not taken for the element", async () => {
+  const { file } = episode();
+  const { read } = readerOver(file, { short: true });
+  await assert.rejects(new MatroskaContainer({ readRange: read, fileSize: file.length }).readTracks(), (error) =>
+    isUnavailable(error)
+  );
+});
+
+test("a head that has not arrived leaves no container behind, and the next ask builds one", async () => {
+  const { file } = episode();
+  let headHere = false;
+  const { read } = readerOver(file, { missing: (start) => !headHere && start === 0 });
+  const containers = new ContainerOrchestrator();
+  const params = { sourceKey: "s", fileIndex: 0, readRange: read, fileSize: file.length, label: "x.mkv" };
+
+  await assert.rejects(containers.containerFor(params), (error) => isUnavailable(error));
+  assert.equal(containers.known("s", 0), undefined, "nothing was kept for a head that is not here");
+  assert.deepEqual(await containers.getTracks(params), [], "the track table answers nothing yet");
+
+  headHere = true;
+  const container = await containers.containerFor(params);
+  assert.equal(container.formatName, "matroska");
+  assert.equal((await containers.getTracks(params)).length, 2);
+});
+
+test("a keyframe table asked for while its Cues are missing stays unanswered, and is filled when they arrive", async () => {
+  const { file, cuesAt } = episode();
+  let tailHere = false;
+  const { read } = readerOver(file, { missing: (start) => !tailHere && start >= cuesAt });
+  const containers = new ContainerOrchestrator();
+  const params = { sourceKey: "k", fileIndex: 0, readRange: read, fileSize: file.length, label: "x.mkv" };
+  const tables = new KeyframeTables({
+    readTable: async () => {
+      const index = await containers.getKeyframeIndex(params);
+      return { times: index?.times ?? null, tolerance: 0, format: "matroska" };
+    },
+    logger: quiet
+  });
+
+  await assert.rejects(tables.read({ sourceKey: "k", fileIndex: 0 }), (error) => isUnavailable(error));
+  const table = tables.of({ sourceKey: "k", fileIndex: 0 });
+  assert.equal(table.answered, false, "a read that did not arrive is not an answer");
+
+  tailHere = true;
+  tables.readAgainIfUnanswered({ sourceKey: "k", fileIndex: 0 });
+  await tables.read({ sourceKey: "k", fileIndex: 0 });
+  assert.equal(table.answered, true);
+  assert.deepEqual(table.times, [0, 5], "the same object the sessions hold now carries the times");
+});
+
+test("a Cues element stored before the first cluster, with no SeekHead entry, is found", async () => {
+  const { file } = episode({ cuesBeforeClusters: true });
+  const { read } = readerOver(file);
+  const index = await new MatroskaContainer({ readRange: read, fileSize: file.length }).parseKeyframeIndex();
+  assert.deepEqual(index.times, [0, 5]);
+});
+
+test("a Tracks element larger than the head window is read by its own size", async () => {
+  // A CodecPrivate of 80 KB pushes the end of Tracks past the 64 KB head.
+  const big = element(
+    ID.TRACK_ENTRY,
+    Buffer.concat([
+      uintElement(ID.TRACK_NUMBER, 4),
+      uintElement(ID.TRACK_TYPE, 17),
+      stringElement(ID.CODEC_ID, "S_TEXT/ASS"),
+      element(0x63a2, Buffer.alloc(80 * 1024, 0x20))
+    ])
+  );
+  const { file } = episode({ extraTrack: big });
+  const { read } = readerOver(file);
+  const tracks = await new MatroskaContainer({ readRange: read, fileSize: file.length }).readTracks();
+  assert.deepEqual(tracks.map((track) => track.trackNumber), [1, 3, 4]);
+});
+
+test("the language: LanguageBCP47 wins, then Language, then the format's default `eng`; `und` stays unknown", async () => {
+  const cases = [
+    { entry: { language: null }, language: "eng", source: "default" },
+    { entry: { language: "" }, language: "eng", source: "language" },
+    { entry: { language: "rus" }, language: "rus", source: "language" },
+    { entry: { language: null, languageBcp47: "pt-BR" }, language: "pt-BR", source: "bcp47" },
+    { entry: { language: "por", languageBcp47: "pt-BR" }, language: "pt-BR", source: "bcp47" },
+    { entry: { language: "und" }, language: "und", source: "language" }
+  ];
+  for (const { entry, language, source } of cases) {
+    const { file } = buildMatroska({
+      tracks: [trackEntry({ number: 3, type: 17, codecId: "S_TEXT/UTF8", ...entry })],
+      cues: null,
+      clusters: [{ ticks: 0, data: clusterData({ ticks: 0, blocks: [] }) }]
+    });
+    const { read } = readerOver(file);
+    const [track] = await new MatroskaContainer({ readRange: read, fileSize: file.length }).readTracks();
+    assert.equal(track.language, language, JSON.stringify(entry));
+    assert.equal(track.languageSource, source, JSON.stringify(entry));
+  }
+});
+
+/** @param {string} type @param {Buffer} payload */
+function box(type, payload) {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(8 + payload.length, 0);
+  header.write(type, 4, "latin1");
+  return Buffer.concat([header, payload]);
+}
+
+test("an MP4 whose `moov` has not arrived keeps nothing; read again, it answers", async () => {
+  const mvhd = Buffer.alloc(100);
+  mvhd.writeUInt32BE(1000, 12); // timescale
+  mvhd.writeUInt32BE(5000, 16); // duration
+  const ftyp = box("ftyp", Buffer.from("isom\0\0\0\0isom", "latin1"));
+  const moov = box("moov", box("mvhd", mvhd));
+  const file = Buffer.concat([ftyp, moov]);
+  let moovHere = false;
+  const { read } = readerOver(file, { missing: (start) => !moovHere && start >= ftyp.length });
+  const container = new Mp4Container({ readRange: read, fileSize: file.length });
+
+  await assert.rejects(container.readMediaInfo(), (error) => isUnavailable(error));
+  moovHere = true;
+  assert.equal((await container.readMediaInfo()).durationSeconds, 5);
+});
+
+test("an MP4 `moov` larger than this reads whole is refused by name, not reported absent", async () => {
+  const ftyp = box("ftyp", Buffer.from("isom\0\0\0\0isom", "latin1"));
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(40 * 1024 * 1024, 0);
+  header.write("moov", 4, "latin1");
+  const file = Buffer.concat([ftyp, header, Buffer.alloc(64)]);
+  const { read } = readerOver(file);
+  const container = new Mp4Container({ readRange: read, fileSize: file.length });
+  assert.equal(await container.readSubtitlePlan(), null);
+  assert.deepEqual(container.moovRefused, { size: 40 * 1024 * 1024, limit: 32 * 1024 * 1024 });
+});
+
+test("an AVI head that has not arrived leaves no media info behind", async () => {
+  const avih = Buffer.alloc(56);
+  avih.writeUInt32LE(40_000, 0); // 25 frames a second
+  avih.writeUInt32LE(250, 16); // ten seconds
+  const chunk = Buffer.concat([Buffer.from("avih", "latin1"), Buffer.from([56, 0, 0, 0]), avih]);
+  const list = Buffer.concat([Buffer.from("LIST", "latin1"), Buffer.alloc(4), Buffer.from("hdrl", "latin1"), chunk]);
+  list.writeUInt32LE(list.length - 8, 4);
+  const riff = Buffer.concat([Buffer.from("RIFF", "latin1"), Buffer.alloc(4), Buffer.from("AVI ", "latin1"), list]);
+  riff.writeUInt32LE(riff.length - 8, 4);
+  let here = false;
+  const { read } = readerOver(riff, { missing: () => !here });
+  const container = new AviContainer({ readRange: read, fileSize: riff.length });
+  await assert.rejects(container.readMediaInfo(), (error) => isUnavailable(error));
+  here = true;
+  assert.equal((await container.readMediaInfo()).durationSeconds, 10);
+});

package/test/segment-store.test.js

@@ -10,6 +10,7 @@ import os from "node:os";
 import path from "node:path";
 import { directoryNameFor, SegmentStore } from "../services/storage/segment-store/SegmentStore.js";
 import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
+import { SEGMENT_CUT_TIME_DELTA_SECONDS } from "../services/encode/output/index.js";
 
 /**
  * @returns {{ store: SegmentStore, root: string, lines: string[] }}
@@ -35,6 +36,19 @@ function writeSegment(dir, index, bytes = 16) {
 
 const KEY = "torrent:abc:fmt=fmp4:grid=kf@0:video-only:v=0/copy";
 
+test("a complete audio cut within the configured muxer delta remains usable", (t) => {
+  const { store, root } = storeInATempRoot();
+  t.after(() => { store.dropAll("the check is over"); rmSync(root, { recursive: true, force: true }); });
+  const format = { ...fmp4Format, readMediaRanges: () => [{ start: 0, end: 4.738913832199547 }],
+    mediaCoverageEnd: (ranges) => ranges.at(-1).end };
+  const dir = store.directoryFor(KEY);
+  store.useFormat(KEY, format);
+  const endSeconds = 4.755 - SEGMENT_CUT_TIME_DELTA_SECONDS;
+  writeFileSync(path.join(dir, "making-0-00000.mp4"), Buffer.alloc(16));
+  assert.equal(store.publish(KEY, "making-0-00000.mp4", format, { endSeconds }), "segment-00000.mp4");
+  assert.ok(store.mediaRangesOf(KEY, 0, { endSeconds }));
+});
+
 test("a closed but truncated non-final piece is not published or reused", (t) => {
   const { store, root } = storeInATempRoot();
   t.after(() => { store.dropAll("the check is over"); rmSync(root, { recursive: true, force: true }); });

package/test/subtitle-cue-walk.test.js

@@ -19,7 +19,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { Readable } from "node:stream";
 
-import { cuesHeldFor, warmSubtitleCues, forgetSubtitles } from "../services/media/SubtitleCues.js";
+import { cuesHeldFor, warmSubtitleCues, forgetSubtitles, subtitleTracksOf } from "../services/media/SubtitleCues.js";
 import { heldFileOver } from "./helpers/held-file.js";
 
 const ID_EBML = 0x1a45dfa3;
@@ -335,12 +335,27 @@ test("one walk fills every track, and a second call reads no cluster again", asy
   }
 });
 
+test("the warm pass walks nothing for a file nobody has asked about", async () => {
+  const { file } = buildFile();
+  const { torrent, reads } = torrentOver(file);
+  const sourceKey = "9".repeat(40);
+  forgetSubtitles(sourceKey);
+  try {
+    assert.deepEqual(await warmSubtitleCues(heldFileOver(torrent, 0, sourceKey)), []);
+    assert.equal(reads.length, 0, "neither its head nor its Cues table was read for it");
+  } finally {
+    forgetSubtitles(sourceKey);
+  }
+});
+
 test("the warm pass reports what is new, by the number the browser knows", async () => {
   const { file } = buildFile();
   const { torrent } = torrentOver(file);
   const sourceKey = "e".repeat(40);
   forgetSubtitles(sourceKey);
   try {
+    // A browser asking for a track is what makes a file one the walk follows.
+    await subtitleTracksOf(heldFileOver(torrent, 0, sourceKey));
     const first = await warmSubtitleCues(heldFileOver(torrent, 0, sourceKey));
     assert.deepEqual(
       first.map((entry) => [entry.trackIndex, entry.cues.length, entry.language]).sort(),

package/test/subtitle-plan-waits.test.js

@@ -0,0 +1,125 @@
+/**
+ * @file The subtitle plan is kept only once it has been read; a plan whose
+ * read finishes later serves the same pass; and cues the container takes back
+ * leave by the numbers they were sent under.
+ *
+ * Fakes only: a stand-in container and a held file of plain functions.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { cuesHeldFor, forgetSubtitles, subtitleTracksOf, warmSubtitleCues } from "../services/media/SubtitleCues.js";
+import { BytesUnavailable } from "../services/media/container/unavailable.js";
+
+const PLAN = {
+  tracks: [{ trackNumber: 2, declaredIndex: 0, codecId: "S_TEXT/UTF8", language: "eng", languageSource: "default", clusterPositions: [] }],
+  declared: [],
+  secondsPerTick: 0.001,
+  segmentDataOffset: 0
+};
+
+function heldFile(sourceKey, container) {
+  return {
+    sourceKey,
+    fileIndex: 0,
+    name: "film.mkv",
+    length: 1000,
+    container: async () => container(),
+    heldRanges: async () => [[0, 999]],
+    readHeld: async () => Buffer.alloc(0)
+  };
+}
+
+test("a plan whose bytes have not arrived is not kept; the next ask reads it", async () => {
+  const sourceKey = "p".repeat(40);
+  forgetSubtitles(sourceKey);
+  let here = false;
+  const container = () => {
+    if (!here) {
+      throw new BytesUnavailable(900, 999, 0);
+    }
+    return { readSubtitlePlan: async () => PLAN, readHeldCues: async () => ({ found: new Map(), covered: 0, indexed: 0, withdrawn: [] }) };
+  };
+  try {
+    assert.deepEqual(await subtitleTracksOf(heldFile(sourceKey, container)), []);
+    here = true;
+    const tracks = await subtitleTracksOf(heldFile(sourceKey, container));
+    assert.deepEqual(tracks.map((track) => [track.trackNumber, track.language, track.languageSource]), [[2, "eng", "default"]]);
+  } finally {
+    forgetSubtitles(sourceKey);
+  }
+});
+
+test("a plan read that finishes later serves the pass that asked, with no further arrival", async () => {
+  const sourceKey = "q".repeat(40);
+  forgetSubtitles(sourceKey);
+  let release;
+  let walks = 0;
+  const arrived = new Promise((resolve) => {
+    release = resolve;
+  });
+  const container = {
+    readSubtitlePlan: async () => {
+      await arrived;
+      return PLAN;
+    },
+    // A cluster is read once: the first pass finds the line, later ones nothing.
+    readHeldCues: async () => {
+      walks += 1;
+      return {
+        found: walks === 1 ? new Map([[2, [{ startSeconds: 1, endSeconds: 2, text: "line", source: 77 }]]]) : new Map(),
+        covered: 1,
+        indexed: 1,
+        withdrawn: []
+      };
+    }
+  };
+  try {
+    // The file is one somebody asked about: a browser's seed is under way.
+    const seed = cuesHeldFor(heldFile(sourceKey, () => container), 2);
+    const warm = warmSubtitleCues(heldFile(sourceKey, () => container));
+    release();
+    await seed;
+    const entries = await warm;
+    assert.equal(entries.length, 1, "the one pass pushed what the plan led to");
+    assert.deepEqual(entries[0].cues.map((cue) => [cue.text, cue.seq]), [["line", 1]]);
+  } finally {
+    forgetSubtitles(sourceKey);
+  }
+});
+
+test("cues read from a position the container withdraws are taken back by their numbers", async () => {
+  const sourceKey = "r".repeat(40);
+  forgetSubtitles(sourceKey);
+  let passNumber = 0;
+  const container = {
+    readSubtitlePlan: async () => PLAN,
+    readHeldCues: async () => {
+      passNumber += 1;
+      return passNumber === 1
+        ? {
+            found: new Map([[2, [
+              { startSeconds: 1, endSeconds: 2, text: "real", source: 10 },
+              { startSeconds: 3, endSeconds: 4, text: "false", source: 50 }
+            ]]]),
+            covered: 2,
+            indexed: 2,
+            withdrawn: []
+          }
+        : { found: new Map(), covered: 1, indexed: 1, withdrawn: [50] };
+    }
+  };
+  try {
+    await subtitleTracksOf(heldFile(sourceKey, () => container));
+    const first = await warmSubtitleCues(heldFile(sourceKey, () => container));
+    assert.deepEqual(first[0].cues.map((cue) => [cue.text, cue.seq]), [["real", 1], ["false", 2]]);
+    const second = await warmSubtitleCues(heldFile(sourceKey, () => container));
+    assert.deepEqual(second[0].withdrawn, [2], "the false cue is named by the number it was sent under");
+    assert.deepEqual(second[0].cues, []);
+    const held = await cuesHeldFor(heldFile(sourceKey, () => container), 2);
+    assert.deepEqual(held.cues.map((cue) => cue.text), ["real"], "and it is gone from what is held");
+  } finally {
+    forgetSubtitles(sourceKey);
+  }
+});

package/test/subtitle-track-numbering.test.js

@@ -374,13 +374,18 @@ test("where the file writes RFC 5646, that is the language", async () => {
   assert.equal(track.languageBcp47, "pt-BR");
 });
 
-test("an omitted Matroska Language element stays unstated rather than becoming the RFC default", async () => {
+test("an omitted Matroska Language element is the format's default, `eng`, and says it was not written", async () => {
+  // RFC 9559 §5.1.4.1.19 gives Language the default `eng`; RFC 8794 §11.1.19
+  // says an element equal to its default need not be written, and a reader MUST
+  // read the default. Until 2026-10-01 such a track was offered as Unknown.
   const file = fileWithFlags();
   const plan = await MatroskaContainer.readSubtitlePlan(readerOver(file), file.length);
 
   const track = plan.tracks.find((entry) => entry.trackNumber === 6);
   const declared = plan.declared.find((entry) => entry.trackNumber === 6);
-  assert.equal(track.language, "");
-  assert.equal(track.declaresLanguage, false);
+  assert.equal(track.language, "eng");
+  assert.equal(track.languageSource, "default");
+  assert.equal(track.declaresLanguage, false, "the element itself was not written");
+  assert.equal(declared.language, "eng");
   assert.equal(declared.declaresLanguage, false);
 });

package/test/viewer-starts-on-map.test.js

@@ -0,0 +1,27 @@
+/**
+ * @file Where viewers stand, read off a merged priority map — the times the
+ * subtitle walk reads first.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { emptyMap, mapForViewer, mergeMaps, viewerStartsOn } from "../services/viewer/PriorityMap.js";
+
+test("each viewer's position is a step up in the merged map", () => {
+  const map = mergeMaps([
+    mapForViewer({ atSeconds: 30, durationSeconds: 300, allowanceSeconds: 5 }),
+    mapForViewer({ atSeconds: 200, durationSeconds: 300, allowanceSeconds: 5 })
+  ]);
+  assert.deepEqual(viewerStartsOn(map), [30, 200]);
+});
+
+test("a viewer at the very start, a stopped viewer, and nobody", () => {
+  assert.deepEqual(viewerStartsOn(mapForViewer({ atSeconds: 0, durationSeconds: 60, allowanceSeconds: 5 })), [0]);
+  assert.deepEqual(
+    viewerStartsOn(mapForViewer({ atSeconds: 12, durationSeconds: 60, allowanceSeconds: 5, playing: false })),
+    [12]
+  );
+  assert.deepEqual(viewerStartsOn(emptyMap(60)), []);
+  assert.deepEqual(viewerStartsOn(null), []);
+});

package/utils/coalesce.js

@@ -0,0 +1,41 @@
+/**
+ * @file One run of a piece of work per key at a time, and one more after it
+ * whenever it was asked for meanwhile.
+ *
+ * For work that is asked for by events — pieces arriving — and that reads
+ * whatever is there when it runs. A request that arrives while a run is going
+ * is neither queued nor dropped: it is remembered as "run again", once,
+ * because one more run reads everything that arrived during the first. Dropping
+ * it lost exactly the run that would have found the last pieces of a file
+ * (`research/subtitles-never-appear-2026-10-01.md`).
+ */
+
+/**
+ * @template {unknown[]} A
+ * @param {(...args: A) => Promise<void>} work
+ * @returns {(key: string, ...args: A) => Promise<void>}
+ */
+export function coalescing(work) {
+  /** @type {Set<string>} */
+  const running = new Set();
+  /** The latest arguments a run was asked for with meanwhile. @type {Map<string, A>} */
+  const askedAgain = new Map();
+  const run = async (key, ...args) => {
+    if (running.has(key)) {
+      askedAgain.set(key, args);
+      return;
+    }
+    running.add(key);
+    try {
+      await work(...args);
+    } finally {
+      running.delete(key);
+      const again = askedAgain.get(key);
+      if (again) {
+        askedAgain.delete(key);
+        void run(key, ...again);
+      }
+    }
+  };
+  return run;
+}