@torrent-tv/proxy 2.75.0 → 2.76.1

package/test/encode-plan.test.js

@@ -0,0 +1,245 @@
+/**
+ * @file How many encoders there should be, and where.
+ *
+ * Every case here is one the code used to get wrong for a reason recorded in
+ * `research/encoder-layer-2026-09-04.md`: a run placed at a viewer's position
+ * rather than at the first thing missing, a run with no end, and nothing that
+ * stops a run which has caught up with material already made.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { CoverageMap } from "../services/encode/CoverageMap.js";
+import { firstUnmetWant, planEncoders } from "../services/encode/EncodePlan.js";
+
+/** A host that can afford two encoders, four-second segments, a cheap restart. */
+const HOST = { maxRuns: 2, segmentSeconds: 4, restartCostSec: 0.12 };
+
+/**
+ * @param {Partial<import("../services/encode/EncodePlan.js").LiveRun>} run
+ * @returns {import("../services/encode/EncodePlan.js").LiveRun}
+ */
+function run(run_) {
+  // A run has no name: the plan hands back the run itself, so a test compares
+  // the thing rather than a token standing for it.
+  return { from: 0, to: 100, head: 0, speedX: 2, ...run_ };
+}
+
+test("a viewer waiting on nothing made starts one encoder, at what they are waiting for", () => {
+  // It starts where the viewer is stopped and runs to the end of the film,
+  // because nothing else is in the way. The window says where to start and
+  // whether to start; it does not say where to stop — a window travels forward
+  // as the viewer plays, and a run bounded by one has to be replaced every few
+  // seconds.
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 40, to: 70 }],
+    runs: [],
+    ...HOST
+  });
+  assert.deepEqual(
+    actions.map((action) => ({ type: action.type, from: action.from, to: action.to })),
+    [{ type: "start", from: 40, to: 99 }]
+  );
+});
+
+test("a viewer whose cushion reaches past a running encoder starts nothing", () => {
+  // Found by the orchestrator's own checks: with the end taken from the window,
+  // a second viewer two segments further on was given an encoder of their own
+  // to make those two, while the run already there had nowhere left to go.
+  const coverage = new CoverageMap({ segmentCount: 1000 });
+  const runA = run({ from: 100, to: 999, head: 100 });
+  coverage.claim(runA, 100, 999);
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 100, to: 130 }, { from: 102, to: 132 }],
+    runs: [runA],
+    ...HOST
+  });
+  assert.equal(actions.some((action) => action.type === "start"), false);
+});
+
+test("a viewer whose whole window is already made starts nothing", () => {
+  // The case that used to restart an encoder to make a second copy of material
+  // sitting on the disk.
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  for (let index = 40; index <= 70; index += 1) {
+    coverage.markReady(index);
+  }
+  const actions = planEncoders({ coverage, windows: [{ from: 40, to: 70 }], runs: [], ...HOST });
+  assert.deepEqual(actions, []);
+});
+
+test("a run is given an end at the edge of what is free", () => {
+  // Handed the rest of the film it would drive straight into another run's
+  // ground; handed the free stretch it stops where the covered material starts.
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const runB = run({ from: 50, to: 80 });
+  coverage.claim(runB, 50, 80);
+  const actions = planEncoders({ coverage, windows: [{ from: 40, to: 90 }], runs: [], ...HOST });
+  assert.equal(actions.length, 1);
+  assert.deepEqual({ from: actions[0].from, to: actions[0].to }, { from: 40, to: 49 });
+});
+
+test("a run that has caught up with made material is moved forward, not killed", () => {
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const runA = run({ head: 10, from: 0, to: 100 });
+  coverage.claim(runA, 0, 100);
+  for (let index = 10; index <= 30; index += 1) {
+    coverage.markReady(index);
+  }
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 90 }],
+    runs: [runA],
+    ...HOST
+  });
+  const move = actions.find((action) => action.type === "move");
+  assert.ok(move, "it should have been moved");
+  assert.equal(move.run, runA);
+  assert.equal(move.from, 31, "to the first thing nobody has");
+  assert.equal(actions.some((action) => action.type === "stop"), false, "and not stopped");
+});
+
+test("a covered stretch shorter than a restart is driven through instead", () => {
+  // The comparison is of two measured quantities: the covered stretch divided
+  // by this run's own speed, against what a restart costs. One segment at 50x
+  // is 0.08 s of encoding against 0.12 s to move.
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const runA = run({ head: 10, speedX: 50 });
+  coverage.claim(runA, 0, 100);
+  coverage.markReady(10);
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 90 }],
+    runs: [runA],
+    ...HOST
+  });
+  assert.equal(actions.some((action) => action.type === "move"), false);
+  assert.ok(actions.some((action) => action.type === "keep" && action.run === runA));
+});
+
+test("a run whose speed nothing has measured is moved rather than left driving through", () => {
+  // Not a default: driving through is work that is certainly wasted, and the
+  // restart is a known and small cost. What cannot be done is the comparison.
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const runA = run({ head: 10, speedX: 0 });
+  coverage.claim(runA, 0, 100);
+  coverage.markReady(10);
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 90 }],
+    runs: [runA],
+    ...HOST
+  });
+  const move = actions.find((action) => action.type === "move");
+  assert.ok(move);
+  assert.match(move.because, /speed is not measured/);
+});
+
+test("a run with nothing left to make ahead of it is stopped", () => {
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const runA = run({ head: 10 });
+  coverage.claim(runA, 0, 100);
+  for (let index = 10; index <= 90; index += 1) {
+    coverage.markReady(index);
+  }
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 90 }],
+    runs: [runA],
+    ...HOST
+  });
+  assert.deepEqual(
+    actions.map((action) => action.type),
+    ["stop"]
+  );
+});
+
+test("every encoder stops when nobody is watching the output", () => {
+  // A look-ahead cannot answer this: it asks how far AHEAD of a viewer a run
+  // is, and there is no viewer.
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  const runA = run();
+  const runB = run();
+  const actions = planEncoders({
+    coverage,
+    windows: [],
+    runs: [runA, runB],
+    ...HOST
+  });
+  assert.deepEqual(
+    actions.map((action) => [action.type, action.run]),
+    [["stop", runA], ["stop", runB]]
+  );
+});
+
+test("a run making material nobody asked for is stopped", () => {
+  const coverage = new CoverageMap({ segmentCount: 1000 });
+  const runA = run({ from: 500, to: 600, head: 520 });
+  coverage.claim(runA, 500, 600);
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 40 }],
+    runs: [runA],
+    ...HOST
+  });
+  assert.ok(actions.some((action) => action.type === "stop" && action.run === runA));
+});
+
+test("two viewers far apart get an encoder each, when the machine can hold two", () => {
+  const coverage = new CoverageMap({ segmentCount: 1000 });
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 0, to: 30 }, { from: 800, to: 830 }],
+    runs: [],
+    ...HOST
+  });
+  const started = actions.filter((action) => action.type === "start").map((action) => action.from);
+  assert.deepEqual(started, [0, 800]);
+});
+
+test("a machine that can hold one gives it to the viewer who is stopped soonest", () => {
+  // The bound is the host's own budget, the same arithmetic that decides the
+  // quality offer. Measured on the addon host 2026-09-03: at 1080p one encode
+  // saturates the machine and two land on realtime.
+  const coverage = new CoverageMap({ segmentCount: 1000 });
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 800, to: 830 }, { from: 0, to: 30 }],
+    runs: [],
+    ...HOST,
+    maxRuns: 1
+  });
+  const started = actions.filter((action) => action.type === "start").map((action) => action.from);
+  assert.deepEqual(started, [0]);
+});
+
+test("a viewer joining behind a running encoder gets their own, not a dragged one", () => {
+  // This is what the whole layer is for. The run in front is untouched; the
+  // viewer behind is not made to wait for it to be pulled back.
+  const coverage = new CoverageMap({ segmentCount: 1000 });
+  const runA = run({ from: 500, to: 600, head: 510 });
+  coverage.claim(runA, 500, 600);
+  const actions = planEncoders({
+    coverage,
+    windows: [{ from: 500, to: 530 }, { from: 100, to: 130 }],
+    runs: [runA],
+    ...HOST
+  });
+  assert.ok(actions.some((action) => action.type === "keep" && action.run === runA));
+  assert.equal(actions.some((action) => action.type === "move"), false);
+  const started = actions.filter((action) => action.type === "start");
+  assert.equal(started.length, 1);
+  assert.equal(started[0].from, 100);
+});
+
+test("the lowest thing a viewer is waiting for is reported, so a stalled plan is visible", () => {
+  const coverage = new CoverageMap({ segmentCount: 100 });
+  coverage.markReady(40);
+  coverage.markReady(41);
+  assert.equal(firstUnmetWant(coverage, [{ from: 40, to: 70 }]), 42);
+  coverage.markReadyAll([42, 43, 44]);
+  assert.equal(firstUnmetWant(coverage, [{ from: 40, to: 44 }]), null);
+});

