@torrent-tv/proxy 2.75.0 → 2.76.0

package/test/helpers/encode-run.js

@@ -0,0 +1,128 @@
+/**
+ * @file A real `EncodeRun` over a process that is not real.
+ *
+ * Tests used to set a session's process fields by hand — `session.ffmpeg`,
+ * `session.runState`, `session.encodeStartIndex` — which is how a test can pass
+ * over code that no longer works: the fields were the thing under test as much
+ * as the behaviour was. A run is an object now, so a test builds the object the
+ * product builds and injects only the one thing a test may not have, which is a
+ * child process.
+ *
+ * The pid is deliberately absent unless a test asks for one. `pause` and
+ * `resume` send signals by pid, and a made-up number is somebody else's process
+ * on the machine running the tests.
+ */
+
+import { EncodeRun } from "../../services/encode/EncodeRun.js";
+
+/**
+ * A child process that records what was done to it.
+ *
+ * @param {object} [options]
+ * @param {number | null} [options.pid] - Only where a test genuinely exercises
+ *   suspend or resume, and then it must be this process's own.
+ * @returns {object}
+ */
+export function fakeProcess({ pid = null, exitsWhenKilled = true } = {}) {
+  /** @type {Map<string, (...args: unknown[]) => void>} */
+  const listeners = new Map();
+  return {
+    pid,
+    killed: false,
+    exitCode: null,
+    signalCode: null,
+    /** Every signal it was sent, in order. */
+    signals: [],
+    stdout: { on() {} },
+    stderr: { on() {} },
+    on(event, handler) {
+      const kept = listeners.get(event) ?? [];
+      kept.push(handler);
+      listeners.set(event, kept);
+      return this;
+    },
+    once(event, handler) {
+      return this.on(event, handler);
+    },
+    kill(signal = "SIGTERM") {
+      this.signals.push(signal);
+      this.killed = true;
+      // A real process answers a signal by exiting, and it does so on a later
+      // turn. A fake that never exits makes every disposal wait out the grace
+      // period, which is two seconds a test spends proving nothing.
+      if (exitsWhenKilled && this.exitCode === null && this.signalCode === null) {
+        queueMicrotask(() => this.exit(null, signal));
+      }
+      return true;
+    },
+    /**
+     * Report an exit, as the real thing would.
+     *
+     * @param {number | null} code
+     * @param {string | null} [signal]
+     */
+    exit(code, signal = null) {
+      this.exitCode = code;
+      this.signalCode = signal;
+      for (const handler of listeners.get("exit") ?? []) {
+        handler(code, signal);
+      }
+    }
+  };
+}
+
+/** A logger that says nothing, for tests that are not about the log. */
+export const silentLogger = { info() {}, warn() {}, error() {} };
+
+/**
+ * Add a run to a session, started, over a fake process.
+ *
+ * A session holds a SET of runs — as many as the machine affords — so a test
+ * that wants two heads on one output calls this twice.
+ *
+ * @param {object} session - The session under test.
+ * @param {object} [options]
+ * @param {number} [options.from] - First segment number it is making.
+ * @param {number} [options.to] - Last, inclusive; below `from` means no end.
+ * @param {object} [options.process] - The process it should own.
+ * @param {boolean} [options.producing] - Whether it has already made its first
+ *   segment, which is what moves it out of starting.
+ * @param {number | null} [options.lastSegmentIndex] - The film's last number,
+ *   for telling a finished file from an input that dried up.
+ * @param {boolean} [options.usesExplicitCuts]
+ * @returns {import("../../services/encode/EncodeRun.js").EncodeRun}
+ */
+export function startRunOn(session, options = {}) {
+  const {
+    from = 0,
+    to = -1,
+    process: child = fakeProcess(),
+    producing = true,
+    lastSegmentIndex = null,
+    usesExplicitCuts = false
+  } = options;
+  const run = new EncodeRun({
+    address: session.outputKey ?? session.id ?? "output",
+    encoder: { name: "libx264", kind: "software" },
+    from,
+    to,
+    buildArgs: () => [],
+    spawn: () => child,
+    logger: silentLogger,
+    lastSegmentIndex: () => lastSegmentIndex,
+    usesExplicitCuts
+  });
+  run.start("a test asked for it");
+  if (producing) {
+    // What moves a run out of starting is its first segment, in the product as
+    // here — so a run that is producing has made one, and its head stands one
+    // past where it began. `from` is still where it started, which is what a
+    // test asserting a run's position asks for.
+    run.noteProduced(from);
+  }
+  if (!(session.runs instanceof Set)) {
+    session.runs = new Set();
+  }
+  session.runs.add(run);
+  return run;
+}

