@torrent-tv/proxy 2.15.3 → 2.16.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.16.0
+
+- **New**: While an encoder runs, one line every five seconds says what the MACHINE is doing: the share of it ffmpeg is getting, the share everything else is taking, the share spent waiting on a disk, the CPU's current clock and its temperature. The budget predicts a rung from benchmarks taken at startup on an idle box, and on 2026-08-15 it predicted 1.83x for a rung that then ran at 0.90-0.999x with nothing else encoding — and no log anywhere could say which of the candidate reasons it was. Now the reading exists: an encoder starved of cores, a machine that has dropped its clock or grown hot, and work around the encode that nobody counted all look different in this line. Linux-only and best effort — a host without `/proc` writes nothing and nothing else changes.
+
 ## 2.15.3
 
 - **Fix**: A magnet whose swarm never answered no longer poisons the film for good. It leaves a torrent with the right infohash and no file list, and WebTorrent then refuses the same film opened from a `.torrent` as a duplicate — so the answer to every later attempt came from the entry that knows nothing: `Proxy playback plan request failed (404): File index was not found in torrent`, reproduced in a browser 2026-08-15, and no reload could clear it because the useless entry outlives them all. A source that carries the metadata now replaces one that lacks it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.15.3",
+  "version": "2.16.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/hls-session-manager.js

@@ -18,6 +18,7 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { logger } from "../utils/logger.js";
 import { readKeyframeIndex } from "./container-index/index.js";
+import { readMachineState, sampleHost, shareOfMachine } from "./host-load.js";
 
 /** Own package version, stamped onto session-start log lines. */
 const PROXY_VERSION = createRequire(import.meta.url)("../package.json").version;
@@ -1193,6 +1194,8 @@ export class HlsSessionManager {
    * @type {Map<string, { costSec: number, version: number }>}
    */
   #observedDecodeCost = new Map();
+  /** The previous reading of the machine, to compare the next one against. */
+  #hostLoadSample = null;
 
   /**
    * @param {HlsSessionManagerOptions} options
@@ -2641,7 +2644,53 @@ export class HlsSessionManager {
     logger.info(`transcode ${session.id} encoder resumed — ${reason} "${session.fileName}"`);
   }
 
+  /**
+   * One line per interval about the MACHINE, while an encoder is running on it.
+   *
+   * The budget predicts a rung from benchmarks taken at startup on an idle box,
+   * and on 2026-08-15 it predicted 1.83x for a rung that ran at 0.90-0.999x
+   * with nothing else encoding. Every candidate explanation is measurable — the
+   * encoder not getting the cores, the machine having dropped its clock or
+   * grown hot, the work around the encode costing more than anyone counted —
+   * and none of them was being measured, so the gap could only be argued about.
+   *
+   * Written only while something is encoding, and only when a reading is
+   * available: on a host without `/proc` this says nothing at all.
+   */
+  async #reportHostLoad() {
+    const encoding = [...this.sessionsById.values()].filter(
+      (session) => session?.ffmpeg != null && !hasChildExited(session.ffmpeg) && session.state !== "disposed"
+    );
+    if (encoding.length === 0) {
+      this.#hostLoadSample = null;
+      return;
+    }
+    // The busiest single encoder is the one worth naming; the system share
+    // below covers everything else the box is doing.
+    const watched = encoding[0];
+    const sample = await sampleHost(watched.ffmpeg?.pid ?? null);
+    const previous = this.#hostLoadSample;
+    this.#hostLoadSample = sample;
+    if (previous === null) {
+      return; // the first reading is only something to compare against
+    }
+    const share = shareOfMachine(previous, sample);
+    if (share === null) {
+      return;
+    }
+    const machine = await readMachineState();
+    const asPercent = (value) => (value === null ? "n/a" : `${Math.round(value * 100)}%`);
+    logger.info(
+      `host-load: ffmpeg=${asPercent(share.processShare)} system=${asPercent(share.systemShare)} ` +
+      `iowait=${asPercent(share.iowaitShare)} cpu=${machine.megahertz === null ? "n/a" : `${machine.megahertz}MHz`} ` +
+      `temp=${machine.celsius === null ? "n/a" : `${machine.celsius}C`} ` +
+      `encoders=${encoding.length} speed=${watched.progress?.speed ?? "n/a"} ` +
+      `over=${share.elapsedSec.toFixed(1)}s`
+    );
+  }
+
   async #enforceRealtimeBudget() {
+    void this.#reportHostLoad();
     if (this.videoEncoder?.kind !== "software") {
       return;
     }

package/services/host-load.js