package/test/encode-run-state.test.js

@@ -25,7 +25,7 @@ import {
   nextState,
   processCanBeSignalled,
   wireState
-} from "../services/encode-run-state.js";
+} from "../services/encode/encode-run-state.js";
 
 const ALL_STATES = Object.values(ENCODE_RUN_STATE);
 const ALL_EVENTS = Object.values(ENCODE_RUN_EVENT);
@@ -271,7 +271,7 @@ test("the sawtooth of 2.9.93 is not expressible", () => {
 });
 
 test("a dead run cannot be mistaken for one that is covering the seek", () => {
-  // `session.ffmpeg` pointed at a corpse, so every later seek was waved through
+  // the process handle pointed at a corpse, so every later seek was waved through
   // as "already covered by the running encode" and the session answered 500 for
   // as long as the viewer kept trying.
   assert.equal(processCanBeSignalled(ENCODE_RUN_STATE.ENDED_FAILED), false);

package/test/encode-run.test.js

@@ -0,0 +1,168 @@
+/**
+ * @file One encoder's lifetime: the stretch it was given, where it got to, and
+ * whether its ending was the normal one.
+ *
+ * The process is injected, so none of this needs ffmpeg. What is checked is the
+ * accounting the user asked for on 2026-09-04: exactly one ending is normal,
+ * every other one says why, and none of them goes unrecorded.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { EncodeRun } from "../services/encode/EncodeRun.js";
+import { ENCODE_EXIT } from "../services/encode/encode-exit.js";
+import { SoftwareEncoder } from "../services/encode/SoftwareEncoder.js";
+
+/**
+ * A process that does nothing until the test says what became of it.
+ */
+class FakeProcess extends EventEmitter {
+  constructor() {
+    super();
+    this.pid = 4242;
+    this.signals = [];
+  }
+
+  kill(signal) {
+    this.signals.push(signal);
+  }
+
+  exitWith(code, signal = null) {
+    this.emit("exit", code, signal);
+  }
+}
+
+/**
+ * @param {Partial<{from:number,to:number}>} [span]
+ */
+function makeRun(span = {}) {
+  const lines = [];
+  const ends = [];
+  const process_ = new FakeProcess();
+  const run = new EncodeRun({
+    address: "torrent:abc:fmt=fmp4:grid=kf@0:video-only:v=0/enc:854x480:auto",
+    encoder: new SoftwareEncoder(),
+    from: span.from ?? 10,
+    to: span.to ?? 14,
+    buildArgs: () => ["-i", "in", "out"],
+    spawn: () => process_,
+    logger: {
+      info: (line) => lines.push(["info", line]),
+      warn: (line) => lines.push(["warn", line])
+    },
+    now: () => 1000,
+    onEnded: (ended) => ends.push(ended)
+  });
+  return { run, process: process_, lines, ends };
+}
+
+test("a start says why it is starting and with what", () => {
+  // The argument list alone cannot say whether this was a first open, a seek, a
+  // quality step or a move off covered material — and with several runs at once
+  // that is the only way to tell one start from another.
+  const { run, lines } = makeRun();
+  run.start("nobody is making #10 and a viewer is waiting for it");
+  const [level, line] = lines[0];
+  assert.equal(level, "info");
+  // A run is named by what it produces: the stretch it was given, on the output
+  // it makes segments of. No other live run of that output can hold it.
+  assert.match(line, /encode-run #10\.\.#14 of torrent:abc:/);
+  assert.match(line, /nobody is making #10/);
+  assert.match(line, /ffmpeg -i in out/);
+});
+
+test("its head is the next number it will make, and moves as it makes them", () => {
+  const { run } = makeRun();
+  run.start("first");
+  assert.equal(run.head, 10);
+  run.noteProduced(10);
+  run.noteProduced(11);
+  assert.equal(run.head, 12);
+  assert.equal(run.reached, 11);
+});
+
+test("reaching the end of its stretch and exiting is the one normal ending", () => {
+  const { run, process, ends, lines } = makeRun({ from: 10, to: 12 });
+  run.start("first");
+  for (const index of [10, 11, 12]) {
+    run.noteProduced(index);
+  }
+  process.exitWith(0, null);
+  assert.equal(ends.length, 1);
+  assert.equal(ends[0].ending, ENCODE_EXIT.COMPLETE);
+  assert.equal(ends[0].normal, true);
+  assert.equal(lines.at(-1)[0], "info", "a normal ending is not a warning");
+});
+
+test("exiting cleanly short of its stretch is abnormal and says where it stopped", () => {
+  // ffmpeg exits zero both at the end of a file and when its input stops
+  // producing bytes; over a torrent the two look identical to it.
+  const { run, process, ends } = makeRun({ from: 10, to: 14 });
+  run.start("first");
+  run.noteProduced(10);
+  run.noteProduced(11);
+  process.exitWith(0, null);
+  assert.equal(ends[0].ending, ENCODE_EXIT.SHORT);
+  assert.equal(ends[0].normal, false);
+  assert.equal(ends[0].reached, 11);
+  assert.match(ends[0].because, /#11 of #14/);
+});
+
+test("a non-zero exit is a failure carrying its code", () => {
+  const { run, process, ends, lines } = makeRun();
+  run.start("first");
+  process.exitWith(255, null);
+  assert.equal(ends[0].ending, ENCODE_EXIT.FAILED);
+  assert.equal(ends[0].code, 255);
+  assert.equal(lines.at(-1)[0], "warn");
+});
+
+test("our own kill is abnormal too, and carries the reason we gave", () => {
+  // Hiding it among the normal endings would make a count of abnormal endings
+  // useless, which is the whole point of counting them.
+  const { run, process, ends } = makeRun();
+  run.start("first");
+  run.stop("moved past 20 segments that are already made");
+  assert.deepEqual(process.signals, ["SIGTERM"]);
+  process.exitWith(null, "SIGTERM");
+  assert.equal(ends[0].ending, ENCODE_EXIT.STOPPED);
+  assert.equal(ends[0].normal, false);
+  assert.match(ends[0].because, /already made/);
+});
+
+test("an ending reports the stretch, how far it got and how long it lived", () => {
+  const { run, process, ends } = makeRun({ from: 10, to: 14 });
+  run.start("first");
+  run.noteProduced(10);
+  process.exitWith(1, null);
+  const ended = ends[0];
+  assert.equal(ended.from, 10);
+  assert.equal(ended.to, 14);
+  assert.equal(ended.reached, 10);
+  assert.equal(ended.livedMs, 0, "the clock is injected, so this is exact");
+  assert.equal(ended.address.includes("enc:854x480"), true);
+});
+
+test("a process that could not be started ends like any other failure", () => {
+  const { run, process, ends } = makeRun();
+  run.start("first");
+  process.emit("error", new Error("ENOENT"));
+  assert.equal(ends[0].ending, ENCODE_EXIT.FAILED);
+  assert.match(ends[0].because, /ENOENT/);
+});
+
+test("only a measured speed is kept", () => {
+  const { run } = makeRun();
+  assert.equal(run.speedX, 0, "nothing measured yet");
+  run.noteSpeed(0);
+  assert.equal(run.speedX, 0);
+  run.noteSpeed(2.5);
+  assert.equal(run.speedX, 2.5);
+});
+
+test("a segment number behind its own start is not its to claim", () => {
+  const { run } = makeRun({ from: 10, to: 14 });
+  run.noteProduced(4);
+  assert.deepEqual(run.produced, []);
+});

package/test/encoder-kinds.test.js

@@ -0,0 +1,122 @@
+/**
+ * @file What every encoder kind must state about itself, and the properties of
+ * its arguments that a field failure paid for.
+ *
+ * Deliberately NOT a transcription of the argument lists: a test written by
+ * copying the code cannot fail when the code is wrong. What is stated here is
+ * what must hold for ANY kind, including one added later, plus the two
+ * kind-specific facts that were learned by running the thing on real hardware.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Encoder } from "../services/encode/Encoder.js";
+import { NvencEncoder } from "../services/encode/NvencEncoder.js";
+import { QsvEncoder } from "../services/encode/QsvEncoder.js";
+import { SoftwareEncoder } from "../services/encode/SoftwareEncoder.js";
+import { V4l2m2mEncoder } from "../services/encode/V4l2m2mEncoder.js";
+import { VaapiEncoder } from "../services/encode/VaapiEncoder.js";
+
+const KINDS = [
+  new SoftwareEncoder(),
+  new VaapiEncoder("/dev/dri/renderD128"),
+  new QsvEncoder("/dev/dri/renderD128"),
+  new NvencEncoder(),
+  new V4l2m2mEncoder()
+];
+
+const BASE = { targetWidth: 1280, targetHeight: 720, segmentDurationSec: 4, fps: 24 };
+
+test("a kind's arguments name the encoder the kind claims to be", () => {
+  // The one thing that must never drift: a class called `h264_nvenc` that puts
+  // `libx264` on the command line would be filed under an address promising
+  // the other one's header.
+  for (const encoder of KINDS) {
+    const args = encoder.buildVideoArgs(BASE);
+    const at = args.indexOf("-c:v");
+    assert.notEqual(at, -1, `${encoder.name} names no video encoder`);
+    assert.equal(args[at + 1], encoder.name, `${encoder.name} builds ${args[at + 1]}`);
+  }
+});
+
+test("an explicit cut list is passed through exactly, by every kind", () => {
+  // This is what makes a re-encoded step splice into a copied picture: it has
+  // to be cut at the source's own keyframe times and nowhere else. A kind that
+  // rounded them, or dropped them for its own even grid, would produce segments
+  // that cannot stand where the copy's would.
+  const times = [0, 4.271, 8.9, 13.04];
+  for (const encoder of KINDS) {
+    const args = encoder.buildVideoArgs({ ...BASE, forcedKeyframeTimes: times });
+    const at = args.indexOf("-force_key_frames");
+    assert.notEqual(at, -1, `${encoder.name} forces no keyframes`);
+    assert.equal(args[at + 1], times.join(","), `${encoder.name} altered the cut list`);
+  }
+});
+
+test("with no cut list, keyframes are still placed on the segment grid", () => {
+  for (const encoder of KINDS) {
+    const args = encoder.buildVideoArgs({ ...BASE, forcedKeyframeTimes: null });
+    const joined = args.join(" ");
+    // Either forced by time, or by a frame-count GOP — both put a keyframe on
+    // every boundary, which is what makes a segment independently decodable.
+    const byTime = joined.includes("-force_key_frames expr:gte(t,n_forced*4)");
+    const byFrameCount = joined.includes(`-g ${4 * 24}`);
+    assert.ok(byTime || byFrameCount, `${encoder.name} places keyframes by neither rule`);
+  }
+});
+
+test("a target box of nothing still produces a usable size", () => {
+  // The session manager passes 0 for "keep the source size"; a kind that let
+  // that through would build `scale=0:0`.
+  for (const encoder of KINDS) {
+    const args = encoder.buildVideoArgs({ ...BASE, targetWidth: 0, targetHeight: 0 });
+    assert.ok(!args.join(" ").includes("=0:"), `${encoder.name} scaled to zero`);
+  }
+});
+
+test("every kind says what its speed setting is, or that it has none", () => {
+  for (const encoder of KINDS) {
+    const ladder = encoder.speedLadder;
+    assert.equal(typeof ladder.note, "string");
+    assert.ok(ladder.note.length > 0, `${encoder.name} explains nothing about its ladder`);
+    assert.ok(Array.isArray(ladder.values));
+    if (ladder.values.length > 0) {
+      assert.ok(ladder.flag.length > 0, `${encoder.name} lists settings but names no option`);
+    }
+  }
+});
+
+test("only libx264 claims a measured ladder", () => {
+  // The four hardware kinds have never been benchmarked across their settings,
+  // and a ladder claiming to be measured is what would let something start
+  // choosing from it.
+  for (const encoder of KINDS) {
+    assert.equal(
+      encoder.speedLadder.measured,
+      encoder.kind === "software",
+      `${encoder.name} misreports whether its ladder was measured`
+    );
+  }
+});
+
+test("a kind that is not software is hardware, and says so", () => {
+  for (const encoder of KINDS) {
+    assert.equal(encoder.isHardware, encoder.kind !== "software");
+  }
+});
+
+test("the encoder on an ARM board always asks for more capture buffers", () => {
+  // The default of four deadlocks on the CM4 — "All capture buffers returned to
+  // userspace" — so this is not a tuning choice but the condition under which
+  // that encoder runs at all.
+  const args = new V4l2m2mEncoder().buildVideoArgs(BASE);
+  const at = args.indexOf("-num_capture_buffers");
+  assert.notEqual(at, -1, "v4l2m2m was given the default buffer count");
+  assert.ok(Number(args[at + 1]) > 4);
+});
+
+test("a kind that does not say how to build its arguments refuses rather than producing none", () => {
+  class Unstated extends Encoder {}
+  const encoder = new Unstated({ name: "h264_unstated", kind: "nvenc" });
+  assert.throws(() => encoder.buildVideoArgs(BASE), /does not say how/);
+});

package/test/held-request-width.test.js

@@ -11,6 +11,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { Timeline } from "../services/output/Timeline.js";
 import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -34,13 +35,18 @@ async function managerWithSession() {
   manager.sessionsById.set(SESSION_ID, {
     id: SESSION_ID,
     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: 201 }, (_, index) => index * SEGMENT_SECONDS),
+      cutGrid: "uniform"
+    }),
     state: "ready",
     segmentFormat: fmp4Format,
-    segmentBoundaries: Array.from({ length: 201 }, (_, index) => index * SEGMENT_SECONDS),
     segmentCount: 200,
     useSyntheticPlaylist: true,
     // The viewer is at segment #25.
-    viewerPositionSeconds: 100
+    furthestViewerSeconds: 100
   });
   return { manager, dirPath };
 }
@@ -107,7 +113,7 @@ test("a seek by one viewer does not release the request held for another", async
   // The shared field now holds the leader's position, which is what the
   // encoder is steered by and what every earlier release judged BOTH of them
   // against.
-  assert.equal(session.viewerPositionSeconds, 600);
+  assert.equal(session.furthestViewerSeconds, 600);
 
   assert.equal(
     manager.requestStillWanted(SESSION_ID, segment(26), "behind"),