@torrent-tv/proxy 2.33.0 → 2.34.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.34.0
+
+- **New**: The proxy tells the browser the smallest buffer at which no interruption reaches the viewer, measured on the file being watched. It is one whole segment — the one being played — plus the worst wait its own reader met before the buffer could refill, from that file's recent interruptions on that swarm. On the field torrent of 2026-08-17 that is 7-9 s, where the browser has been waiting for a hand-chosen 25: sixteen seconds of spinner that nothing had shown to be necessary. Null until the reader has seen two interruptions — one wait shows no interval, and an interval invented from one point is what this work exists to remove — and the browser keeps its own figure until then. The reader measures it, the session manager states it with its own segment length, and the progress reply carries it.
+- **Chore**: Removed `services/torrent-worker/supply-interruptions.js`, a second copy of the same arithmetic that was wired to nothing.
+
 ## 2.33.0
 
 - **New**: A quality step is judged on the machine it will actually run on. The encoder benchmark measures a QUIET host — one ffmpeg and nothing else — while the addon host was measured 99 % busy, and a step predicted at 1.83x ran at 1.01-1.12x (2026-08-17). The offer now multiplies each prediction by the share of the machine that is free, taken from the same `host-load` reading that is already printed every five seconds. What is subtracted is ONLY the work nobody has been charged for — the kernel, the container, whatever else the owner runs — because our own encoders are already priced by the concurrency arithmetic and the proxy's own work per megabyte moved. Charging those here as well is what shipped in 2.21.0 and emptied the quality menu down to a single copied height. On the field reading the correction is about 0.77, and the "not offering" line now says what the machine had to spare when it decided.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.33.0",
+  "version": "2.34.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

@@ -21,6 +21,7 @@ import { readKeyframeIndex } from "./container-index/index.js";
 import { readMachineState, readProcessCpuSeconds, readProxyCpuSeconds, readSystemCpu, shareOfMachine } from "./host-load.js";
 import { speedFromReadings } from "./encoder-readings.js";
 import { availableShareFrom, correctForAvailability } from "./available-share.js";
