@torrent-tv/proxy 2.87.21 → 2.88.0

package/test/one-authority.test.js

@@ -1,285 +1,285 @@
-/**
- * @file One place decides which encoders exist.
- *
- * Not a check of behaviour but of shape, and it is here because the shape is
- * what failed. Three separate places used to decide where an encoder should
- * work and whether it should go on living, and they disagreed on every pass:
- * measured in the field on 2026-09-05, 684 starts and 660 stops in 482 seconds,
- * of which 294 were one place killing what another had just decided to keep,
- * while the viewer's own segment went unmade for 32.3 seconds.
- *
- * Every rule below is one that was broken then. A reader who needs to add a
- * fourth place should read this file first and then not.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { readFileSync, readdirSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { EventEmitter } from "node:events";
-import { EncodeRun } from "../services/encode/EncodeRun.js";
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-
-/**
- * @param {string} relative
- * @returns {string}
- */
-function source(relative) {
-  return readFileSync(path.join(HERE, "..", relative), "utf8");
-}
-
-/**
- * Every source file of the proxy's services, read together.
- *
- * A rule that something must not come back is asked of all of them: asked of
- * one file, it passes as soon as the code moves to another.
- *
- * @returns {string}
- */
-function everything() {
-  return readdirSync(path.join(HERE, "..", "services"), { recursive: true })
-    .filter((name) => String(name).endsWith(".js"))
-    .map((name) => source(path.join("services", String(name))))
-    .join("\n");
-}
-
-/**
- * Lines of code, without comments or blanks: a rule about what the code does
- * must not be answered by what a comment says about it.
- *
- * @param {string} text
- * @returns {string[]}
- */
-function statements(text) {
-  return text
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0 && !line.startsWith("//") && !line.startsWith("*") && !line.startsWith("/*"));
-}
-
-test("an encoder is stopped for scheduling reasons in exactly one place", () => {
-  // The orchestrator decides; nobody else may. What is left in the session
-  // manager is teardown — the session is going away and its encoders with it —
-  // which is not a decision about which encoders should exist.
-  const orchestrator = statements(source("services/encode/EncodeOrchestrator.js"));
-  const stopsInOrchestrator = orchestrator.filter((line) => line.includes("run.stop("));
-  assert.equal(stopsInOrchestrator.length, 1, "the orchestrator stops runs in one place");
-
-  const wiring = statements(source("services/server/wire-outputs.js"));
-  assert.deepEqual(wiring.filter((line) => line.includes(".stop(")), [], "the wiring stops nothing");
-  const lifecycle = statements(source("services/server/OutputLifecycle.js"));
-  const stopsAtTeardown = lifecycle.filter((line) => line.includes(".stop("));
-  assert.equal(
-    stopsAtTeardown.length,
-    1,
-    "an output's end stops its runs, and nothing else there does: " + stopsAtTeardown.join(" / ")
-  );
-  // And the runs themselves stop one for a stated reason in one place, which is
-  // what a corrected cut table asks through.
-  const runs = statements(source("services/encode/EncodeRuns.js"));
-  assert.equal(runs.filter((line) => line.includes(".stop(")).length, 1);
-});
-
-test("nothing outside the encoding layer starts an encoder", () => {
-  // A run is built in one place. Two places building them is how a start came
-  // to kill what the plan had decided to keep — the killing lived in the
-  // building.
-  const builds = statements(everything()).filter((line) => line.includes("new EncodeRun("));
-  assert.equal(builds.length, 1, "one place builds an encoder");
-});
-
-test("a run exists means its process is running, so nothing can start one twice", () => {
-  // WHAT THIS IS FOR, and why the test above did not catch it. That one counts
-  // where a run is BUILT and asks nothing about where it is STARTED, and until
-  // 2026-09-10 those were two acts: the session manager built a run and started
-  // it, handed it back, and the orchestrator started it again. Every run of
-  // every session therefore had two ffmpeg processes on one output writing one
-  // set of names — 207 runs against 414 spawns in the field logs of 08-10
-  // September, without a single exception — and only the second was reachable,
-  // so a stop killed one and the other ran on, measured 105 seconds past its
-  // own run's death.
-  //
-  // Asserted over the source because the guarantee IS a property of the source:
-  // there is no second act for a second owner to perform.
-  const files = [
-    "services/encode/EncodeRun.js",
-    "services/encode/EncodeOrchestrator.js",
-    "services/encode/EncodeRuns.js",
-    "services/server/wire-outputs.js"
-  ];
-  for (const file of files) {
-    const starts = statements(source(file)).filter(
-      (line) =>
-        /(?:^|[^a-zA-Z#])start\(/.test(line) &&
-        !/startsWith|startPosition|startIndex|startSeconds|startAt|startNumber/.test(line)
-    );
-    assert.deepEqual(starts, [], "an encoder is started by hand in " + file + ": " + starts.join(" / "));
-  }
-});
-
-test("starting an encoder stops nothing", () => {
-  // The rule that broke it: the start path looked for a live run whose own
-  // start was not below the new one's and killed it. It is not enough that the
-  // line is gone — the words it was written with must not come back.
-  const manager = everything();
-  assert.equal(
-    manager.includes("previousRun"),
-    false,
-    "there is no such thing as the previous run: a session holds several"
-  );
-  assert.equal(manager.includes("a new run is taking its place"), false);
-});
-
-test("a seek moves the viewer and nothing else", () => {
-  // It used to do eleven things and write the position into five places. What
-  // follows from a viewer moving is the map's business, and the orchestrators
-  // read the map.
-  const manager = source("services/server/ViewerRequests.js");
-  const at = manager.indexOf("requestSeek(sessionId, positionSeconds");
-  assert.notEqual(at, -1, "the seek is where this reads it");
-  const seek = manager.slice(at, at + 2000);
-  const body = seek.slice(0, seek.indexOf("\n  }\n"));
-  assert.equal(body.includes("#startEncodeRun"), false, "a seek starts no encoder");
-  assert.equal(body.includes("setTimeout"), false, "and waits for nothing");
-});
-
-test("how far an encoder may work is answered once", () => {
-  // The plan computes the stretch and it reaches ffmpeg. A second computation
-  // somewhere else is what made the first one pointless: it was passed and then
-  // dropped by a parameter list that did not name it.
-  const orchestrator = source("services/encode/EncodeOrchestrator.js");
-  assert.match(
-    orchestrator,
-    /makeRun\(\{ address, from, to, because \}\)/,
-    "the stretch is handed over, and so are the plan's own words for why"
-  );
-});
-
-test("only the plan places an encoder", () => {
-  // The count is the whole of this item. There were eight other places: the
-  // first run of a session, a viewer joining it further in, a rung or a
-  // soundtrack being warmed, one being switched to, a hardware encoder falling
-  // back to software, an input coming back, a cut table correcting itself, and
-  // a settled seek. Each of them chose a position by a rule of its own, and the
-  // plan — which is arithmetic over what is made, what is being made and what is
-  // wanted — was left to compare its answer against theirs.
-  const manager = source("services/encode/EncodeRuns.js");
-  const starts = [...manager.matchAll(/this\.#startEncodeRun\(/g)].length;
-  assert.equal(starts, 1, "one caller, and it is the one the plan asks through");
-  assert.match(
-    manager,
-    /makeRunAt\(address, from, to, because\)[\s\S]{0,3000}this\.#startEncodeRun\(base, from, because, \{ to \}\)/,
-    "and that caller is what the plan is given to build runs with"
-  );
-});
-
-test("nobody stops an encoder for being unwatched", () => {
-  // Whether an encoder is still wanted is the same question as where one should
-  // be, and the plan answers it: an output with nobody on it has a priority map
-  // with nothing in it. Answered here as well, it was answered twice by two
-  // rules — and since a viewer moving between steps announces itself, the plan
-  // started again what this class had just killed, several times a second.
-  const manager = everything();
-  assert.equal(
-    manager.includes("no viewer is watching"),
-    false,
-    "a rung nobody is on is a fact, not an act"
-  );
-  assert.equal(manager.includes("no viewer is listening to audio track"), false);
-  assert.equal(
-    manager.includes("warmed for a switch the viewer did not make"),
-    false,
-    "an abandoned warm-up is a viewer leaving an output"
-  );
-  assert.equal(manager.includes("prepared for a track change the viewer did not make"), false);
-});
-
-test("the seek settle machinery is gone, whole", () => {
-  // A viewer's position is applied the moment they state it. The settle was a
-  // second debounce on a signal the browser had already debounced, and every
-  // millisecond of it was dead time in front of the viewer; the cooldown behind
-  // it existed because segment REQUESTS once steered the encoder.
-  const manager = everything();
-  for (const gone of [
-    "seekSettleTimer",
-    "seekTarget",
-    "seekFirstFarAt",
-    "SEEK_SETTLE_MS",
-    "SEEK_SETTLE_MAX_MS",
-    "RESTART_COOLDOWN_MS",
-    "SEEK_BACKOFF_SEGMENTS",
-    "#fireSettledSeek",
-    "#seekSession"
-  ]) {
-    assert.equal(manager.includes(gone), false, `${gone} is gone`);
-  }
-});
-
-test("where a soundtrack begins is read off the table, not handed in", () => {
-  // The instant a number really begins is a fact of the FILE's cutting, held in
-  // the live table every session of the file shares. Passed as an argument by
-  // the one caller that had measured it, only a run started by that caller ever
-  // had it, and a run the plan placed at the same number landed apart again.
-  const manager = source("services/encode/EncodeRuns.js");
-  assert.match(
-    manager,
-    /const positionSecondsOverride = session\.spec\.carries === "audio-only"\s*\n?\s*\? trueStartOf\(session\.timeline, startIndex\)/,
-    "derived where the run is built"
-  );
-  assert.equal(
-    manager.includes("this.#startEncodeRun(member, index, trueStart)"),
-    false,
-    "and not carried in from the correction that measured it"
-  );
-});
-
-test("each output is handed its own priority map, and the plan is what reads it", () => {
-  // The map is one fact asked at two scopes, and both are right for what asks
-  // them: the swarm is asked for bytes of a FILE, which every output of it
-  // reads, and encoders are placed per OUTPUT, which a person watching 480p
-  // wants nothing of at 1080p.
-  const manager = source("services/encode/EncodeRuns.js");
-  assert.match(
-    manager,
-    /notePriorityMap\([\s\S]{0,200}mapForOutput\(address\)/,
-    "the encoding reads the output's own map"
-  );
-  assert.equal(
-    manager.includes("this.priority.mapFor("),
-    false,
-    "and never the whole film's, which wanted an encoder on every output of it"
-  );
-});
-
-test("one process per run, and no way to ask for a second", () => {
-  const spawned = [];
-  const run = new EncodeRun({
-    address: "torrent:abc:video-only:v=0/copy",
-    encoder: { name: "libx264", kind: "software" },
-    from: 0,
-    to: 4,
-    buildArgs: () => [],
-    spawn: () => {
-      const child = new EventEmitter();
-      child.stdout = new EventEmitter();
-      child.stderr = new EventEmitter();
-      child.stdio = [null, child.stdout, child.stderr, new EventEmitter()];
-      child.kill = () => undefined;
-      child.pid = 1 + spawned.length;
-      spawned.push(child);
-      return child;
-    },
-    logger: { info: () => undefined, warn: () => undefined },
-    now: () => 1000,
-    because: "a test asked for it"
-  });
-
-  assert.equal(spawned.length, 1, "building a run did not put a process on the machine");
-  assert.equal(
-    Reflect.get(run, "start"),
-    undefined,
-    "a run still offers a way to start it a second time"
-  );
-});
+/**
+ * @file One place decides which encoders exist.
+ *
+ * Not a check of behaviour but of shape, and it is here because the shape is
+ * what failed. Three separate places used to decide where an encoder should
+ * work and whether it should go on living, and they disagreed on every pass:
+ * measured in the field on 2026-09-05, 684 starts and 660 stops in 482 seconds,
+ * of which 294 were one place killing what another had just decided to keep,
+ * while the viewer's own segment went unmade for 32.3 seconds.
+ *
+ * Every rule below is one that was broken then. A reader who needs to add a
+ * fourth place should read this file first and then not.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EventEmitter } from "node:events";
+import { EncodeRun } from "../services/encode/EncodeRun.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @param {string} relative
+ * @returns {string}
+ */
+function source(relative) {
+  return readFileSync(path.join(HERE, "..", relative), "utf8");
+}
+
+/**
+ * Every source file of the proxy's services, read together.
+ *
+ * A rule that something must not come back is asked of all of them: asked of
+ * one file, it passes as soon as the code moves to another.
+ *
+ * @returns {string}
+ */
+function everything() {
+  return readdirSync(path.join(HERE, "..", "services"), { recursive: true })
+    .filter((name) => String(name).endsWith(".js"))
+    .map((name) => source(path.join("services", String(name))))
+    .join("\n");
+}
+
+/**
+ * Lines of code, without comments or blanks: a rule about what the code does
+ * must not be answered by what a comment says about it.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function statements(text) {
+  return text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("//") && !line.startsWith("*") && !line.startsWith("/*"));
+}
+
+test("an encoder is stopped for scheduling reasons in exactly one place", () => {
+  // The orchestrator decides; nobody else may. What is left in the session
+  // manager is teardown — the session is going away and its encoders with it —
+  // which is not a decision about which encoders should exist.
+  const orchestrator = statements(source("services/encode/EncodeOrchestrator.js"));
+  const stopsInOrchestrator = orchestrator.filter((line) => line.includes("run.stop("));
+  assert.equal(stopsInOrchestrator.length, 1, "the orchestrator stops runs in one place");
+
+  const wiring = statements(source("services/server/wire-outputs.js"));
+  assert.deepEqual(wiring.filter((line) => line.includes(".stop(")), [], "the wiring stops nothing");
+  const lifecycle = statements(source("services/server/OutputLifecycle.js"));
+  const stopsAtTeardown = lifecycle.filter((line) => line.includes(".stop("));
+  assert.equal(
+    stopsAtTeardown.length,
+    1,
+    "an output's end stops its runs, and nothing else there does: " + stopsAtTeardown.join(" / ")
+  );
+  // And the runs themselves stop one for a stated reason in one place, which is
+  // what a corrected cut table asks through.
+  const runs = statements(source("services/encode/EncodeRuns.js"));
+  assert.equal(runs.filter((line) => line.includes(".stop(")).length, 1);
+});
+
+test("nothing outside the encoding layer starts an encoder", () => {
+  // A run is built in one place. Two places building them is how a start came
+  // to kill what the plan had decided to keep — the killing lived in the
+  // building.
+  const builds = statements(everything()).filter((line) => line.includes("new EncodeRun("));
+  assert.equal(builds.length, 1, "one place builds an encoder");
+});
+
+test("a run exists means its process is running, so nothing can start one twice", () => {
+  // WHAT THIS IS FOR, and why the test above did not catch it. That one counts
+  // where a run is BUILT and asks nothing about where it is STARTED, and until
+  // 2026-09-10 those were two acts: the session manager built a run and started
+  // it, handed it back, and the orchestrator started it again. Every run of
+  // every session therefore had two ffmpeg processes on one output writing one
+  // set of names — 207 runs against 414 spawns in the field logs of 08-10
+  // September, without a single exception — and only the second was reachable,
+  // so a stop killed one and the other ran on, measured 105 seconds past its
+  // own run's death.
+  //
+  // Asserted over the source because the guarantee IS a property of the source:
+  // there is no second act for a second owner to perform.
+  const files = [
+    "services/encode/EncodeRun.js",
+    "services/encode/EncodeOrchestrator.js",
+    "services/encode/EncodeRuns.js",
+    "services/server/wire-outputs.js"
+  ];
+  for (const file of files) {
+    const starts = statements(source(file)).filter(
+      (line) =>
+        /(?:^|[^a-zA-Z#])start\(/.test(line) &&
+        !/startsWith|startPosition|startIndex|startSeconds|startAt|startNumber/.test(line)
+    );
+    assert.deepEqual(starts, [], "an encoder is started by hand in " + file + ": " + starts.join(" / "));
+  }
+});
+
+test("starting an encoder stops nothing", () => {
+  // The rule that broke it: the start path looked for a live run whose own
+  // start was not below the new one's and killed it. It is not enough that the
+  // line is gone — the words it was written with must not come back.
+  const manager = everything();
+  assert.equal(
+    manager.includes("previousRun"),
+    false,
+    "there is no such thing as the previous run: a session holds several"
+  );
+  assert.equal(manager.includes("a new run is taking its place"), false);
+});
+
+test("a seek moves the viewer and nothing else", () => {
+  // It used to do eleven things and write the position into five places. What
+  // follows from a viewer moving is the map's business, and the orchestrators
+  // read the map.
+  const manager = source("services/server/ViewerRequests.js");
+  const at = manager.indexOf("requestSeek(sessionId, positionSeconds");
+  assert.notEqual(at, -1, "the seek is where this reads it");
+  const seek = manager.slice(at, at + 2000);
+  const body = seek.slice(0, seek.indexOf("\n  }\n"));
+  assert.equal(body.includes("#startEncodeRun"), false, "a seek starts no encoder");
+  assert.equal(body.includes("setTimeout"), false, "and waits for nothing");
+});
+
+test("how far an encoder may work is answered once", () => {
+  // The plan computes the stretch and it reaches ffmpeg. A second computation
+  // somewhere else is what made the first one pointless: it was passed and then
+  // dropped by a parameter list that did not name it.
+  const orchestrator = source("services/encode/EncodeOrchestrator.js");
+  assert.match(
+    orchestrator,
+    /makeRun\(\{ address, from, to, because \}\)/,
+    "the stretch is handed over, and so are the plan's own words for why"
+  );
+});
+
+test("only the plan places an encoder", () => {
+  // The count is the whole of this item. There were eight other places: the
+  // first run of a session, a viewer joining it further in, a rung or a
+  // soundtrack being warmed, one being switched to, a hardware encoder falling
+  // back to software, an input coming back, a cut table correcting itself, and
+  // a settled seek. Each of them chose a position by a rule of its own, and the
+  // plan — which is arithmetic over what is made, what is being made and what is
+  // wanted — was left to compare its answer against theirs.
+  const manager = source("services/encode/EncodeRuns.js");
+  const starts = [...manager.matchAll(/this\.#startEncodeRun\(/g)].length;
+  assert.equal(starts, 1, "one caller, and it is the one the plan asks through");
+  assert.match(
+    manager,
+    /makeRunAt\(address, from, to, because\)[\s\S]{0,3000}this\.#startEncodeRun\(base, from, because, \{ to \}\)/,
+    "and that caller is what the plan is given to build runs with"
+  );
+});
+
+test("nobody stops an encoder for being unwatched", () => {
+  // Whether an encoder is still wanted is the same question as where one should
+  // be, and the plan answers it: an output with nobody on it has a priority map
+  // with nothing in it. Answered here as well, it was answered twice by two
+  // rules — and since a viewer moving between steps announces itself, the plan
+  // started again what this class had just killed, several times a second.
+  const manager = everything();
+  assert.equal(
+    manager.includes("no viewer is watching"),
+    false,
+    "a rung nobody is on is a fact, not an act"
+  );
+  assert.equal(manager.includes("no viewer is listening to audio track"), false);
+  assert.equal(
+    manager.includes("warmed for a switch the viewer did not make"),
+    false,
+    "an abandoned warm-up is a viewer leaving an output"
+  );
+  assert.equal(manager.includes("prepared for a track change the viewer did not make"), false);
+});
+
+test("the seek settle machinery is gone, whole", () => {
+  // A viewer's position is applied the moment they state it. The settle was a
+  // second debounce on a signal the browser had already debounced, and every
+  // millisecond of it was dead time in front of the viewer; the cooldown behind
+  // it existed because segment REQUESTS once steered the encoder.
+  const manager = everything();
+  for (const gone of [
+    "seekSettleTimer",
+    "seekTarget",
+    "seekFirstFarAt",
+    "SEEK_SETTLE_MS",
+    "SEEK_SETTLE_MAX_MS",
+    "RESTART_COOLDOWN_MS",
+    "SEEK_BACKOFF_SEGMENTS",
+    "#fireSettledSeek",
+    "#seekSession"
+  ]) {
+    assert.equal(manager.includes(gone), false, `${gone} is gone`);
+  }
+});
+
+test("where a soundtrack begins is read off the table, not handed in", () => {
+  // The instant a number really begins is a fact of the FILE's cutting, held in
+  // the live table every session of the file shares. Passed as an argument by
+  // the one caller that had measured it, only a run started by that caller ever
+  // had it, and a run the plan placed at the same number landed apart again.
+  const manager = source("services/encode/EncodeRuns.js");
+  assert.match(
+    manager,
+    /const positionSecondsOverride = session\.spec\.carries === "audio-only"\s*\n?\s*\? trueStartOf\(session\.timeline, startIndex\)/,
+    "derived where the run is built"
+  );
+  assert.equal(
+    manager.includes("this.#startEncodeRun(member, index, trueStart)"),
+    false,
+    "and not carried in from the correction that measured it"
+  );
+});
+
+test("each output is handed its own priority map, and the plan is what reads it", () => {
+  // The map is one fact asked at two scopes, and both are right for what asks
+  // them: the swarm is asked for bytes of a FILE, which every output of it
+  // reads, and encoders are placed per OUTPUT, which a person watching 480p
+  // wants nothing of at 1080p.
+  const manager = source("services/encode/EncodeRuns.js");
+  assert.match(
+    manager,
+    /notePriorityMap\([\s\S]{0,200}mapForOutput\(address\)/,
+    "the encoding reads the output's own map"
+  );
+  assert.equal(
+    manager.includes("this.priority.mapFor("),
+    false,
+    "and never the whole film's, which wanted an encoder on every output of it"
+  );
+});
+
+test("one process per run, and no way to ask for a second", () => {
+  const spawned = [];
+  const run = new EncodeRun({
+    address: "torrent:abc:video-only:v=0/copy",
+    encoder: { name: "libx264", kind: "software" },
+    from: 0,
+    to: 4,
+    buildArgs: () => [],
+    spawn: () => {
+      const child = new EventEmitter();
+      child.stdout = new EventEmitter();
+      child.stderr = new EventEmitter();
+      child.stdio = [null, child.stdout, child.stderr, new EventEmitter()];
+      child.kill = () => undefined;
+      child.pid = 1 + spawned.length;
+      spawned.push(child);
+      return child;
+    },
+    logger: { info: () => undefined, warn: () => undefined },
+    now: () => 1000,
+    because: "a test asked for it"
+  });
+
+  assert.equal(spawned.length, 1, "building a run did not put a process on the machine");
+  assert.equal(
+    Reflect.get(run, "start"),
+    undefined,
+    "a run still offers a way to start it a second time"
+  );
+});