@torrent-tv/proxy 2.80.12 → 2.80.13

package/services/priority/WaitLedger.js

@@ -0,0 +1,142 @@
+/**
+ * @file How well the priority map is being served, measured where somebody waits.
+ *
+ * The map says what matters most. Nothing said whether what mattered most was
+ * actually delivered first — so "is the prioritisation any good" had no answer
+ * of any kind, for either of the two things that read the map.
+ *
+ * The measure is the same for both, and it is a wait recorded against the rank
+ * the map gave the thing waited for AT THE MOMENT it was asked for. Read that
+ * way it says which part is wrong rather than whether the whole scheme is:
+ *
+ * - long waits at the TOP rank mean the urgent zone is not being served first,
+ *   which is a fault in whoever acts on the map;
+ * - long waits further down with none at the top mean the zones are the wrong
+ *   width — the urgent one too narrow, so the viewer reaches material that was
+ *   only ever ranked "soon";
+ * - a rank with no waits at all is not a good sign or a bad one, it is silence,
+ *   and it is reported as such rather than as a zero.
+ *
+ * There is nothing in here about encoders, torrents, sessions or viewers: it is
+ * given a rank and a number of milliseconds.
+ */
+
+/** How many waits to keep per rank. A median wants a sample, not a history. */
+const HISTORY = 200;
+
+/**
+ * Ranks are collapsed into bands before they are counted.
+ *
+ * The map's ranks are as many as the film needs — 100 down to 1 on a long file
+ * — and a table with a hundred rows says nothing a reader can hold. What is
+ * being asked is coarse: was the thing waited for what the viewer needs NOW,
+ * what they reach shortly, or the rest of the film. So the top rank is its own
+ * band, the next few are the second, and everything below is the third.
+ *
+ * @param {number} rank
+ * @param {number} topRank - The highest rank the map currently states.
+ * @returns {"now" | "soon" | "later"}
+ */
+export function bandOf(rank, topRank) {
+  if (!Number.isFinite(rank) || rank <= 0) {
+    return "later";
+  }
+  const top = Number.isFinite(topRank) && topRank > 0 ? topRank : rank;
+  if (rank >= top) {
+    return "now";
+  }
+  // Within a tenth of the top: what a viewer reaches while watching what they
+  // hold. A tenth is the map's own shape — its zones widen geometrically — and
+  // not a threshold chosen for this table.
+  return rank >= top - Math.max(1, Math.round(top / 10)) ? "soon" : "later";
+}
+
+export class WaitLedger {
+  /** @type {Map<string, Map<string, number[]>>} */
+  #waits = new Map();
+
+  /** @type {Map<string, Map<string, number>>} */
+  #counts = new Map();
+
+  /**
+   * Somebody waited this long for something the map ranked this highly.
+   *
+   * @param {string} key - What the waits belong to: an output, or a file.
+   * @param {number} waitedMs
+   * @param {number} rank - The map's rank for the thing waited for.
+   * @param {number} topRank - The highest rank the map states, so the rank can
+   *   be read as a position rather than as an absolute number.
+   */
+  note(key, waitedMs, rank, topRank) {
+    if (!key || !Number.isFinite(waitedMs) || waitedMs < 0) {
+      return;
+    }
+    const band = bandOf(rank, topRank);
+    let byBand = this.#waits.get(key);
+    if (!byBand) {
+      byBand = new Map();
+      this.#waits.set(key, byBand);
+    }
+    const held = byBand.get(band) ?? [];
+    held.push(waitedMs);
+    while (held.length > HISTORY) {
+      held.shift();
+    }
+    byBand.set(band, held);
+
+    let counts = this.#counts.get(key);
+    if (!counts) {
+      counts = new Map();
+      this.#counts.set(key, counts);
+    }
+    counts.set(band, (counts.get(band) ?? 0) + 1);
+  }
+
+  /**
+   * What the waits say, in one line, or null while nothing has waited.
+   *
+   * The count is the whole run and the median and worst are the recent sample,
+   * because those answer different questions: how often, and how badly.
+   *
+   * @param {string} key
+   * @returns {string | null}
+   */
+  describe(key) {
+    const byBand = this.#waits.get(key);
+    if (!byBand || byBand.size === 0) {
+      return null;
+    }
+    const counts = this.#counts.get(key) ?? new Map();
+    const parts = [];
+    for (const band of ["now", "soon", "later"]) {
+      const held = byBand.get(band);
+      if (!held || held.length === 0) {
+        // Said out loud, because an absent band and a band that never waited
+        // are the same silence and neither is a zero.
+        parts.push(`${band} none`);
+        continue;
+      }
+      const sorted = [...held].sort((a, b) => a - b);
+      const median = sorted[Math.floor(sorted.length / 2)];
+      parts.push(
+        `${band} ${counts.get(band) ?? held.length} wait(s) median ${Math.round(median)}ms ` +
+        `worst ${Math.round(sorted[sorted.length - 1])}ms`
+      );
+    }
+    return parts.join(", ");
+  }
+
+  /**
+   * @param {string} key
+   */
+  forget(key) {
+    this.#waits.delete(key);
+    this.#counts.delete(key);
+  }
+}
+
+/**
+ * One ledger for the process, because the question is asked in two layers and
+ * the answer is comparable only if the scale is the same.
+ */
+export const waits = new WaitLedger();