@@ -0,0 +1,154 @@
+/**
+ * @file What the machine is doing while an encoder runs on it.
+ *
+ * The budget predicts a rung from two benchmarks taken at startup on an idle
+ * machine. On 2026-08-15 it predicted 1.83x for a rung that then ran at
+ * 0.90-0.999x with nothing else encoding, and nothing in any log said why. The
+ * candidates are all measurable and none of them was being measured:
+ *
+ *   - the encoder is not getting the cores (something else is taking them, or
+ *     it is waiting on input);
+ *   - the machine is no longer the machine that was benchmarked, because it has
+ *     dropped its clock or grown hot;
+ *   - the work around the encode — hashing pieces, serving segments — costs
+ *     more than anyone counted.
+ *
+ * Everything here is Linux-specific and best effort: a host without these files
+ * reports nulls and nothing above it changes. The proxy stays
+ * deployment-agnostic (`../CLAUDE.md`).
+ */
+
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+
+/**
+ * Clock ticks per second, the unit `/proc/<pid>/stat` counts CPU time in.
+ * `getconf CLK_TCK` is 100 on every Linux this runs on; spawning a process to
+ * ask would cost more than the measurement.
+ */
+const CLOCK_TICKS_PER_SECOND = 100;
+
+/**
+ * @typedef {object} CpuTotals
+ * @property {number} busySeconds - Everything but idle.
+ * @property {number} idleSeconds
+ * @property {number} iowaitSeconds - Idle because it is waiting for a disk.
+ */
+
+/**
+ * The system's CPU time since boot, from `/proc/stat`.
+ *
+ * @returns {Promise<CpuTotals | null>}
+ */
+export async function readSystemCpu() {
+  try {
+    const text = await readFile("/proc/stat", "utf8");
+    const line = text.split("\n", 1)[0];
+    if (!line.startsWith("cpu ")) {
+      return null;
+    }
+    const fields = line.trim().split(/\s+/).slice(1).map(Number);
+    if (fields.length < 5 || fields.some((value) => !Number.isFinite(value))) {
+      return null;
+    }
+    const [user, nice, system, idle, iowait] = fields;
+    const busyTicks = user + nice + system + fields.slice(5).reduce((sum, value) => sum + value, 0);
+    return {
+      busySeconds: busyTicks / CLOCK_TICKS_PER_SECOND,
+      idleSeconds: idle / CLOCK_TICKS_PER_SECOND,
+      iowaitSeconds: iowait / CLOCK_TICKS_PER_SECOND
+    };
+  } catch {
+    return null; // not Linux, or /proc is not mounted
+  }
+}
+
+/**
+ * The CPU time one process has used, from `/proc/<pid>/stat`.
+ *
+ * The comm field can itself contain spaces and brackets, so the fields are
+ * counted from the LAST `)` rather than by splitting the whole line — the usual
+ * trap with this file.
+ *
+ * @param {number} pid
+ * @returns {Promise<number | null>} Seconds of CPU, or null.
+ */
+export async function readProcessCpuSeconds(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return null;
+  }
+  try {
+    const text = await readFile(`/proc/${pid}/stat`, "utf8");
+    const afterComm = text.slice(text.lastIndexOf(")") + 2).trim().split(/\s+/);
+    // After the comm and state fields, utime is index 11 and stime index 12.
+    const utime = Number(afterComm[11]);
+    const stime = Number(afterComm[12]);
+    if (!Number.isFinite(utime) || !Number.isFinite(stime)) {
+      return null;
+    }
+    return (utime + stime) / CLOCK_TICKS_PER_SECOND;
+  } catch {
+    return null; // the process is gone, or this is not Linux
+  }
+}
+
+/**
+ * Is this still the machine the benchmarks were taken on: its clock and its
+ * temperature.
+ *
+ * @returns {Promise<{ megahertz: number | null, celsius: number | null }>}
+ */
+export async function readMachineState() {
+  const [frequency, temperature] = await Promise.all([
+    readFile("/sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq", "utf8").catch(() => null),
+    readFile("/sys/class/thermal/thermal_zone0/temp", "utf8").catch(() => null)
+  ]);
+  const kilohertz = frequency === null ? Number.NaN : Number(frequency.trim());
+  const milliCelsius = temperature === null ? Number.NaN : Number(temperature.trim());
+  return {
+    megahertz: Number.isFinite(kilohertz) ? Math.round(kilohertz / 1000) : null,
+    celsius: Number.isFinite(milliCelsius) ? Math.round(milliCelsius / 100) / 10 : null
+  };
+}
+
+/**
+ * Turn two readings into the shares of ONE second of wall clock that each part
+ * of the machine spent working. A share is per whole machine: 1.0 means every
+ * core was busy for the whole interval.
+ *
+ * @param {{ takenAt: number, processCpuSeconds: number | null, system: CpuTotals | null }} before
+ * @param {{ takenAt: number, processCpuSeconds: number | null, system: CpuTotals | null }} after
+ * @param {number} [cores=os.cpus().length]
+ * @returns {{ elapsedSec: number, processShare: number | null, systemShare: number | null, iowaitShare: number | null } | null}
+ */
+export function shareOfMachine(before, after, cores = os.cpus().length) {
+  const elapsedSec = (after.takenAt - before.takenAt) / 1000;
+  if (!(elapsedSec > 0) || !(cores > 0)) {
+    return null;
+  }
+  const machineSeconds = elapsedSec * cores;
+  const processShare = before.processCpuSeconds !== null && after.processCpuSeconds !== null
+    ? (after.processCpuSeconds - before.processCpuSeconds) / machineSeconds
+    : null;
+  const systemShare = before.system !== null && after.system !== null
+    ? (after.system.busySeconds - before.system.busySeconds) / machineSeconds
+    : null;
+  const iowaitShare = before.system !== null && after.system !== null
+    ? (after.system.iowaitSeconds - before.system.iowaitSeconds) / machineSeconds
+    : null;
+  return { elapsedSec, processShare, systemShare, iowaitShare };
+}
+
+/**
+ * One reading of everything above, to be compared against the next.
+ *
+ * @param {number | null} pid - The encoder's process, when one is running.
+ * @returns {Promise<{ takenAt: number, processCpuSeconds: number | null, system: CpuTotals | null }>}
+ */
+export async function sampleHost(pid) {
+  const [processCpuSeconds, system] = await Promise.all([
+    pid === null ? Promise.resolve(null) : readProcessCpuSeconds(pid),
+    readSystemCpu()
+  ]);
+  return { takenAt: Date.now(), processCpuSeconds, system };
+}