package/test/keyframe-index-accuracy.test.js

@@ -15,6 +15,8 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { SourceFile } from "../services/source/SourceFile.js";
+import { Timeline } from "../services/output/Timeline.js";
 import { newIndexCheck, noteIndexDeviation } from "../services/hls-session-manager.js";
 
 test("an index that describes its file exactly is reported as such", () => {
@@ -65,14 +67,17 @@ test("a boundary the index got wrong is replaced by the time the file really has
     localPort: 9090
   });
   t.after(() => manager.disposeAll());
+  // ONE table for the film, held by both. It used to be a copy each, kept in
+  // step by writing the correction into every member — which is what the shared
+  // table replaces, and what drifted in the field.
+  const boundaries = [0, 10, 20, 30, 40];
   const base = {
     id: "aaaaaaaa-1111-2222-3333-444444444444",
     fileName: "film.mkv",
     state: "ready",
     transcodeVideo: false,
-    segmentBoundaries: [0, 10, 20, 30, 40],
-    indexCheck: newIndexCheck(),
-    variants: new Map(),
+    timeline: new Timeline({ boundaries: boundaries, cutGrid: "uniform" }),
+    file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "film.mkv" }),
     segmentFormat: { segmentFileName: (index) => `segment-${index}.mp4` }
   };
   const rung = {
@@ -80,11 +85,13 @@ test("a boundary the index got wrong is replaced by the time the file really has
     fileName: "film.mkv",
     state: "ready",
     transcodeVideo: true,
-    segmentBoundaries: [0, 10, 20, 30, 40],
-    indexCheck: newIndexCheck(),
-    variantBases: new Set([base.id])
+    timeline: new Timeline({ boundaries: boundaries, cutGrid: "uniform" }),
+    // A step of the picture: the same file, and made as a step.
+    file: base.file,
+    variantHeight: 540,
+    isStep: true
   };
-  base.variants.set(540, rung.id);
+  base.file.stepHeights.set(540, 540);
   manager.sessionsById.set(base.id, base);
   manager.sessionsById.set(rung.id, rung);
 
@@ -93,17 +100,17 @@ test("a boundary the index got wrong is replaced by the time the file really has
   manager.correctBoundaryFromSegment(base, 2, 17.4);
 
   assert.equal(
-    base.segmentBoundaries[2],
+    base.timeline.boundaries[2],
     17.4,
     "the grid must describe the file, not the index — a rung forced onto 20 s would not join the copy"
   );
   assert.equal(
-    rung.segmentBoundaries[2],
+    rung.timeline.boundaries[2],
     17.4,
-    "the family shares one grid, so a correction reaches the rungs cut against it"
+    "the family shares one grid — the same array, so there is nothing to keep in step"
   );
   assert.deepEqual(
-    base.segmentBoundaries,
+    base.timeline.boundaries,
     [0, 10, 17.4, 30, 40],
     "only the boundary that was shown to be wrong moves"
   );
@@ -114,7 +121,7 @@ test("a boundary the index got wrong is replaced by the time the file really has
   manager.correctBoundaryFromSegment(base, 2, 35);
   manager.correctBoundaryFromSegment(base, 2, 5);
   manager.correctBoundaryFromSegment(base, 0, 3);
-  assert.deepEqual(base.segmentBoundaries, [0, 10, 17.4, 30, 40], "out-of-order readings are refused");
+  assert.deepEqual(base.timeline.boundaries, [0, 10, 17.4, 30, 40], "out-of-order readings are refused");
 });
 
 test("a segment requested again is not new evidence", () => {

package/test/keyframes-belong-to-the-file.test.js

@@ -0,0 +1,132 @@
+/**
+ * @file Where a file's keyframes are is a fact of the file, not of a session.
+ *
+ * It is a property of immutable bytes, like the duration and the track list, so
+ * a second reading could only agree. Two sessions created in the same moment
+ * used to read it twice — which is what two viewers opening one film do,
+ * measured 13 ms apart on 2026-09-03 — and the answer decides whether the
+ * picture can be copied at all, so it has to be one answer.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { Container } from "../services/container/Container.js";
+
+/**
+ * @returns {HlsSessionManager}
+ */
+function manager() {
+  return new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+}
+
+test("two sessions asking at once make one read and join one wait", async () => {
+  const session = manager();
+  let reads = 0;
+  let answer = null;
+  session.getContainerKeyframes = () => {
+    reads += 1;
+    return new Promise((resolve) => {
+      answer = resolve;
+    });
+  };
+
+  const first = session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" });
+  const second = session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" });
+  assert.equal(reads, 1, "the second asker joined the read already running");
+
+  answer({ times: [0, 4, 8], tolerance: 0 });
+  await Promise.all([first, second]);
+  assert.equal(reads, 1);
+});
+
+test("the answer is remembered for the file, so a later session reads nothing", async () => {
+  const session = manager();
+  let reads = 0;
+  session.getContainerKeyframes = async () => {
+    reads += 1;
+    return { times: [0, 4, 8], tolerance: 0 };
+  };
+
+  await session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" });
+  await session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" });
+
+  assert.equal(reads, 1);
+});
+
+test("two files of one torrent are two answers", async () => {
+  const session = manager();
+  const asked = [];
+  session.getContainerKeyframes = async ({ fileIndex }) => {
+    asked.push(fileIndex);
+    return { times: [0, 4], tolerance: 0 };
+  };
+
+  await session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" });
+  await session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 1, logName: "b.mkv" });
+
+  assert.deepEqual(asked, [0, 1]);
+});
+
+test("a file with no readable index says so once, and keeps saying it", async () => {
+  const session = manager();
+  let reads = 0;
+  session.getContainerKeyframes = async () => {
+    reads += 1;
+    return null;
+  };
+
+  await session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.ts" });
+  await session.warmKeyframeIndex({ sourceKey: "torrent:abc", fileIndex: 0, logName: "a.ts" });
+
+  // "No index" is an answer about the file — it is what makes a copy of it
+  // re-encode instead — and it must be the same answer for every viewer.
+  assert.equal(reads, 1);
+});
+
+test("a container reads its own table once", async () => {
+  let parses = 0;
+  class OneTable extends Container {
+    async parseKeyframeIndex() {
+      parses += 1;
+      return { times: [0, 2, 4], tolerance: 0 };
+    }
+  }
+  const container = new OneTable({ readRange: async () => null, fileSize: 10 });
+
+  const [first, second] = await Promise.all([
+    container.readKeyframeIndex(),
+    container.readKeyframeIndex()
+  ]);
+  await container.readKeyframeIndex();
+
+  assert.equal(parses, 1);
+  assert.deepEqual(first, second);
+});
+
+test("a read that threw is not remembered as an answer", async () => {
+  let parses = 0;
+  class Late extends Container {
+    async parseKeyframeIndex() {
+      parses += 1;
+      if (parses === 1) {
+        // The bytes it needed had not arrived yet, which is not a statement
+        // about the file.
+        throw new Error("nothing to read there yet");
+      }
+      return { times: [0, 2], tolerance: 0 };
+    }
+  }
+  const container = new Late({ readRange: async () => null, fileSize: 10 });
+
+  await assert.rejects(() => container.readKeyframeIndex());
+  const second = await container.readKeyframeIndex();
+
+  assert.equal(parses, 2);
+  assert.deepEqual(second.times, [0, 2]);
+});

package/test/orchestrator-wired.test.js

@@ -0,0 +1,164 @@
+/**
+ * @file The plan is what decides the encoders, and it is asked of real sessions.
+ *
+ * Three rules written into the session manager become one here: where a run
+ * belongs, when it has been overtaken, and how many the machine affords. The
+ * point of wiring rather than duplicating is that the arithmetic has sixteen
+ * checks of its own and no ffmpeg behind it.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SourceFile } from "../services/source/SourceFile.js";
+import { Timeline } from "../services/output/Timeline.js";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { SegmentStore } from "../services/encode/SegmentStore.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+import { viewerOf } from "../services/viewer/Viewer.js";
+import { startRunOn } from "./helpers/encode-run.js";
+
+const KEY = "torrent:abc:fmt=fmp4:grid=kf@0:video-only:v=0/copy";
+
+function managerWithAnOutput() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "orchestrator-wired-"));
+  const store = new SegmentStore({ root });
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090,
+    segmentStore: store
+  });
+  const dirPath = store.directoryFor(KEY);
+  store.useFormat(KEY, fmp4Format);
+  return { manager, store, root, dirPath };
+}
+
+function sessionOn({ id, dirPath, encodeStartIndex = 0, runEndIndex = -1, speed = 0, running = true }) {
+  const session = {
+    id,
+    outputKey: KEY,
+    dirPath,
+    // Where this file is cut, held by the file. A fixture that stated it
+    // on the session was describing what production no longer does.
+    timeline: new Timeline({
+      boundaries: Array.from({ length: 1001 }, (_, index) => index * 4),
+      cutGrid: "uniform"
+    }),
+    state: "ready",
+    file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "video.mkv" }),
+    // An ordinary session reads its own file, and its sound is inside it. The
+    // three differ only for a soundtrack shipped as a file of its own.
+    get inputFile() { return this.file; },
+    get audioFile() { return this.file; },
+    segmentFormat: fmp4Format,
+    segmentCount: 1000,
+    recentSpeed: null,
+    consumers: new Set(),
+    viewers: new Map(),
+    runs: new Set(),
+    lastAccessedAt: Date.now()
+  };
+  if (running) {
+    const run = startRunOn(session, { from: encodeStartIndex, to: runEndIndex });
+    // A speed is a reading taken FROM a run, so it names the run it came from.
+    session.recentSpeed = speed > 0 ? { speed, at: Date.now(), run } : null;
+    run.noteSpeed(speed);
+  }
+  return session;
+}
+
+test("a session is handed to the plan as the run it is", (t) => {
+  const { manager, root, dirPath } = managerWithAnOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const session = sessionOn({ id: "one", dirPath, encodeStartIndex: 10, runEndIndex: 40 });
+  manager.sessionsById.set(session.id, session);
+  viewerOf(session, "watching").head = { segment: 12, seconds: 48, at: Date.now() };
+
+  manager.runQualityBudgetOnce;
+  manager.planEncodersNow();
+
+  const runs = manager.encodeOrchestrator.runsOn(KEY);
+  assert.equal(runs.length, 1, "the session the browser already has is a run like any other");
+  assert.equal(runs[0], [...session.runs][0], "and it is the run the session actually holds");
+  assert.equal(runs[0].from, 10);
+  assert.equal(runs[0].to, 40);
+});
+
+test("what a viewer waits for reaches the plan without their name", (t) => {
+  const { manager, root, dirPath } = managerWithAnOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const session = sessionOn({ id: "one", dirPath, encodeStartIndex: 0, runEndIndex: -1 });
+  manager.sessionsById.set(session.id, session);
+  viewerOf(session, "someone").head = { segment: 5, seconds: 20, at: Date.now() };
+
+  manager.planEncodersNow();
+
+  const wanted = manager.encodeOrchestrator.demand.windowsOn(KEY);
+  assert.equal(wanted.length, 1);
+  assert.equal(wanted[0].from, 5, "where they are");
+  assert.ok(wanted[0].to > 5, "and the cushion in front of them");
+});
+
+test("a viewer who has gone quiet stops being waited for", (t) => {
+  const { manager, root, dirPath } = managerWithAnOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const session = sessionOn({ id: "one", dirPath });
+  manager.sessionsById.set(session.id, session);
+  viewerOf(session, "gone").head = { segment: 5, seconds: 20, at: Date.now() - 10 * 60 * 1000 };
+
+  manager.planEncodersNow();
+
+  assert.equal(manager.encodeOrchestrator.demand.windowsOn(KEY).length, 0);
+});
+
+test("how many encoders the machine affords is measured, not chosen", (t) => {
+  const { manager, root, dirPath } = managerWithAnOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  // Nothing measured yet: one is what it has.
+  const cold = sessionOn({ id: "cold", dirPath });
+  manager.sessionsById.set(cold.id, cold);
+  assert.equal(manager.maxRunsForOutput(KEY), 1);
+
+  // Fast, but what a second job costs on THIS machine has not been measured,
+  // and an unmeasured penalty of 1 is not a statement that it is free.
+  cold.recentSpeed = { speed: 7.12 };
+  assert.equal(manager.maxRunsForOutput(KEY), 1, "no measurement, no second encoder");
+
+  // Measured on the addon host 2026-09-03: at 854x480 one run made 7.12x and
+  // two made 4.20x and 4.16x, a penalty of 1.70x, and both stayed far above
+  // realtime.
+  manager.contentionPenalties = new Map([[1, 1.7]]);
+  assert.ok(manager.maxRunsForOutput(KEY) > 1, "measured, and a second fits");
+
+  // The same host at 1920x1080: one made 1.96x, two made 0.99x and 0.98x.
+  manager.contentionPenalties = new Map([[1, 1.98]]);
+  cold.recentSpeed = { speed: 1.96 };
+  assert.equal(manager.maxRunsForOutput(KEY), 1, "the machine is full at one");
+});
+
+test("segments already made are known to the plan, whoever made them", (t) => {
+  const { manager, store, root, dirPath } = managerWithAnOutput();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  for (const index of [0, 1, 2, 3]) {
+    writeFileSync(path.join(dirPath, fmp4Format.segmentFileName(index)), Buffer.alloc(16, 1));
+  }
+  const session = sessionOn({ id: "one", dirPath });
+  manager.sessionsById.set(session.id, session);
+
+  manager.planEncodersNow();
+
+  const coverage = manager.encodeOrchestrator.coverageOf(KEY);
+  assert.equal(coverage.isReady(0), true);
+  assert.equal(coverage.isReady(2), true);
+  assert.equal(coverage.isReady(3), false, "the highest has no successor to prove it closed");
+  void store;
+});

package/test/output-shape.test.js

@@ -0,0 +1,68 @@
+/**
+ * @file What an output is encoded AS is decided once, for the output.
+ *
+ * The realtime budget decides the box, the frame rate and the speed setting
+ * from what the machine could hold at that moment. Decided per SESSION, two
+ * sessions of one output made minutes apart could be given different pictures
+ * while claiming the same identity — and everything downstream assumes they
+ * cannot be, from a segment of one standing in for a segment of the other to
+ * the single RESOLUTION the master names for both.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Output, Outputs } from "../services/output/Output.js";
+
+const KEY = "torrent:abc:fmt=fmp4:grid=even@0:video-only:v=0/enc:1280x720:auto";
+
+test("the second session of one output is given the shape the first was", () => {
+  const outputs = new Outputs();
+  const first = outputs.get(KEY, () => new Output({
+    encodeWidth: 1280,
+    encodeHeight: 720,
+    outputFps: 24,
+    softwarePreset: "veryfast",
+    applyTonemap: false
+  }));
+  // A minute later the machine is busier and the budget would answer 480p. It
+  // is not asked: the shape of this output was settled when it was first made.
+  const second = outputs.get(KEY, () => {
+    throw new Error("deciding twice is how two sessions of one output diverge");
+  });
+
+  assert.equal(second, first);
+  assert.equal(second.encodeHeight, 720);
+});
+
+test("two outputs are two shapes", () => {
+  const outputs = new Outputs();
+  const tall = outputs.get(KEY, () => new Output({ encodeWidth: 1280, encodeHeight: 720, outputFps: 24 }));
+  const short = outputs.get(`${KEY}:other`, () => new Output({
+    encodeWidth: 854,
+    encodeHeight: 480,
+    outputFps: 24
+  }));
+
+  assert.notEqual(short, tall);
+  assert.equal(short.encodeHeight, 480);
+});
+
+test("a copied picture has no box of its own, and says so with zeroes", () => {
+  // Zero means the source's own size, which is what a copy is by definition:
+  // no box asked for can change one byte of it.
+  const copied = new Output({ encodeWidth: 0, encodeHeight: 0, outputFps: 24 });
+
+  assert.equal(copied.encodeWidth, 0);
+  assert.equal(copied.encodeHeight, 0);
+  assert.equal(copied.softwarePreset, null, "and no speed setting, having no encoder");
+});
+
+test("a shape nobody holds is dropped", () => {
+  const outputs = new Outputs();
+  const kept = outputs.get(KEY, () => new Output({ encodeWidth: 1280, encodeHeight: 720, outputFps: 24 }));
+  outputs.get(`${KEY}:other`, () => new Output({ encodeWidth: 854, encodeHeight: 480, outputFps: 24 }));
+
+  assert.equal(outputs.size, 2);
+  assert.equal(outputs.forgetUnused(new Set([kept])), 1);
+  assert.equal(outputs.size, 1);
+});