+import { minimumBufferFrom } from "./supply-margin.js";
 import {
   ENCODE_RUN_EVENT,
   ENCODE_RUN_STATE,
@@ -3368,6 +3369,12 @@ export class HlsSessionManager {
     if (!stats) {
       return "unknown";
     }
+    // What this file's own interruptions demand, measured by the reader. Kept
+    // on the session because the browser is told the buffer that follows from
+    // it, and because the quality offer will be held to the speed it names.
+    if (stats.supply) {
+      session.supplyFigures = stats.supply;
+    }
     // A fully (or almost fully) downloaded file cannot be download-bound.
     if (typeof stats.fileProgress === "number" && stats.fileProgress >= 0.999) {
       return "cpu";
@@ -7589,6 +7596,17 @@ export class HlsSessionManager {
       // the browser tracks its sessions by the id it was given.
       sessionId: named.id,
       state: wireState(session.runState),
+      // The smallest buffer at which no interruption reaches the viewer, from
+      // THIS file's own recent interruptions: one whole segment — the one being
+      // played — plus the worst wait that can arrive before the buffer refills.
+      // On the field torrent that is 7-9 s where the browser waits for a
+      // hand-chosen 25, which is sixteen seconds of staring at a spinner that
+      // nothing had shown to be necessary. Null until the reader has seen two
+      // interruptions; the browser keeps its own figure until then.
+      minimumBufferSeconds: minimumBufferFrom({
+        segmentSeconds: this.segmentDurationSec,
+        worstSupplyWaitSec: session.supplyFigures?.worstWaitSec
+      })?.seconds ?? null,
       processedSeconds: session.progress.processedSeconds,
       startPositionSeconds: session.progress.startPositionSeconds ?? 0,
       totalSeconds: session.progress.totalSeconds,

package/services/torrent-worker/piece-reader.js

@@ -340,6 +340,39 @@ const supplyReportedAt = new Map();
  * @param {number} waitedMs
  * @returns {void}
  */
+/**
+ * What this file's recent interruptions demand, for a caller that has to decide
+ * something with them.
+ *
+ * Exported because the figures are measured HERE — the reader is the only place
+ * that knows how long it waited — while the decisions they feed are made
+ * elsewhere: the smallest buffer that hides an interruption goes to the browser,
+ * and the speed a step must sustain goes to the quality offer.
+ *
+ * @param {string} infoHash
+ * @param {string} fileName
+ * @param {number} segmentSeconds - The session's own segment duration.
+ * @returns {{ requiredSpeed: number, worstWaitSec: number, medianIntervalSec: number, samples: number, minimumBufferSec: number } | null}
+ */
+export function supplyFiguresFor(infoHash, fileName, segmentSeconds) {
+  const history = supplyWaits.get(`${infoHash ?? "?"}/${fileName ?? "?"}`);
+  const demand = requiredSpeedFrom(history ?? []);
+  if (!demand) {
+    return null;
+  }
+  const buffer = minimumBufferFrom({
+    segmentSeconds,
+    worstSupplyWaitSec: demand.worstWaitSec
+  });
+  return {
+    requiredSpeed: demand.requiredSpeed,
+    worstWaitSec: demand.worstWaitSec,
+    medianIntervalSec: demand.medianIntervalSec,
+    samples: demand.samples,
+    minimumBufferSec: buffer ? buffer.seconds : null
+  };
+}
+
 function noteSupplyWait(key, label, waitedMs) {
   const history = supplyWaits.get(key) ?? [];
   history.push({ waitedMs, at: Date.now() });

package/services/torrent-worker/worker.js

@@ -26,7 +26,7 @@ import "./install-webrtc-shim.js";
 import { parentPort, workerData } from "node:worker_threads";
 import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
-import { readFragments } from "./piece-reader.js";
+import { readFragments, supplyFiguresFor } from "./piece-reader.js";
 import { Command, Event } from "./protocol.js";
 
 // Imported dynamically, and that is load-bearing: static imports are RESOLVED
@@ -358,9 +358,20 @@ async function runCommand(command, params, id) {
 
     case Command.FILE_STATS: {
       const torrent = await requireTorrent(params.sourceKey);
-      return pool.getFileStats(torrent, params.fileIndex, {
+      const stats = pool.getFileStats(torrent, params.fileIndex, {
         resumeAnchorByteStart: params.resumeAnchorByteStart ?? null
       });
+      // What this file's own interruptions demand, measured by the reader in
+      // this thread. It travels with the stats because the caller asking for
+      // them is the one that has to decide with them — the browser's smallest
+      // safe buffer, and the speed a quality step must sustain. Null until a
+      // second interruption has been seen: one wait shows no interval, and an
+      // interval invented from one point is exactly what this work removes.
+      const file = Array.isArray(torrent?.files) ? torrent.files[params.fileIndex] : null;
+      return {
+        ...stats,
+        supply: supplyFiguresFor(torrent?.infoHash, file?.name, params.segmentSeconds ?? 4)
+      };
     }
 
     case Command.PRIORITIZE: {

package/services/torrent-worker/supply-interruptions.js

@@ -1,155 +0,0 @@
-/**
- * @file What the supply's own interruptions require of a quality step, and of
- * the buffer in front of the viewer.
- *
- * Both figures are chosen by hand today — a speed margin of 1.5 and a 25-second
- * prebuffer — and both stand for a quantity that is measured every few seconds
- * anyway: how long a read waits for a piece, and how often that happens.
- *
- * The arithmetic, from the measurements of 2026-08-17:
- *
- *   A step producing at speed `v` gains `v - 1` seconds of cushion per second
- *   of playback. An interruption of `W` seconds costs `W`. So a step survives
- *   its own supply exactly when it can rebuild what one interruption takes
- *   before the next one arrives:
- *
- *       (v - 1) × T > W   ⇔   v > 1 + W / T
- *
- *   On the field torrent that day: waits of 1.49 s median, 3.16 s worst, one
- *   every 2.22 s → a required speed of 1.67 against the 1.5 chosen by hand, and
- *   against 1.05 actually measured, which is why it stalled. A copy running at
- *   8x gains 15.5 s between interruptions against 1.5-4.8 s lost, which is the
- *   same formula explaining why a copy never stalls.
- *
- *   The buffer follows from the same numbers: it must hold the segment being
- *   played, whole, plus the worst interruption that can arrive before it can be
- *   refilled — whichever source that interruption comes from.
- *
- *       B_min = segment duration + max(W_supply, D_production, T_transfer)
- *
- *   7-9 s on that torrent, against the 25 s in the browser today.
- *
- * Every term is measured, none is chosen, and the figures rise by themselves
- * when a session's interruptions grow — which is what makes lowering the buffer
- * safe. Pure: no torrent, no clock of its own, no state beyond the samples it
- * is given.
- */
-
-/**
- * How many recent interruptions are kept per file. Enough for a median to mean
- * something, short enough that a swarm which has recovered is not judged by how
- * it behaved ten minutes ago.
- */
-const SAMPLE_LIMIT = 24;
-
-/**
- * A reading of one interruption: how long the reader waited, and when.
- *
- * @typedef {object} Interruption
- * @property {number} waitedMs
- * @property {number} at - Epoch milliseconds when the wait ENDED.
- */
-
-/**
- * Add one interruption to a record, keeping only the recent ones.
- *
- * @param {Interruption[]} samples - Existing readings, oldest first.
- * @param {Interruption} interruption
- * @returns {Interruption[]} A new array; the input is not modified.
- */
-export function withInterruption(samples, interruption) {
-  const kept = Array.isArray(samples) ? samples : [];
-  if (!Number.isFinite(interruption?.waitedMs) || !Number.isFinite(interruption?.at)) {
-    return kept;
-  }
-  const next = [...kept, { waitedMs: Math.max(0, interruption.waitedMs), at: interruption.at }];
-  return next.length > SAMPLE_LIMIT ? next.slice(next.length - SAMPLE_LIMIT) : next;
-}
-
-/**
- * @param {number[]} values
- * @returns {number}
- */
-function median(values) {
-  if (values.length === 0) {
-    return 0;
-  }
-  const sorted = [...values].sort((left, right) => left - right);
-  return sorted[Math.floor(sorted.length / 2)];
-}
-
-/**
- * What the recent interruptions amount to.
- *
- * The interval between interruptions is measured between the readings
- * themselves, so a file that is read steadily and rarely blocked reports a long
- * interval and asks little of the step.
- *
- * @param {Interruption[]} samples
- * @returns {{ samples: number, medianWaitSeconds: number, worstWaitSeconds: number, medianGapSeconds: number }}
- */
-export function summariseInterruptions(samples) {
-  const readings = Array.isArray(samples) ? samples : [];
-  if (readings.length === 0) {
-    return { samples: 0, medianWaitSeconds: 0, worstWaitSeconds: 0, medianGapSeconds: 0 };
-  }
-  const waits = readings.map((entry) => entry.waitedMs / 1000);
-  const gaps = [];
-  for (let index = 1; index < readings.length; index += 1) {
-    const gap = (readings[index].at - readings[index - 1].at) / 1000;
-    if (gap > 0) {
-      gaps.push(gap);
-    }
-  }
-  return {
-    samples: readings.length,
-    medianWaitSeconds: median(waits),
-    worstWaitSeconds: Math.max(...waits),
-    medianGapSeconds: median(gaps)
-  };
-}
-
-/**
- * The speed a step must run at to survive this supply, or null when the supply
- * has not interrupted often enough to say.
- *
- * Null is a real answer and must not be replaced by a number: with one reading
- * there is no interval at all, and inventing one is how a margin comes to be
- * chosen by hand again. A caller with no figure keeps whatever it used before
- * and says so.
- *
- * The worst wait is used rather than the median, because a step that only
- * survives the typical interruption stalls on the others — and a stall is what
- * the viewer sees, not an average.
- *
- * @param {{ samples: number, worstWaitSeconds: number, medianGapSeconds: number }} summary
- * @returns {number | null}
- */
-export function requiredSpeedFrom(summary) {
-  if (!summary || summary.samples < 2 || !(summary.medianGapSeconds > 0)) {
-    return null;
-  }
-  return 1 + summary.worstWaitSeconds / summary.medianGapSeconds;
-}
-
-/**
- * The smallest buffer at which no spinner appears: the segment being played,
- * whole, plus the worst interruption that can arrive before it can be refilled.
- *
- * Each term is the worst OBSERVED over a recent window, and a term nobody has
- * measured contributes nothing rather than a guess.
- *
- * @param {{ segmentSeconds: number, supplySeconds?: number, productionSeconds?: number, transferSeconds?: number }} terms
- * @returns {number}
- */
-export function minimumBufferSeconds(terms) {
-  const segment = Number.isFinite(terms?.segmentSeconds) && terms.segmentSeconds > 0
-    ? terms.segmentSeconds
-    : 0;
-  const worst = Math.max(
-    Number.isFinite(terms?.supplySeconds) ? terms.supplySeconds : 0,
-    Number.isFinite(terms?.productionSeconds) ? terms.productionSeconds : 0,
-    Number.isFinite(terms?.transferSeconds) ? terms.transferSeconds : 0
-  );
-  return segment + Math.max(0, worst);
-}

package/test/supply-interruptions.test.js

@@ -1,125 +0,0 @@
-/**
- * @file The speed a step needs, and the buffer a viewer needs, from what the
- * supply actually did.
- *
- * The field numbers these are checked against (2026-08-17, one torrent, one
- * session): waits of 1.49 s median and 3.16 s worst, one every 2.22 s. The
- * margin chosen by hand was 1.5; the arithmetic says 1.67; the step measured
- * 1.05 and stalled.
- */
-
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import {
-  minimumBufferSeconds,
-  requiredSpeedFrom,
-  summariseInterruptions,
-  withInterruption
-} from "../services/torrent-worker/supply-interruptions.js";
-
-/**
- * Interruptions of `waitMs`, one every `gapMs`.
- *
- * @param {number[]} waitsMs
- * @param {number} gapMs
- * @returns {Array<{ waitedMs: number, at: number }>}
- */
-function series(waitsMs, gapMs) {
-  let samples = [];
-  let at = 1_000_000;
-  for (const waitedMs of waitsMs) {
-    samples = withInterruption(samples, { waitedMs, at });
-    at += gapMs;
-  }
-  return samples;
-}
-
-test("the field session's numbers produce the field session's answer", () => {
-  // Waits around 1.49 s with a worst of 3.16 s, one every 2.22 s.
-  const samples = series([1490, 1490, 3160, 1490, 1490], 2220);
-  const summary = summariseInterruptions(samples);
-
-  assert.equal(summary.worstWaitSeconds, 3.16);
-  assert.equal(summary.medianGapSeconds, 2.22);
-
-  const required = requiredSpeedFrom(summary);
-  assert.ok(required !== null);
-  assert.ok(
-    Math.abs(required - 2.42) < 0.01,
-    `1 + 3.16/2.22 = ${required?.toFixed(2)} — the supply asks for it, nobody chose it`
-  );
-});
-
-test("a supply that rarely interrupts asks for almost nothing", () => {
-  // One short wait every couple of minutes: a step barely faster than realtime
-  // rebuilds the cushion long before the next one.
-  const summary = summariseInterruptions(series([200, 200, 200], 120_000));
-  const required = requiredSpeedFrom(summary);
-  assert.ok(required !== null && required < 1.01, `asked ${required}`);
-});
-
-test("a supply that interrupts constantly asks for a great deal", () => {
-  const summary = summariseInterruptions(series([4000, 4000, 4000], 1000));
-  assert.equal(requiredSpeedFrom(summary), 5);
-});
-
-test("too little evidence is answered with nothing, never with a number", () => {
-  // The whole point of deriving the margin is that it stops being invented. One
-  // reading has no interval at all, and a caller must keep what it had.
-  assert.equal(requiredSpeedFrom(summariseInterruptions([])), null);
-  assert.equal(requiredSpeedFrom(summariseInterruptions(series([1000], 0))), null);
-  assert.equal(requiredSpeedFrom(null), null);
-  assert.equal(requiredSpeedFrom({ samples: 9, worstWaitSeconds: 3, medianGapSeconds: 0 }), null);
-});
-
-test("the worst wait decides, not the typical one", () => {
-  // A step that survives the median interruption still stalls on the others,
-  // and a stall is what the viewer sees.
-  const summary = summariseInterruptions(series([100, 100, 5000, 100], 1000));
-  assert.equal(summary.medianWaitSeconds, 0.1);
-  assert.equal(summary.worstWaitSeconds, 5);
-  assert.equal(requiredSpeedFrom(summary), 6);
-});
-
-test("only the recent interruptions are judged", () => {
-  // A swarm that has recovered must not be sentenced by how it behaved ten
-  // minutes ago, so the record is bounded.
-  let samples = series(Array.from({ length: 40 }, () => 9000), 1000);
-  samples = withInterruption(samples, { waitedMs: 10, at: 2_000_000 });
-  assert.ok(samples.length <= 24, `kept ${samples.length}`);
-  assert.equal(samples[samples.length - 1].waitedMs, 10);
-});
-
-test("a reading without a time or a duration is not a reading", () => {
-  const samples = withInterruption([], { waitedMs: Number.NaN, at: 1 });
-  assert.deepEqual(samples, []);
-  assert.deepEqual(withInterruption([], { waitedMs: 100 }), []);
-});
-
-test("the minimum buffer is one segment plus the worst interruption", () => {
-  // The field torrent: 4 s segments, a worst supply wait of 3.16 s, production
-  // gaps within the segment length, transfer measured in milliseconds.
-  const seconds = minimumBufferSeconds({
-    segmentSeconds: 4,
-    supplySeconds: 3.16,
-    productionSeconds: 1.2,
-    transferSeconds: 0.066
-  });
-  assert.ok(Math.abs(seconds - 7.16) < 0.001, `${seconds}s against the 25 s chosen by hand`);
-});
-
-test("whichever source is worst is the one that sizes the buffer", () => {
-  // A step at 1.0x makes production the binding term even on a swarm that never
-  // stalls, which is exactly the case a supply-only figure would miss.
-  assert.equal(
-    minimumBufferSeconds({ segmentSeconds: 4, supplySeconds: 0.2, productionSeconds: 6 }),
-    10
-  );
-});
-
-test("a term nobody measured contributes nothing, not a guess", () => {
-  assert.equal(minimumBufferSeconds({ segmentSeconds: 4 }), 4);
-  assert.equal(minimumBufferSeconds({ segmentSeconds: 4, supplySeconds: Number.NaN }), 4);
-  assert.equal(minimumBufferSeconds({}), 0);
-});