@torrent-tv/proxy 2.56.0 → 2.57.1

package/test/packet-witness.test.js

@@ -1,120 +1,148 @@
-/**
- * @file The packet witness's gating rules and command construction.
- *
- * Roadmap item 10: a send queue wedged longer than ~30 s must start a bounded
- * tcpdump on its own, because the 2026-08-24 episode proved no counter above
- * the wire can name the cause. Everything here is the part that decides WHEN
- * and WITH WHAT ARGUMENTS — the spawning itself is thin glue around these.
- */
-
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import {
-  buildTcpdumpArgs,
-  createPacketWitness,
-  isWitnessCapture,
-  normalizeRemoteAddress,
-  shouldStartCapture,
-  WITNESS_CAPTURE_SECONDS,
-  WITNESS_RING_FILES,
-  WITNESS_ROTATE_SECONDS
-} from "../services/packet-witness.js";
-
-test("an IPv4 literal survives unchanged", () => {
-  assert.equal(normalizeRemoteAddress("192.168.178.57"), "192.168.178.57");
-});
-
-test("an IPv6 literal survives unchanged", () => {
-  assert.equal(
-    normalizeRemoteAddress("2001:1c00:a603:2100:a129:a1a1:7f07:3f0b"),
-    "2001:1c00:a603:2100:a129:a1a1:7f07:3f0b"
-  );
-});
-
-test("a zone suffix is stripped", () => {
-  assert.equal(normalizeRemoteAddress("fe80::2aca:8001:3ba6:f16f%18"), "fe80::2aca:8001:3ba6:f16f");
-});
-
-test("hostnames, garbage and shell text are rejected", () => {
-  assert.equal(normalizeRemoteAddress("homeassistant.local"), null);
-  assert.equal(normalizeRemoteAddress("8.8.8.8; rm -rf /"), null);
-  assert.equal(normalizeRemoteAddress("999.1.1.1"), null);
-  assert.equal(normalizeRemoteAddress(""), null);
-  assert.equal(normalizeRemoteAddress(undefined), null);
-  assert.equal(normalizeRemoteAddress(42), null);
-});
-
-test("the tcpdump command line is bounded and filtered to one peer", () => {
-  const args = buildTcpdumpArgs({
-    host: "2001:db8::1",
-    port: 9090,
-    filePrefix: "/data/packet-witness.e2b5ef39.1787600000.pcap"
-  });
-  assert.deepEqual(args, [
-    "-n",
-    "-S",
-    "-s",
-    "128",
-    "-i",
-    "any",
-    "-w",
-    "/data/packet-witness.e2b5ef39.1787600000.pcap",
-    "-G",
-    String(WITNESS_ROTATE_SECONDS),
-    "-W",
-    String(WITNESS_RING_FILES),
-    "udp",
-    "and",
-    "host",
-    "2001:db8::1",
-    "and",
-    "port",
-    "9090"
-  ]);
-});
-
-test("the capture window is what the rotation ring adds up to", () => {
-  assert.equal(WITNESS_ROTATE_SECONDS * WITNESS_RING_FILES, WITNESS_CAPTURE_SECONDS);
-});
-
-test("one capture runs at a time", () => {
-  assert.equal(shouldStartCapture({ running: true, lastStartedAt: Date.now() }), false);
-});
-
-test("the first capture of a process is always allowed", () => {
-  assert.equal(shouldStartCapture({ running: false, lastStartedAt: 0, now: 1000 }), true);
-});
-
-test("a capture within the cooldown is refused, one after it is allowed", () => {
-  const state = { running: false, lastStartedAt: 10_000 };
-  assert.equal(shouldStartCapture({ ...state, now: 10_000 + 599_999 }), false);
-  assert.equal(shouldStartCapture({ ...state, now: 10_000 + 600_000 }), true);
-});
-
-test("capture files are recognised by name, rotations included", () => {
-  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.pcap"), true);
-  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.pcap20260825T120000"), true);
-  assert.equal(isWitnessCapture("core.WorkerThread.81.1787600000"), false);
-  assert.equal(isWitnessCapture("proxy.log"), false);
-  assert.equal(isWitnessCapture("../packet-witness.x.pcap"), false);
-});
-
-test("a trigger without a usable remote endpoint is refused without touching anything", () => {
-  const lines = [];
-  const witness = createPacketWitness({
-    log: (message) => lines.push(message),
-    dir: "",
-    port: 9090
-  });
-  const started = witness.maybeCapture({
-    sessionId: "e2b5ef39-0000",
-    tag: "e2b5ef39",
-    label: "proxy",
-    remote: null,
-    queuedBytes: 160_000_000,
-    stuckForMs: 31_000
-  });
-  assert.equal(started, false);
-  assert.deepEqual(lines, []);
-});
+/**
+ * @file The packet witness's gating rules and command construction.
+ *
+ * Roadmap item 10: a send queue wedged longer than ~30 s must start a bounded
+ * tcpdump on its own, because the 2026-08-24 episode proved no counter above
+ * the wire can name the cause. Everything here is the part that decides WHEN
+ * and WITH WHAT ARGUMENTS — the spawning itself is thin glue around these.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildTcpdumpArgs,
+  createPacketWitness,
+  isWitnessCapture,
+  isWitnessRingFile,
+  normalizeRemoteAddress,
+  shouldStartCapture,
+  WITNESS_RING_FILE_MB,
+  WITNESS_RING_FILES,
+  WITNESS_RTO_CEILING_SECONDS,
+  WITNESS_TAIL_SECONDS
+} from "../services/packet-witness.js";
+
+test("an IPv4 literal survives unchanged", () => {
+  assert.equal(normalizeRemoteAddress("192.168.178.57"), "192.168.178.57");
+});
+
+test("an IPv6 literal survives unchanged", () => {
+  assert.equal(
+    normalizeRemoteAddress("2001:1c00:a603:2100:a129:a1a1:7f07:3f0b"),
+    "2001:1c00:a603:2100:a129:a1a1:7f07:3f0b"
+  );
+});
+
+test("a zone suffix is stripped", () => {
+  assert.equal(normalizeRemoteAddress("fe80::2aca:8001:3ba6:f16f%18"), "fe80::2aca:8001:3ba6:f16f");
+});
+
+test("hostnames, garbage and shell text are rejected", () => {
+  assert.equal(normalizeRemoteAddress("homeassistant.local"), null);
+  assert.equal(normalizeRemoteAddress("8.8.8.8; rm -rf /"), null);
+  assert.equal(normalizeRemoteAddress("999.1.1.1"), null);
+  assert.equal(normalizeRemoteAddress(""), null);
+  assert.equal(normalizeRemoteAddress(undefined), null);
+  assert.equal(normalizeRemoteAddress(42), null);
+});
+
+test("the tcpdump command line is bounded and filtered to one peer", () => {
+  const args = buildTcpdumpArgs({
+    host: "2001:db8::1",
+    port: 9090,
+    filePrefix: "/data/packet-witness.e2b5ef39.1787600000.pcap"
+  });
+  assert.deepEqual(args, [
+    "-n",
+    "-S",
+    "-s",
+    "128",
+    "-i",
+    "any",
+    "-w",
+    "/data/packet-witness.e2b5ef39.1787600000.pcap",
+    "-C",
+    String(WITNESS_RING_FILE_MB),
+    "-W",
+    String(WITNESS_RING_FILES),
+    "udp",
+    "and",
+    "port",
+    "9090",
+    "and",
+    "host",
+    "2001:db8::1"
+  ]);
+});
+
+test("rotation is by size, so the ring files cannot collapse onto one name", () => {
+  // `-G` with a name carrying no strftime field overwrote a single file, which
+  // is why both field captures held 28 s instead of the intended 120.
+  const args = buildTcpdumpArgs({ port: 9090, filePrefix: "/data/ring.pcap" });
+  assert.equal(args.includes("-G"), false);
+  assert.equal(args[args.indexOf("-C") + 1], String(WITNESS_RING_FILE_MB));
+});
+
+test("with no peer named the ring records every peer on the port", () => {
+  const args = buildTcpdumpArgs({ port: 9090, filePrefix: "/data/ring.pcap" });
+  assert.equal(args.includes("host"), false);
+  assert.deepEqual(args.slice(-4), ["udp", "and", "port", "9090"]);
+});
+
+test("the tail outlasts three retransmission timeouts", () => {
+  assert.equal(WITNESS_TAIL_SECONDS, WITNESS_RTO_CEILING_SECONDS * 3);
+  // A zero-window probe is due once per timeout, so a window shorter than the
+  // ceiling could not tell silence from a probe that had not come round yet.
+  assert.ok(WITNESS_TAIL_SECONDS > WITNESS_RTO_CEILING_SECONDS);
+});
+
+test("ring files are told apart from the copies kept as evidence", () => {
+  assert.equal(isWitnessRingFile("packet-witness-ring.pcap"), true);
+  assert.equal(isWitnessRingFile("packet-witness-ring.pcap3"), true);
+  assert.equal(isWitnessRingFile("packet-witness.e2b5ef39.1787600000.before1.pcap"), false);
+  assert.equal(isWitnessCapture("packet-witness-ring.pcap3"), false);
+  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.before1.pcap"), true);
+  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.tail.pcap1"), true);
+});
+
+test("one capture runs at a time", () => {
+  assert.equal(shouldStartCapture({ running: true, lastStartedAt: Date.now() }), false);
+});
+
+test("the first capture of a process is always allowed", () => {
+  assert.equal(shouldStartCapture({ running: false, lastStartedAt: 0, now: 1000 }), true);
+});
+
+test("a capture within the cooldown is refused, one after it is allowed", () => {
+  const state = { running: false, lastStartedAt: 10_000 };
+  assert.equal(shouldStartCapture({ ...state, now: 10_000 + 599_999 }), false);
+  assert.equal(shouldStartCapture({ ...state, now: 10_000 + 600_000 }), true);
+});
+
+test("capture files are recognised by name, rotations included", () => {
+  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.pcap"), true);
+  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.pcap20260825T120000"), true);
+  assert.equal(isWitnessCapture("core.WorkerThread.81.1787600000"), false);
+  assert.equal(isWitnessCapture("proxy.log"), false);
+  assert.equal(isWitnessCapture("../packet-witness.x.pcap"), false);
+});
+
+test("a trigger without a usable remote endpoint is refused without touching anything", () => {
+  const lines = [];
+  const witness = createPacketWitness({
+    log: (message) => lines.push(message),
+    dir: "",
+    port: 9090
+  });
+  const started = witness.maybeCapture({
+    sessionId: "e2b5ef39-0000",
+    tag: "e2b5ef39",
+    label: "proxy",
+    remote: null,
+    queuedBytes: 160_000_000,
+    stuckForMs: 31_000
+  });
+  assert.equal(started, false);
+  assert.deepEqual(lines, []);
+});

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

@@ -37,6 +37,10 @@ const ID_TRACK_NUMBER = 0xd7;
 const ID_TRACK_TYPE = 0x83;
 const ID_CODEC_ID = 0x86;
 const ID_LANGUAGE = 0x22b59c;
+const ID_LANGUAGE_BCP47 = 0x22b59d;
+const ID_FLAG_ENABLED = 0xb9;
+const ID_FLAG_FORCED = 0x55aa;
+const ID_FLAG_HEARING_IMPAIRED = 0x55ab;
 const ID_CUES = 0x1c53bb6b;
 const ID_CUE_POINT = 0xbb;
 const ID_CUE_TIME = 0xb3;
@@ -95,13 +99,26 @@ function uint32Element(id, value) {
   return element(id, payload);
 }
 
-function trackEntry({ number, type, codecId, language }) {
-  return element(ID_TRACK_ENTRY, Buffer.concat([
+function trackEntry({ number, type, codecId, language, flags = {}, languageBcp47 = null }) {
+  const parts = [
     uintElement(ID_TRACK_NUMBER, number),
     uintElement(ID_TRACK_TYPE, type),
     stringElement(ID_CODEC_ID, codecId),
     stringElement(ID_LANGUAGE, language)
-  ]));
+  ];
+  if (languageBcp47 !== null) {
+    parts.push(stringElement(ID_LANGUAGE_BCP47, languageBcp47));
+  }
+  for (const [id, value] of [
+    [ID_FLAG_ENABLED, flags.enabled],
+    [ID_FLAG_FORCED, flags.forced],
+    [ID_FLAG_HEARING_IMPAIRED, flags.hearingImpaired]
+  ]) {
+    if (value !== undefined) {
+      parts.push(uintElement(id, value ? 1 : 0));
+    }
+  }
+  return element(ID_TRACK_ENTRY, Buffer.concat(parts));
 }
 
 /**
@@ -260,3 +277,94 @@ test("two walks of one file at the same time read each cluster once", async () =
   );
   forgetSubtitles(sourceKey);
 });
+
+/**
+ * A file whose subtitle tracks carry the flags RFC 9559 defines for them: one
+ * forced, one for viewers who cannot hear, one the file marks unusable, and one
+ * writing its language as RFC 5646 alongside the three-letter code.
+ *
+ * @returns {Buffer}
+ */
+function fileWithFlags() {
+  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_TEXT/UTF8", language: "rus", flags: { forced: true } }),
+    trackEntry({ number: 3, type: 17, codecId: "S_TEXT/UTF8", language: "eng", flags: { hearingImpaired: true } }),
+    trackEntry({ number: 4, type: 17, codecId: "S_TEXT/UTF8", language: "fre", flags: { enabled: false } }),
+    trackEntry({ number: 5, type: 17, codecId: "S_TEXT/ASS", language: "por", languageBcp47: "pt-BR" })
+  ]));
+  const seekEntry = (targetId, position) => element(ID_SEEK, Buffer.concat([
+    element(ID_SEEK_ID, idBytes(targetId)),
+    uint32Element(ID_SEEK_POSITION, position)
+  ]));
+  const seekHeadWith = (infoAt, tracksAt) => element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, infoAt),
+    seekEntry(ID_TRACKS, tracksAt)
+  ]));
+  const headLength = seekHeadWith(0, 0).length;
+  const segmentPayload = Buffer.concat([
+    seekHeadWith(headLength, headLength + info.length),
+    info,
+    tracks
+  ]);
+  const ebml = element(ID_EBML, Buffer.from([0x42, 0x86, 0x81, 0x01]));
+  return Buffer.concat([ebml, element(ID_SEGMENT, segmentPayload)]);
+}
+
+test("the flags the file states about a track are read, not guessed from its name", async () => {
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  const forced = plan.tracks.find((track) => track.trackNumber === 2);
+  assert.equal(forced.isForced, true, "FlagForced 0x55AA");
+  assert.equal(forced.isHearingImpaired, false);
+
+  const sdh = plan.tracks.find((track) => track.trackNumber === 3);
+  assert.equal(sdh.isHearingImpaired, true, "FlagHearingImpaired 0x55AB");
+  assert.equal(sdh.isForced, false);
+});
+
+test("a track the file marks unusable is not offered, but is still counted", async () => {
+  // FlagEnabled (0xB9): "Set to 1 if the track is usable." Track 4 says 0, so
+  // it is not offered — but it KEEPS its place in the numbering, because ffmpeg
+  // keeps it: `matroskadec.c` parses MATROSKA_ID_TRACKFLAGENABLED as EBML_NONE,
+  // reading the element and storing nothing, so the stream is created and gets
+  // its own `0:s:N`. Dropping it here would shift every track after it.
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  assert.equal(plan.tracks.some((track) => track.trackNumber === 4), false, "not offered for extraction");
+  const counted = plan.declared.find((track) => track.trackNumber === 4);
+  assert.ok(counted, "still declared, so the numbering does not move");
+  assert.equal(counted.isEnabled, false);
+});
+
+test("an unusable track keeps its place, so the tracks after it keep theirs", async () => {
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  // s:0 forced, s:1 SDH, s:2 the unusable one, s:3 the Brazilian track.
+  assert.deepEqual(
+    plan.tracks.map((track) => [track.trackNumber, track.declaredIndex]),
+    [[2, 0], [3, 1], [5, 3]]
+  );
+});
+
+test("the list ffmpeg is lined up against still speaks ffmpeg's language codes", async () => {
+  // `declared` exists to be paired with the `-i` banner, which prints the
+  // three-letter code; reporting "pt-BR" there would break the pairing and cost
+  // the FlagDefault reading with it.
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  const declared = plan.declared.find((track) => track.trackNumber === 5);
+  assert.equal(declared.language, "por");
+  assert.equal(declared.languageBcp47, "pt-BR");
+});
+
+test("where the file writes RFC 5646, that is the language", async () => {
+  // "If this element is used, then any Language elements used in the same
+  // TrackEntry MUST be ignored."
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  const track = plan.tracks.find((entry) => entry.trackNumber === 5);
+  assert.equal(track.language, "pt-BR", "not the three-letter por");
+  assert.equal(track.languageBcp47, "pt-BR");
+});

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);
+});