package/services/torrent-pool.js

@@ -15,7 +15,7 @@ import { rmSync, statfsSync } from "node:fs";
 import WebTorrent from "webtorrent";
 import { logger } from "../utils/logger.js";
 import { SharedPieceStore, findSharedStore } from "./piece-store/shared-piece-store.js";
-import { Urgency } from "./demand/index.js";
+import { Urgency, urgencyName } from "./demand/index.js";
 import { demandFor, forgetTorrent, reconcileAll } from "./download/registry.js";
 import { isAtAWatchingViewer, isBehindEverybody, isNobodyComingNow } from "./priority/PriorityMap.js";
 import { deriveSourceKey } from "./torrent-source-key.js";
@@ -682,6 +682,12 @@ export function dhtNodeCount(client) {
   }
 }
 
+// The last shape said out loud per torrent, so an unchanged one is not
+// repeated. Held here rather than on the pool because `applyPriorityMap`
+// reads nothing but its arguments — which is what lets it be exercised
+// without building a pool, a torrent client or a thread.
+const lastMapSaid = new WeakMap();
+
 export class TorrentPool {
   /**
    * In-flight `client.add()` promises keyed by the same key as `torrents`.
@@ -1099,6 +1105,37 @@ export class TorrentPool {
         register.withdraw(window.claimant);
       }
     }
+    // WHAT THE SWARM WAS ACTUALLY TOLD, said on change and never on a timer.
+    // The map was applied in silence: that it had been BUILT was visible in the
+    // encoding's own line, and that the download had received it was visible
+    // nowhere at all — so "is the map reaching the swarm" could only be taken
+    // on trust. Field 2026-09-08: not one line about it in a whole session.
+    //
+    // Per LEVEL rather than per zone, because the register has five levels and
+    // the map has as many bands as the film needs; the fit between them is the
+    // one thing here that could be wrong, and this is what shows it. Megabytes,
+    // because that is what a swarm delivers.
+    const byLevel = new Map();
+    for (const zone of ordered) {
+      const level = levelOf(zone);
+      const seconds = Math.max(0, zone.to - zone.from);
+      const held = byLevel.get(level) ?? { zones: 0, megabytes: 0 };
+      held.zones += 1;
+      held.megabytes += (seconds / duration) * length / 1048576;
+      byLevel.set(level, held);
+    }
+    const shape = [...byLevel.entries()]
+      .sort((left, right) => right[0] - left[0])
+      .map(([level, held]) => `${urgencyName(level)} ${held.zones} zone(s) ${held.megabytes.toFixed(0)}MB`)
+      .join(", ");
+    const said = `${fileIndex}:${shape}`;
+    if (lastMapSaid.get(torrent) !== said) {
+      lastMapSaid.set(torrent, said);
+      logger.info(
+        `torrent-pool: the swarm is told, for "${file.name}": ${shape || "nothing"} ` +
+        `(${ordered.length} band(s) of the map, over ${Math.round(duration)}s of film)`
+      );
+    }
   }
 
   #reportStalledDownloads() {

package/services/torrent-worker/client.js

@@ -228,12 +228,7 @@ export class TorrentWorkerClient {
       // Fail everything outstanding rather than leaving callers hanging: a dead
       // worker will never answer, and a stalled request is worse than an error
       // the loading flow can retry.
-      const reason = new Error("Torrent worker stopped unexpectedly.");
-      this.#caller.rejectAll(reason);
-      for (const [, read] of this.#reads) {
-        read.fail(reason);
-      }
-      this.#reads.clear();
+      this.#failEverythingOutstanding(new Error("Torrent worker stopped unexpectedly."));
     });
 
     // A worker that ENDS was, until now, not noticed at all: only `message` and
@@ -252,15 +247,35 @@ export class TorrentWorkerClient {
         `torrent-worker: thread ended on its own with code ${code} — nobody asked it to. ` +
         "Everything waiting on it is failed; the proxy has no torrent client until it is rebuilt."
       );
-      const reason = new Error("Torrent worker ended unexpectedly.");
-      this.#caller.rejectAll(reason);
-      for (const [, read] of this.#reads) {
-        read.fail(reason);
-      }
-      this.#reads.clear();
+      this.#failEverythingOutstanding(new Error("Torrent worker ended unexpectedly."));
     });
   }
 
+  /**
+   * A dead thread will never answer, so everything waiting on it is failed.
+   *
+   * INCLUDING THE FRAGMENT READS, which is what ffmpeg's input is. Both death
+   * handlers walked `#reads` alone and left `#fragmentReaders` untouched, so an
+   * encoder's input neither ended nor errored — it went quiet. Field 2026-08-31,
+   * three times: the thread died, both ffmpeg runs stayed ALIVE and stopped
+   * producing (167 `holding segment-00085.mp4 … encoder alive` lines), the
+   * browser drained its cushion and then retried a segment that would never
+   * exist, for ever, with nothing shown to the viewer.
+   *
+   * @param {Error} reason
+   */
+  #failEverythingOutstanding(reason) {
+    this.#caller.rejectAll(reason);
+    for (const [, read] of this.#reads) {
+      read.fail(reason);
+    }
+    this.#reads.clear();
+    for (const [, reader] of this.#fragmentReaders) {
+      reader.fail(reason);
+    }
+    this.#fragmentReaders.clear();
+  }
+
   /**
    * Add (or join) a torrent and register it under `sourceKey`.
    *

package/test/wait-ledger.test.js

@@ -0,0 +1,100 @@
+/**
+ * @file Whether the priority map is being served in its own order.
+ *
+ * The map says what matters most. Until 2026-09-08 nothing said whether what
+ * mattered most was delivered first, for either of the two things that read it
+ * — so a map read backwards would have looked identical in every log line the
+ * proxy writes.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { bandOf, WaitLedger } from "../services/priority/WaitLedger.js";
+import { SegmentDemand } from "../services/encode/SegmentDemand.js";
+
+test("the top rank is its own band, and the rest fall behind it", () => {
+  // The map's ranks are as many as the film needs, and a table with a hundred
+  // rows says nothing a reader can hold. What is being asked is coarse.
+  assert.equal(bandOf(100, 100), "now", "where the viewer is standing");
+  assert.equal(bandOf(95, 100), "soon", "what they reach while watching what they hold");
+  assert.equal(bandOf(50, 100), "later", "the rest of the film");
+  assert.equal(bandOf(0, 100), "later", "in nobody's zone at all");
+});
+
+test("a short map has a top band too", () => {
+  // A film with three bands must not report every wait as `later` because its
+  // numbers are small: a rank is a position in THIS map, not an absolute.
+  assert.equal(bandOf(3, 3), "now");
+  assert.equal(bandOf(1, 3), "later");
+});
+
+test("a band that never waited is said out loud, not reported as zero", () => {
+  const ledger = new WaitLedger();
+  ledger.note("out:1080", 40, 100, 100);
+
+  const said = ledger.describe("out:1080");
+  assert.match(said, /now 1 wait\(s\) median 40ms worst 40ms/);
+  assert.match(said, /soon none/, "silence is not a zero");
+  assert.match(said, /later none/);
+});
+
+test("nothing waited at all reads as nothing, so it cannot be mistaken for good", () => {
+  assert.equal(new WaitLedger().describe("out:1080"), null);
+});
+
+test("the count is the whole run and the median is the recent sample", () => {
+  // Two different questions: how often, and how badly.
+  const ledger = new WaitLedger();
+  for (let n = 0; n < 300; n += 1) {
+    ledger.note("out:1080", n, 100, 100);
+  }
+
+  const said = ledger.describe("out:1080");
+  assert.match(said, /now 300 wait\(s\)/, "every wait is counted");
+  assert.match(said, /worst 299ms/, "and the worst of what is still held");
+});
+
+test("waits of two outputs do not mix", () => {
+  const ledger = new WaitLedger();
+  ledger.note("out:1080", 5000, 100, 100);
+  ledger.note("out:480", 10, 100, 100);
+
+  assert.match(ledger.describe("out:1080"), /now 1 wait\(s\) median 5000ms/);
+  assert.match(ledger.describe("out:480"), /now 1 wait\(s\) median 10ms/);
+});
+
+test("the map answers what it says about one segment, and about itself", () => {
+  // The rank alone cannot be read: a wait means one thing at the top of a map
+  // and another at the bottom, so the highest rank stated comes with it.
+  const demand = new SegmentDemand();
+  demand.state("out:1080", [
+    { from: 10, to: 12, priority: 100, withinSeconds: 0 },
+    { from: 13, to: 20, priority: 97, withinSeconds: 4 },
+    { from: 21, to: 90, priority: 90, withinSeconds: 40 }
+  ]);
+
+  assert.deepEqual(demand.rankOf("out:1080", 11), { rank: 100, topRank: 100 });
+  assert.deepEqual(demand.rankOf("out:1080", 15), { rank: 97, topRank: 100 });
+  assert.deepEqual(
+    demand.rankOf("out:1080", 500),
+    { rank: 0, topRank: 100 },
+    "in nobody's zone is a statement: nothing is coming for it"
+  );
+  assert.deepEqual(
+    demand.rankOf("out:none", 11),
+    { rank: 0, topRank: 0 },
+    "and a map that has not been built says nothing at all, which is different"
+  );
+});
+
+test("overlapping zones give a segment the highest rank that covers it", () => {
+  // Two viewers a few seconds apart state stretches that overlap; the segment
+  // is as urgent as the most urgent claim on it.
+  const demand = new SegmentDemand();
+  demand.state("out:1080", [
+    { from: 0, to: 100, priority: 90, withinSeconds: 40 },
+    { from: 10, to: 12, priority: 100, withinSeconds: 0 }
+  ]);
+
+  assert.equal(demand.rankOf("out:1080", 11).rank, 100);
+});