@torrent-tv/proxy 2.66.0 → 2.67.0

package/test/background-fill.test.js

@@ -0,0 +1,156 @@
+/**
+ * Fetching a file nobody is playing yet, without taking anything from the
+ * viewer.
+ *
+ * The ordering these checks pin is the whole point of the thing: what plays now
+ * comes first, the other soundtracks and subtitle files next, and reading the
+ * film far ahead last. The middle tier stays below the first by standing aside
+ * whenever a reader on the torrent is inside a wait.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EventEmitter } from "node:events";
+import { fillFileInBackground, fillIsRunning } from "../services/torrent-worker/background-fill.js";
+
+/**
+ * A file whose reads resolve when the test says so, recording what was asked
+ * for.
+ *
+ * @param {{ length: number, name?: string }} params
+ */
+function fakeFile({ length, name = "dub.mka" }) {
+  const reads = [];
+  return {
+    name,
+    length,
+    reads,
+    createReadStream({ start, end }) {
+      const stream = new EventEmitter();
+      stream.destroy = () => {};
+      reads.push({ start, end });
+      // Deliver on the next turn, so a test can observe the read in flight.
+      queueMicrotask(() => {
+        stream.emit("data", Buffer.alloc(end - start + 1));
+        stream.emit("end");
+      });
+      return stream;
+    }
+  };
+}
+
+/**
+ * @param {() => boolean} until
+ * @param {number} [limit]
+ */
+async function waitFor(until, limit = 2000) {
+  const deadline = Date.now() + limit;
+  while (!until()) {
+    if (Date.now() > deadline) {
+      throw new Error("condition was never reached");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+test("a file is walked whole, a piece at a time", async () => {
+  const file = fakeFile({ length: 10 });
+  const torrent = { infoHash: "aaa", pieceLength: 4, files: [file] };
+
+  const started = fillFileInBackground(torrent, 0, "source-a", { chunkBytes: 4 });
+
+  assert.equal(started, true);
+  await waitFor(() => !fillIsRunning("source-a", 0));
+  // 0-3, 4-7, 8-9: the last chunk is short because the file ends, and its end
+  // is the last byte rather than one past it.
+  assert.deepEqual(file.reads, [
+    { start: 0, end: 3 },
+    { start: 4, end: 7 },
+    { start: 8, end: 9 }
+  ]);
+});
+
+test("one fill per file, however many times it is asked for", async () => {
+  const file = fakeFile({ length: 8 });
+  const torrent = { infoHash: "bbb", pieceLength: 4, files: [file] };
+
+  const first = fillFileInBackground(torrent, 0, "source-b", { chunkBytes: 4 });
+  const second = fillFileInBackground(torrent, 0, "source-b", { chunkBytes: 4 });
+
+  assert.equal(first, true);
+  assert.equal(second, false, "the second call does not start a second walk");
+  await waitFor(() => !fillIsRunning("source-b", 0));
+  assert.equal(file.reads.length, 2, "the file was walked once");
+});
+
+test("a file that is gone is not read, and does not throw", async () => {
+  const torrent = { infoHash: "ccc", pieceLength: 4, files: [] };
+
+  const started = fillFileInBackground(torrent, 0, "source-c", { chunkBytes: 4 });
+
+  assert.equal(started, false);
+  assert.equal(fillIsRunning("source-c", 0), false);
+});
+
+test("a read that returns nothing stops the walk instead of spinning", async () => {
+  const file = {
+    name: "dub.mka",
+    length: 100,
+    reads: [],
+    createReadStream({ start, end }) {
+      const stream = new EventEmitter();
+      stream.destroy = () => {};
+      this.reads.push({ start, end });
+      queueMicrotask(() => stream.emit("error", new Error("gone")));
+      return stream;
+    }
+  };
+  const torrent = { infoHash: "ddd", pieceLength: 10, files: [file] };
+
+  fillFileInBackground(torrent, 0, "source-d", { chunkBytes: 10 });
+
+  await waitFor(() => !fillIsRunning("source-d", 0));
+  assert.equal(file.reads.length, 1, "it gave up after the first failed read");
+});
+
+test("it stands aside while the viewer's own reading is blocked", async () => {
+  const file = fakeFile({ length: 8 });
+  const torrent = { infoHash: "eee", pieceLength: 4, files: [file] };
+  let blocked = true;
+
+  fillFileInBackground(torrent, 0, "source-e", { chunkBytes: 4, isBlocked: () => blocked });
+
+  // The picture is starving, so nothing is asked of the swarm on the
+  // soundtrack's behalf — however long that lasts.
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  assert.deepEqual(file.reads, [], "not one read while a reader is inside a wait");
+
+  blocked = false;
+  await waitFor(() => !fillIsRunning("source-e", 0));
+  assert.equal(file.reads.length, 2, "and it resumes once the room is there");
+});
+
+test("the gate is re-asked before every chunk, not once at the start", async () => {
+  const file = fakeFile({ length: 12 });
+  const torrent = { infoHash: "fff", pieceLength: 4, files: [file] };
+  // Starve the viewer again the moment the first chunk has been read, and stay
+  // that way until the test lifts it.
+  let starvedAfterFirstChunk = false;
+  let lifted = false;
+  const isBlocked = () => {
+    if (file.reads.length >= 1 && !lifted) {
+      starvedAfterFirstChunk = true;
+    }
+    return starvedAfterFirstChunk && !lifted;
+  };
+
+  fillFileInBackground(torrent, 0, "source-f", { chunkBytes: 4, isBlocked });
+
+  await waitFor(() => file.reads.length === 1);
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  assert.equal(file.reads.length, 1, "a torrent healthy a moment ago is not evidence about now");
+
+  lifted = true;
+  await waitFor(() => !fillIsRunning("source-f", 0));
+  assert.equal(file.reads.length, 3);
+});

package/test/supply-margin.test.js

@@ -29,18 +29,65 @@ function evenlySpaced(count, intervalSec, waitSec) {
 }
 
 test("the margin is what the supply's own interruptions demand", () => {
-  // The field torrent: a wait every 2.22 s, the worst of them 3.16 s.
-  const waits = evenlySpaced(10, 2.22, 1.49);
-  waits[4].waitedMs = 3160;
+  // The field torrent: waits of 1.49 s with 0.73 s of running between them, and
+  // the worst of them 3.16 s. Written out rather than generated, because the
+  // point of the test is that these exact spans give that exact answer.
+  const waits = [
+    { waitedMs: 1490, at: 1490 },   // 0.00..1.49
+    { waitedMs: 1490, at: 3710 },   // 2.22..3.71
+    { waitedMs: 1490, at: 5930 },   // 4.44..5.93
+    { waitedMs: 3160, at: 9820 },   // 6.66..9.82  ← the worst
+    { waitedMs: 1490, at: 12_040 }, // 10.55..12.04
+    { waitedMs: 1490, at: 14_260 }  // 12.77..14.26
+  ];
 
   const answer = requiredSpeedFrom(waits);
 
   assert.ok(answer);
   assert.equal(answer.worstWaitSec, 3.16);
-  assert.equal(answer.medianIntervalSec, 2.22);
-  // 1 + 3.16 / 2.22 = 2.42. The step that was admitted by the hand-chosen 1.5
-  // ran at 1.05x and stalled; this is the bar it should have been held to.
-  assert.ok(Math.abs(answer.requiredSpeed - 2.4234) < 0.001, `got ${answer.requiredSpeed}`);
+  // 2.22 s from one wait's end to the next one's END, of which 1.49 s was spent
+  // waiting — so the encoder ran for 0.73 s. That running stretch is what the
+  // derivation calls T: `(v - 1) x T > W` prices what is GAINED between
+  // interruptions, and nothing is gained during one.
+  assert.ok(Math.abs(answer.medianIntervalSec - 0.73) < 0.001, `got ${answer.medianIntervalSec}`);
+  // 1 + 3.16 / 0.73 = 5.33. Measuring end-to-end instead gave 2.42, and the
+  // symptom that this whole file was written against is that a step admitted at
+  // 1.5 ran at 1.05x and stalled — so the bar was too low, not too high.
+  assert.ok(Math.abs(answer.requiredSpeed - 5.3288) < 0.001, `got ${answer.requiredSpeed}`);
+});
+
+test("one stall seen by three readers is one interruption, not three", () => {
+  // The picture and two audio renditions walk the same file, so a piece that
+  // has not arrived blocks all three, and their waits end within milliseconds
+  // of each other. Field 2026-08-31: `worst wait 13.26s, one every 0.00s,
+  // 2 measured` produced a required speed of 4422.00x, and every quality step
+  // was refused against it.
+  const answer = requiredSpeedFrom([
+    { waitedMs: 13_260, at: 1_000_000 },
+    { waitedMs: 13_257, at: 1_000_003 }
+  ]);
+
+  // Two overlapping waits are one interruption, and one interruption shows no
+  // interval — so the honest answer is that it is not known yet.
+  assert.equal(answer, null);
+});
+
+test("overlapping waits merge, and the gap between stalls is what is left", () => {
+  const answer = requiredSpeedFrom([
+    // First stall: 10s..20s, noticed by two readers a moment apart.
+    { waitedMs: 10_000, at: 20_000 },
+    { waitedMs: 9_000, at: 19_500 },
+    // Second stall: 30s..34s, again seen twice.
+    { waitedMs: 4_000, at: 34_000 },
+    { waitedMs: 3_500, at: 33_800 }
+  ]);
+
+  assert.ok(answer);
+  assert.equal(answer.samples, 2, "two interruptions");
+  assert.equal(answer.waits, 4, "from four waits");
+  assert.equal(answer.worstWaitSec, 10, "the merged stall, not one reader's view of it");
+  assert.equal(answer.medianIntervalSec, 10, "20s to 30s is when the encoder ran");
+  assert.equal(answer.requiredSpeed, 2, "1 + 10/10");
 });
 
 test("a copy at 8x clears its own supply with room to spare", () => {
@@ -48,9 +95,10 @@ test("a copy at 8x clears its own supply with room to spare", () => {
   const waits = evenlySpaced(6, 15.5, 4.82);
   const answer = requiredSpeedFrom(waits);
   assert.ok(answer);
-  // 1 + 4.82/15.5 = 1.31, against 8x measured. Which is why a copy is the step
-  // a stranded viewer is always able to return to.
-  assert.ok(answer.requiredSpeed < 1.35, `got ${answer.requiredSpeed}`);
+  // Waits end 15.5 s apart and last 4.82 s, so the encoder runs 10.68 s between
+  // them: 1 + 4.82/10.68 = 1.45, against 8x measured. Which is why a copy is the
+  // step a stranded viewer is always able to return to.
+  assert.ok(answer.requiredSpeed < 1.5, `got ${answer.requiredSpeed}`);
 });
 
 test("with too little evidence it says so instead of inventing a number", () => {
@@ -77,7 +125,7 @@ test("readings that are not measurements are ignored, not averaged in", () => {
     { waitedMs: 1500, at: 7000 }
   ]);
   assert.ok(answer);
-  assert.equal(answer.samples, 3, "only the three real waits count");
+  assert.equal(answer.waits, 3, "only the three real waits count");
 });
 
 test("the buffer is one segment plus the worst interruption, and names which", () => {