@torrent-tv/proxy 2.55.14 → 2.57.0

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

@@ -0,0 +1,262 @@
+/**
+ * @file The number a subtitle track is asked for by, and one walk per file.
+ *
+ * Two rules, both found by reading on 2026-08-26 after the report that embedded
+ * subtitles appear late (`research/subtitle-delay-2026-08-26.md`):
+ *
+ * 1. The browser names a track by ffmpeg's `0:s:N`, which counts EVERY subtitle
+ *    stream. The container plan drops the picture-based ones — PGS, VobSub —
+ *    because they cannot become WebVTT, so counting the kept ones is a
+ *    different numbering as soon as a file carries one of each. What that cost:
+ *    the push landed on a track the browser does not know, and the browser's
+ *    own request found no track at all and fell through to the ffmpeg
+ *    extraction, which reads the whole film (752 s measured, 2026-08-19).
+ * 2. A file is walked once at a time. The walk marks a cluster as read only
+ *    after two suspension points, and it is started both on every verified
+ *    piece and on a 3 s timer, so two passes could read and parse the same
+ *    cluster and push the same line twice.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Readable } from "node:stream";
+import { readSubtitlePlan } from "../services/container-index/matroska-subtitles.js";
+import { cuesHeldFor, forgetSubtitles } from "../services/torrent-worker/subtitle-cues.js";
+
+const ID_EBML = 0x1a45dfa3;
+const ID_SEGMENT = 0x18538067;
+const ID_SEEK_HEAD = 0x114d9b74;
+const ID_SEEK = 0x4dbb;
+const ID_SEEK_ID = 0x53ab;
+const ID_SEEK_POSITION = 0x53ac;
+const ID_INFO = 0x1549a966;
+const ID_TIMESTAMP_SCALE = 0x2ad7b1;
+const ID_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+const ID_CODEC_ID = 0x86;
+const ID_LANGUAGE = 0x22b59c;
+const ID_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_CUE_CLUSTER_POSITION = 0xf1;
+const ID_CLUSTER = 0x1f43b675;
+const ID_TIMESTAMP = 0xe7;
+
+/** An element id, as the bytes the specification gives it. */
+function idBytes(id) {
+  const bytes = [];
+  let rest = id;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  }
+  return Buffer.from(bytes);
+}
+
+/** A size, as a four-byte EBML variable-length integer. */
+function sizeBytes(size) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(size, 0);
+  buffer[0] |= 0x10;
+  return buffer;
+}
+
+function element(id, payload) {
+  return Buffer.concat([idBytes(id), sizeBytes(payload.length), payload]);
+}
+
+function uintElement(id, value) {
+  const bytes = [];
+  let rest = value;
+  do {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  } while (rest > 0);
+  return element(id, Buffer.from(bytes));
+}
+
+function stringElement(id, value) {
+  return element(id, Buffer.from(value, "utf8"));
+}
+
+/**
+ * An unsigned value at a FIXED four bytes. A cue's cluster position has to be
+ * written twice — once to measure the table, once with the position that
+ * measurement produced — and a value-sized element would make the second table
+ * a different length from the first, moving the very cluster it names.
+ */
+function uint32Element(id, value) {
+  const payload = Buffer.alloc(4);
+  payload.writeUInt32BE(value, 0);
+  return element(id, payload);
+}
+
+function trackEntry({ number, type, codecId, language }) {
+  return element(ID_TRACK_ENTRY, Buffer.concat([
+    uintElement(ID_TRACK_NUMBER, number),
+    uintElement(ID_TRACK_TYPE, type),
+    stringElement(ID_CODEC_ID, codecId),
+    stringElement(ID_LANGUAGE, language)
+  ]));
+}
+
+/**
+ * A file whose subtitle tracks are, in the container's own order: a picture
+ * one, then two text ones. ffmpeg numbers those `0:s:0`, `0:s:1`, `0:s:2`;
+ * the plan can only read the last two.
+ *
+ * The Cues table points both text tracks at one cluster, which is written after
+ * the table so its position can be stated.
+ *
+ * @returns {{ file: Buffer, clusterAt: number }}
+ */
+function buildFile() {
+  const info = element(ID_INFO, uintElement(ID_TIMESTAMP_SCALE, 1_000_000));
+  const tracks = element(ID_TRACKS, Buffer.concat([
+    trackEntry({ number: 1, type: 1, codecId: "V_MPEG4/ISO/AVC", language: "und" }),
+    trackEntry({ number: 2, type: 17, codecId: "S_HDMV/PGS", language: "eng" }),
+    trackEntry({ number: 3, type: 17, codecId: "S_TEXT/UTF8", language: "rus" }),
+    trackEntry({ number: 4, type: 17, codecId: "S_TEXT/ASS", language: "eng" })
+  ]));
+
+  // Built twice: the cue points state where the cluster is, and that position
+  // is only known once everything before it has its final length. Every size
+  // and position here is written at a fixed width, so the draft and the final
+  // table are the same length.
+  const cuesWith = (clusterAt) => element(ID_CUES, Buffer.concat([
+    element(ID_CUE_POINT, Buffer.concat([
+      uintElement(ID_CUE_TIME, 1000),
+      element(ID_CUE_TRACK_POSITIONS, Buffer.concat([
+        uintElement(ID_CUE_TRACK, 3),
+        uint32Element(ID_CUE_CLUSTER_POSITION, clusterAt)
+      ])),
+      element(ID_CUE_TRACK_POSITIONS, Buffer.concat([
+        uintElement(ID_CUE_TRACK, 4),
+        uint32Element(ID_CUE_CLUSTER_POSITION, clusterAt)
+      ]))
+    ]))
+  ]));
+
+  const seekEntry = (targetId, position) => element(ID_SEEK, Buffer.concat([
+    element(ID_SEEK_ID, idBytes(targetId)),
+    element(ID_SEEK_POSITION, (() => {
+      const buffer = Buffer.alloc(4);
+      buffer.writeUInt32BE(position, 0);
+      return buffer;
+    })())
+  ]));
+  const seekHeadWith = (infoAt, tracksAt, cuesAt) => element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, infoAt),
+    seekEntry(ID_TRACKS, tracksAt),
+    seekEntry(ID_CUES, cuesAt)
+  ]));
+
+  const headLength = seekHeadWith(0, 0, 0).length;
+  const infoAt = headLength;
+  const tracksAt = infoAt + info.length;
+  const cuesAt = tracksAt + tracks.length;
+  // A position in the Cues table is measured from the Segment's payload, and so
+  // is the one the reader turns it into.
+  const clusterRelative = cuesAt + cuesWith(0).length;
+
+  // Enough of a cluster to be read and recognised: its own header and a
+  // timestamp. No blocks, so it yields no cues — what the walk test counts is
+  // that its bytes are fetched once, and that does not depend on their content.
+  const cluster = element(ID_CLUSTER, uintElement(ID_TIMESTAMP, 1000));
+
+  const segmentPayload = Buffer.concat([
+    seekHeadWith(infoAt, tracksAt, cuesAt),
+    info,
+    tracks,
+    cuesWith(clusterRelative),
+    cluster
+  ]);
+  const ebml = element(ID_EBML, Buffer.from([0x42, 0x86, 0x81, 0x01]));
+  const segment = element(ID_SEGMENT, segmentPayload);
+  const segmentDataOffset = ebml.length + segment.length - segmentPayload.length;
+  return {
+    file: Buffer.concat([ebml, segment]),
+    clusterAt: segmentDataOffset + clusterRelative
+  };
+}
+
+function readerOver(file) {
+  return async (start, end) => {
+    const last = Math.min(end, file.length - 1);
+    return start > last ? null : file.subarray(start, last + 1);
+  };
+}
+
+test("a text track is numbered as ffmpeg numbers it, past the picture ones", async () => {
+  const { file } = buildFile();
+
+  const plan = await readSubtitlePlan(readerOver(file), file.length);
+
+  assert.equal(plan.declared.length, 3, "all three subtitle tracks are declared");
+  assert.deepEqual(plan.tracks.map((track) => track.trackNumber), [3, 4], "only the text ones are readable");
+  assert.deepEqual(
+    plan.tracks.map((track) => track.declaredIndex),
+    [1, 2],
+    "the PGS track is 0:s:0, so the text tracks are 0:s:1 and 0:s:2 — not 0 and 1"
+  );
+});
+
+/**
+ * A torrent holding one file entirely, counting the byte ranges read from it.
+ *
+ * @param {Buffer} bytes
+ * @returns {{ torrent: object, reads: Array<{ start: number, end: number }> }}
+ */
+function torrentOver(bytes) {
+  const reads = [];
+  const file = {
+    name: "film.mkv",
+    length: bytes.length,
+    offset: 0,
+    createReadStream({ start = 0, end = bytes.length - 1 } = {}) {
+      reads.push({ start, end });
+      // Asynchronous on purpose: a read that resolves in the same tick would
+      // hide exactly the interleaving this test is about.
+      return Readable.from((async function* chunks() {
+        await new Promise((resolve) => setImmediate(resolve));
+        yield bytes.subarray(start, end + 1);
+      })());
+    }
+  };
+  return {
+    reads,
+    torrent: {
+      pieceLength: 1024,
+      bitfield: { get: () => true },
+      files: [file]
+    }
+  };
+}
+
+test("two walks of one file at the same time read each cluster once", async () => {
+  const { file, clusterAt } = buildFile();
+  const { torrent, reads } = torrentOver(file);
+  const sourceKey = "torrent:numbering-test";
+  forgetSubtitles(sourceKey);
+
+  // Both text tracks at once, which is what the warmup does on every verified
+  // piece and every three seconds.
+  const [first, second] = await Promise.all([
+    cuesHeldFor(torrent, 0, sourceKey, 3),
+    cuesHeldFor(torrent, 0, sourceKey, 4)
+  ]);
+
+  assert.equal(first.coveredClusters, 1, "the cluster the table names was walked");
+  assert.equal(second.coveredClusters, 1, "and the second track sees the same walk, not its own");
+  const clusterReads = reads.filter((range) => range.start === clusterAt);
+  assert.equal(
+    clusterReads.length,
+    2,
+    "one probe of the cluster's header and one read of its body — not two of each"
+  );
+  forgetSubtitles(sourceKey);
+});

