@torrent-tv/proxy 2.77.0 → 2.78.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.78.0
+
+- **Fix**: One authority over the encoders, where there were three. A viewer watching an episode on 2026-09-05 had their picture stop for 125 seconds while the proxy spawned and killed an encoder every 350-700ms, producing nothing. Two decisions were contradicting each other on every pass: the plan commanded a start inside the viewer's window, at #46; `planRunInterval` in the session manager moved that start to #78, because it counted every live run as claiming up to its head plus the look-ahead; and the plan then saw a run at #78 against a window of [27, 57], found no overlap and killed it as "nothing it was given is wanted". Neither coverage nor demand changed between two such passes, so the same start was commanded again, for as long as anybody watched. `planRunInterval` is deleted: where a run starts is the plan's decision and nothing moves it, and how far it may work is read off the one coverage map the plan itself uses.
+- **Fix**: A run is never stopped for standing outside a viewer's window. While a file is being encoded it is encoded whole; a viewer decides the ORDER the work is taken in and, through the machine's budget, how many processes take it — never whether a run may go on living. The stop this replaced was the other half of the contradiction above, and with it went the last two uses of "does this run overlap a window" in the file.
+- **New**: What a viewer needs is a map, and the maps of several viewers merge into one (`services/encode/DemandMap.js`). Three zones per viewer, in seconds of film: what must be ready before they set off so that they never stop, what the machine reaches while they watch that, and the rest of the track. Merging takes the highest priority per second, so film two people want is as urgent as the more urgent of them and is made once. Which viewer asked never reaches the encoders.
+- **Fix**: The size of that first zone is measured rather than chosen. Below realtime an encoder loses `1 - speed` of a second of film for every second played, so over the film in front of a viewer the shortfall is `remaining × (1 - speed)`, and that much has to exist before they start or they meet a stall partway through — at 0.25x on 400 seconds of film, 300 seconds. Above realtime only the allowance this file's own recent interruptions have shown to be necessary is needed. The 120 seconds that used to size this window were `LOOKAHEAD_PAUSE_SECONDS`, the threshold of a suspended encoder, one chosen number answering seven unrelated questions.
+- **Fix**: The look-ahead limiter is gone, with both of its chosen numbers. It suspended a run 120 seconds in front of the viewer and woke it at 60 — deliberately pushing a run past the window the plan was asking about, which is what the plan then killed it for. What remains of it is a reading: how much film is ready in front of the earliest viewer, which commands nothing.
+- **Fix**: A zone's priority reaches the register instead of being dropped on the way. `want()` took only the two ends, so the order the map states was computed and then discarded. It is a property of the window now, and the claimant's name stays the person's, so a viewer who leaves takes all three of their zones with them.
+- **Fix**: The measured encode speed is read from the field that exists. `progress.speedX` appears nowhere in this codebase, so the speed was always zero and the middle zone was never built at all; the reading the budget already trusts is `recentSpeed.speed`.
+
 ## 2.77.0
 
 - **Fix**: A viewer who has just arrived is watching. Presence and position were one field — the segment they last asked for — so a viewer who had asked for nothing counted as absent, and an output all of whose viewers count as absent has every encoder on it stopped. Field 2026-09-05: a soundtrack's encoder was stopped 1.25 s after it started, with nothing produced, so its `init.mp4` was never made; the picture could not be played without it, the browser waited sixty seconds and was told the proxy had sent no video. The viewer could not have rescued themselves — the segment request that would have marked them present needs the `init.mp4` the stopped encoder was going to make. They are now two facts: position is set the moment they arrive, from the position their own request names, and presence is a fact of their connection.

package/package.json

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

package/services/encode/DemandMap.js