package/test/host-load.test.js

@@ -0,0 +1,68 @@
+/**
+ * @file The arithmetic that turns two readings of the machine into shares.
+ *
+ * The readings themselves are files this host may or may not have; what is
+ * tested here is what is DERIVED from them, because that is where a wrong
+ * number would quietly become a wrong conclusion about why an encoder is slow.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readProcessCpuSeconds, readSystemCpu, sampleHost, shareOfMachine } from "../services/host-load.js";
+
+test("a process using one core of four for a second reports a quarter of the machine", () => {
+  const before = { takenAt: 1_000, processCpuSeconds: 10, system: null };
+  const after = { takenAt: 2_000, processCpuSeconds: 11, system: null };
+  const share = shareOfMachine(before, after, 4);
+  assert.equal(share?.elapsedSec, 1);
+  assert.equal(share?.processShare, 0.25);
+});
+
+test("a process using every core reports the whole machine", () => {
+  const share = shareOfMachine(
+    { takenAt: 0, processCpuSeconds: 0, system: null },
+    { takenAt: 2_000, processCpuSeconds: 8, system: null },
+    4
+  );
+  assert.equal(share?.processShare, 1);
+});
+
+test("waiting for a disk is counted apart from working", () => {
+  const before = { takenAt: 0, processCpuSeconds: null, system: { busySeconds: 100, idleSeconds: 900, iowaitSeconds: 10 } };
+  const after = { takenAt: 1_000, processCpuSeconds: null, system: { busySeconds: 101, idleSeconds: 902, iowaitSeconds: 11 } };
+  const share = shareOfMachine(before, after, 4);
+  assert.equal(share?.systemShare, 0.25);
+  assert.equal(share?.iowaitShare, 0.25);
+});
+
+test("two readings taken at the same instant say nothing rather than dividing by zero", () => {
+  assert.equal(shareOfMachine({ takenAt: 5, processCpuSeconds: 1, system: null }, { takenAt: 5, processCpuSeconds: 2, system: null }, 4), null);
+});
+
+test("a missing reading leaves that share unknown, not zero", () => {
+  const share = shareOfMachine(
+    { takenAt: 0, processCpuSeconds: null, system: null },
+    { takenAt: 1_000, processCpuSeconds: 1, system: null },
+    4
+  );
+  assert.equal(share?.processShare, null);
+  assert.equal(share?.systemShare, null);
+});
+
+test("a process that does not exist reports nothing at all", async () => {
+  assert.equal(await readProcessCpuSeconds(0), null);
+  assert.equal(await readProcessCpuSeconds(-1), null);
+  // A pid far above any real one on this machine.
+  assert.equal(await readProcessCpuSeconds(4_000_000), null);
+});
+
+test("on a host without /proc the readings are null and the sampler still answers", async () => {
+  // This runs on Linux in CI and on Windows here; both must be safe. What is
+  // asserted is the SHAPE — a reading is either a number or null, never a throw.
+  const system = await readSystemCpu();
+  assert.ok(system === null || typeof system.busySeconds === "number");
+  const sample = await sampleHost(null);
+  assert.equal(typeof sample.takenAt, "number");
+  assert.equal(sample.processCpuSeconds, null);
+});