package/test/wedge-certainty.test.js

@@ -0,0 +1,131 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { wedgeIsCertain } from "../services/data-channel-handler.js";
+import { PROBE_INTERVAL_MS } from "../services/delivery-probe.js";
+
+const MEGABYTE = 1024 * 1024;
+
+test("a queue draining at the rate this link was measured at is not a wedge", () => {
+  // 8 MB at 16 MB/s is half a second of draining. Half a second in is normal.
+  const verdict = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 16 * MEGABYTE,
+    flatForMs: 200
+  });
+  assert.equal(verdict.certain, false);
+});
+
+test("the counter standing still past the queue's own drain time is a wedge", () => {
+  const verdict = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 16 * MEGABYTE,
+    flatForMs: 4000
+  });
+  assert.equal(verdict.certain, true);
+  assert.equal(verdict.needMs, 500);
+});
+
+test("a big queue on a slow link is given the time it genuinely needs", () => {
+  // 67 MB at 1 MB/s is 67 seconds of honest draining — the field's own numbers
+  // for the wedged channel, at a rate a thin link could really be running at.
+  const patient = wedgeIsCertain({
+    queuedBytes: 67 * MEGABYTE,
+    bytesPerSecond: MEGABYTE,
+    flatForMs: 30_000
+  });
+  assert.equal(patient.certain, false);
+  const later = wedgeIsCertain({
+    queuedBytes: 67 * MEGABYTE,
+    bytesPerSecond: MEGABYTE,
+    flatForMs: 70_000
+  });
+  assert.equal(later.certain, true);
+});
+
+test("the same queue on the link the field actually had is called quickly", () => {
+  // 67 MB at 18 MB/s is under four seconds. The field episode stood still for
+  // 3217 s; the previous rule waited a flat 30 s before recording anything.
+  const verdict = wedgeIsCertain({
+    queuedBytes: 67 * MEGABYTE,
+    bytesPerSecond: 18 * MEGABYTE,
+    flatForMs: 5000
+  });
+  assert.equal(verdict.certain, true);
+  assert.ok(verdict.needMs < 30_000);
+});
+
+test("a tiny queue still waits for one round of probes", () => {
+  const verdict = wedgeIsCertain({
+    queuedBytes: 512,
+    bytesPerSecond: 16 * MEGABYTE,
+    flatForMs: PROBE_INTERVAL_MS - 1
+  });
+  assert.equal(verdict.certain, false);
+  assert.equal(verdict.needMs, PROBE_INTERVAL_MS);
+});
+
+test("nothing queued is not a wedge however long the counter has been still", () => {
+  const verdict = wedgeIsCertain({
+    queuedBytes: 0,
+    bytesPerSecond: 16 * MEGABYTE,
+    flatForMs: 600_000
+  });
+  assert.equal(verdict.certain, false);
+  assert.equal(verdict.needMs, null);
+});
+
+test("with no rate measured the answer is that nothing can be said", () => {
+  const verdict = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 0,
+    flatForMs: 600_000
+  });
+  assert.equal(verdict.certain, false);
+  assert.equal(verdict.needMs, null);
+});
+
+test("a pause no longer than this link's own longest healthy pause is not a wedge", () => {
+  // A retransmission timeout stops the accepted-byte counter dead: a full send
+  // buffer accepts nothing. If this connection has already paused 3 s while
+  // healthy, a 3 s pause says nothing.
+  const verdict = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 18 * MEGABYTE,
+    flatForMs: 2500,
+    longestHealthyFlatMs: 3000
+  });
+  assert.equal(verdict.certain, false);
+  assert.equal(verdict.needMs, 3000);
+});
+
+test("a pause longer than any this link has shown is a wedge", () => {
+  const verdict = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 18 * MEGABYTE,
+    flatForMs: 3500,
+    longestHealthyFlatMs: 3000
+  });
+  assert.equal(verdict.certain, true);
+});
+
+test("the quiet-probe rate cannot be what the queue is divided by", () => {
+  // With the browser's buffer full, the only traffic is the probe: three
+  // channels, a few dozen bytes, twice a second. Dividing 8 MB by that gives
+  // six hours, and the wedge would never be called. The BEST rate seen is what
+  // the watcher keeps, so this case must not arise — pinned here as the
+  // arithmetic that made it matter.
+  const wrong = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 360,
+    flatForMs: 60_000
+  });
+  assert.equal(wrong.certain, false);
+  assert.ok(wrong.needMs > 6 * 60 * 60 * 1000 - 1);
+  const right = wedgeIsCertain({
+    queuedBytes: 8 * MEGABYTE,
+    bytesPerSecond: 18 * MEGABYTE,
+    flatForMs: 60_000
+  });
+  assert.equal(right.certain, true);
+});