@torrent-tv/proxy 2.56.0 → 2.57.0

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