@@ -0,0 +1,187 @@
+/**
+ * @file What one viewer needs, what all of them need together, and in what
+ * order the work should be taken.
+ *
+ * The shape, stated by the user 2026-09-05:
+ *
+ * > Usually you make a map for each viewer, then merge the maps, then decide
+ * > the best way of filling it given the encoders available, where they are now
+ * > and how many there are.
+ *
+ * Three questions, and this file answers the first two. The third — the filling
+ * — belongs to whoever holds the encoders, and it is handed the merged map
+ * instead of a list of windows.
+ *
+ * **ONE PRIORITISATION, TWO CONSUMERS.** Downloading and encoding keep
+ * different STATES — made / being made / free for one; downloaded / arriving,
+ * and which peers hold it at what speed, for the other — but they must agree
+ * about what matters first, or the swarm fetches what the encoder will not
+ * reach for another twenty minutes. That agreement is this map.
+ *
+ * **THE UNIT IS SECONDS OF FILM.** A map is a set of stretches with sizes and a
+ * length of its own, so it needs a unit, and seconds are the only one every
+ * term of the arithmetic is already stated in: encode speed is a ratio of
+ * seconds to seconds, the measured allowance below which an interruption
+ * reaches a viewer is seconds, the viewer's position is seconds, the film's
+ * length is seconds. Bytes cannot serve — how many a second costs is not known
+ * when a file is opened and is not constant across it, and a soundtrack in a
+ * file of its own has bytes of its own. Segment numbers cannot serve either:
+ * they exist only once a cut grid is read, and two outputs of one film number
+ * differently.
+ *
+ * **What this file must NOT know**, and the boundary is the point: nothing about
+ * containers, cut grids, pieces or bytes. Turning a stretch of seconds into the
+ * bytes of one track is the container's and the track's business, by whatever
+ * means suit that file — a Cues table, a sample table, or a walk when the file
+ * carries neither, which is the same answer they already give in order to play
+ * it at all. Getting those bytes is the downloader's business; making segments
+ * out of them is the encoder's.
+ */
+
+/**
+ * How urgently a stretch of film is wanted. Higher is sooner.
+ *
+ * @typedef {object} DemandZone
+ * @property {number} from - First second of film, inclusive.
+ * @property {number} to - Last second of film, inclusive.
+ * @property {number} priority - Higher is more urgent. Only the ORDER between
+ *   zones is meaningful; the numbers themselves are not a scale.
+ */
+
+/** Where the viewer stands. Nothing outranks it. */
+const AT_THE_VIEWER = 3;
+
+/** In front of them, within reach while they watch what is already made. */
+const IN_FRONT = 2;
+
+/** The rest of the track: wanted, because the file is encoded whole. */
+const THE_REST = 1;
+
+/**
+ * One viewer's map.
+ *
+ * Three zones, and the two boundaries between them are measured rather than
+ * chosen:
+ *
+ * 1. **what must be ready before they set off, so that they never stop.** While
+ *    they watch, film is consumed at one second per second and produced at
+ *    `encodeSpeedX`. Above realtime the encoder gains on them, and all that is
+ *    needed in front is the measured allowance for unevenness in the swarm and
+ *    in production. Below realtime it LOSES `1 - speed` of a second for every
+ *    second played, so over the film in front of them the shortfall is
+ *    `remaining × (1 - speed)` — at 0.5x on twenty minutes ahead, ten minutes
+ *    must exist before they start, or they meet a stall partway through;
+ * 2. **what the machine reaches while they watch zone 1** — in front of a
+ *    moving viewer, so ahead of the rest, and nobody is waiting for it yet, so
+ *    behind zone 1;
+ * 3. **the rest of the track.**
+ *
+ * @param {object} params
+ * @param {number} params.atSeconds - Where they are watching from.
+ * @param {number} params.durationSeconds - How long the film is.
+ * @param {number} params.allowanceSeconds - The measured depth below which an
+ *   interruption reaches this viewer (`minimumBufferSeconds`).
+ * @param {number} params.encodeSpeedX - Measured encode speed against realtime
+ *   for this track on this machine. Zero or less means nothing has measured it
+ *   yet, and then zone 2 is left out rather than invented.
+ * @returns {DemandZone[]} Ascending, without gaps or overlaps, covering
+ *   everything from where they are to the end of the film.
+ */
+export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, encodeSpeedX }) {
+  const from = Number.isFinite(atSeconds) && atSeconds > 0 ? atSeconds : 0;
+  const end = Number.isFinite(durationSeconds) ? durationSeconds : 0;
+  if (!(end > from)) {
+    return [];
+  }
+  const remaining = end - from;
+  const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0 ? allowanceSeconds : 0;
+  const speed = Number.isFinite(encodeSpeedX) && encodeSpeedX > 0 ? encodeSpeedX : 0;
+  const shortfall = speed > 0 && speed < 1 ? remaining * (1 - speed) : 0;
+
+  /** @type {DemandZone[]} */
+  const zones = [];
+  const readyBy = Math.min(end, from + allowance + shortfall);
+  zones.push({ from, to: readyBy, priority: AT_THE_VIEWER });
+
+  if (readyBy < end && speed > 0) {
+    // While they watch what zone 1 holds, the encoder makes `speed` times that
+    // much. Beyond it nobody is waiting yet.
+    const reach = Math.min(end, readyBy + (readyBy - from) * speed);
+    if (reach > readyBy) {
+      zones.push({ from: readyBy, to: reach, priority: IN_FRONT });
+    }
+  }
+
+  const covered = zones[zones.length - 1].to;
+  if (covered < end) {
+    zones.push({ from: covered, to: end, priority: THE_REST });
+  }
+  return zones;
+}
+
+/**
+ * Every viewer's map as one.
+ *
+ * The highest priority per second wins: film two people want is as urgent as
+ * the more urgent of them, and making it once serves both. What comes back has
+ * no overlaps, so the filling can walk it without asking about any individual
+ * viewer — which is the rule this layer exists to keep, that which viewer asked
+ * never reaches the encoders.
+ *
+ * @param {DemandZone[][]} maps
+ * @returns {DemandZone[]} Ascending by position.
+ */
+export function mergeMaps(maps) {
+  /** @type {DemandZone[]} */
+  const all = [];
+  for (const map of maps ?? []) {
+    for (const zone of map ?? []) {
+      if (Number.isFinite(zone?.from) && Number.isFinite(zone?.to) && zone.to > zone.from) {
+        all.push(zone);
+      }
+    }
+  }
+  if (all.length === 0) {
+    return [];
+  }
+  // Walked by BOUNDARIES rather than by second: a film is thousands of them and
+  // this is asked again on every change.
+  const points = [...new Set(all.flatMap((zone) => [zone.from, zone.to]))].sort(
+    (left, right) => left - right
+  );
+  /** @type {DemandZone[]} */
+  const merged = [];
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const from = points[index];
+    const to = points[index + 1];
+    let priority = 0;
+    for (const zone of all) {
+      if (zone.from <= from && to <= zone.to && zone.priority > priority) {
+        priority = zone.priority;
+      }
+    }
+    if (priority <= 0) {
+      continue;
+    }
+    const previous = merged[merged.length - 1];
+    if (previous && previous.priority === priority && previous.to === from) {
+      previous.to = to;
+      continue;
+    }
+    merged.push({ from, to, priority });
+  }
+  return merged;
+}
+
+/**
+ * The merged map in the order the work is taken: most urgent first, and within
+ * one priority the earliest film first — that is where somebody is stopped.
+ *
+ * @param {DemandZone[]} merged
+ * @returns {DemandZone[]}
+ */
+export function inWorkingOrder(merged) {
+  return [...(merged ?? [])].sort(
+    (left, right) => right.priority - left.priority || left.from - right.from
+  );
+}