@torrent-tv/proxy 2.80.0 → 2.80.2

package/services/priority/PriorityMap.js

@@ -53,133 +53,89 @@
  *   zones is meaningful; the numbers themselves are not a scale.
  */
 
-/** Where the viewer stands. Nothing outranks it. */
-const AT_THE_VIEWER = 33;
-
-/** In front of them, within reach while they watch what is already made. */
-const IN_FRONT = 32;
-
-/** The rest of the track: wanted, because the file is encoded whole. */
-const THE_REST = 1;
-
 /**
- * How many zones one viewer's map may hold.
- *
- * Below realtime the zones grow geometrically, so their number is the logarithm
- * of the film left over what the viewer holds — five on the addon host's worst
- * measured case, and it grows by one each time the speed halves. The bound is
- * not a policy about how many encoders may run (the machine's budget answers
- * that, and it is far smaller); it stops a speed measured at almost zero from
- * turning a film into thousands of slivers before anything reads the map.
+ * The number a stretch gets when nobody is heading towards it.
+ *
+ * Behind a viewer, and everywhere for a viewer who has stopped the picture: the
+ * film is still wanted — a seek back must be cheap — but nobody is on their way
+ * there, so it yields to everything anybody is approaching.
  */
-const MOST_ZONES = 32;
+export const NOBODY_IS_COMING = 1;
 
 /**
- * One viewer's map, and every boundary in it is measured rather than chosen.
+ * The number the second a viewer is about to watch gets. Everything else ahead
+ * of them counts down from here.
  *
- * The shape depends on one measured number — how fast this machine encodes this
- * track against realtime:
- *
- * - **at or above realtime** the encoder gains on the viewer everywhere, so one
- *   of them holds the whole film. Three zones: the measured allowance in front
- *   of the viewer, what the encoder reaches while they watch it, and the rest;
- * - **below realtime** the encoder loses `1 - speed` of a second for every
- *   second played, so one cannot hold the film and the map says how many can.
- *   An encoder starting at `q` stays ahead of a viewer at `p` for
- *   `(q - p) * s / (1 - s)`, which GROWS with its distance from them — so the
- *   zones grow, each is one encoder's share, and their number is the smallest
- *   that holds this viewer.
- *
- * The last zone is always the rest of the track, wanted because the file is
- * encoded whole and last because nobody is waiting on it.
+ * One scale for every viewer, because the maps are merged by taking the highest
+ * number per second: two viewers must be comparable, and they are, because the
+ * number depends only on how far each of them still has to travel.
+ */
+export const AT_THE_VIEWER = 32;
+
+/**
+ * One viewer's map: seconds of film against a number, and nothing else.
+ *
+ * **The number is a reading of how soon they will be there.** A viewer moving
+ * forward reaches the second `x` after `x - p` seconds of film. That distance —
+ * not a clock time, not a deadline — is what the number is derived from, and it
+ * is why two viewers can be compared at all: the nearer one wins the second
+ * they both want.
+ *
+ * **The bands widen as they go.** Near the viewer the difference between now
+ * and ten seconds away decides what is made first; twenty minutes out, the
+ * difference between twenty and twenty-one changes nothing. So the first band
+ * is the measured allowance — the depth below which an interruption reaches
+ * this viewer — and each next band is twice the last. A film of any length is
+ * then described by a handful of bands, fine where it matters.
+ *
+ * **What must NOT be here**, and the boundary is the point: how fast this
+ * machine encodes, how many encoders that takes, what a second weighs in bytes,
+ * where a piece boundary falls. Those are answers the encoding and the
+ * downloading work out for themselves, from this map and from what each knows
+ * about itself.
  *
  * @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.
+ *   interruption reaches this viewer. The width of the first band.
+ * @param {boolean} [params.playing] - Whether the picture is moving. A viewer
+ *   who has stopped it is going nowhere, so nothing is nearer to them than
+ *   anything else.
+ * @returns {DemandZone[]} Ascending by position, without gaps or overlaps.
  */
-export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, encodeSpeedX }) {
+export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, playing = true }) {
   const from = Number.isFinite(atSeconds) && atSeconds > 0 ? atSeconds : 0;
   const end = Number.isFinite(durationSeconds) ? durationSeconds : 0;
-  if (!(end > from)) {
+  if (!(end > 0)) {
     return [];
   }
   const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0 ? allowanceSeconds : 0;
-  const speed = Number.isFinite(encodeSpeedX) && encodeSpeedX > 0 ? encodeSpeedX : 0;
+  if (!playing || allowance <= 0) {
+    // Nobody is on their way anywhere: the film is wanted and nothing in it is
+    // wanted sooner than the rest.
+    return [{ from: 0, to: end, priority: NOBODY_IS_COMING }];
+  }
 
   /** @type {DemandZone[]} */
   const zones = [];
-
-  // AT OR ABOVE REALTIME ONE ENCODER SUFFICES, whatever the film's length.
-  //
-  // From the condition below with `s >= 1`: the encoder gains on the viewer at
-  // every point, so there is no distance at which they catch it. All that has
-  // to exist in front of them is the allowance this file's own interruptions
-  // have shown to be necessary.
-  if (speed === 0 || speed >= 1) {
-    const readyBy = Math.min(end, from + allowance);
-    zones.push({ from, to: readyBy, priority: AT_THE_VIEWER });
-    if (readyBy < end && speed > 0) {
-      // While they watch what the first zone holds, the encoder makes `speed`
-      // times as much again. Beyond that 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;
-  }
-
-  // BELOW REALTIME THE ZONES GROW, AND EACH IS ONE ENCODER'S SHARE.
-  //
-  // An encoder starting at `q` produces the point `q + y` after `y / s`, and the
-  // viewer reaches it after `q + y - p`. It stays ahead while
-  //
-  //     y <= (q - p) * s / (1 - s)
-  //
-  // so the length one encoder can hold GROWS with its distance from the viewer:
-  // the further off it starts, the later the viewer arrives. Equal shares are
-  // therefore the wrong division, and by a wide margin — on the addon host with
-  // 2400 s of film left, 120 s held and 0.5x, equal shares need twenty encoders
-  // and growing ones need five (120, 240, 480, 960, 1920).
-  //
-  // Each zone is exactly as long as its bound allows, which makes the count the
-  // smallest that can hold this viewer: any zone longer stalls them, and any
-  // shorter leaves the next one starting nearer, where its own bound is tighter.
-  // With nothing held, no partition holds this viewer: the first encoder can
-  // stay ahead for `b * s / (1 - s)`, and that is zero. Saying so plainly beats
-  // slicing the film into equal slivers that pretend otherwise — the whole of
-  // what is left is urgent, and it will still not be enough.
-  if (allowance <= 0) {
-    return [{ from, to: end, priority: AT_THE_VIEWER }];
+  if (from > 0) {
+    zones.push({ from: 0, to: from, priority: NOBODY_IS_COMING });
   }
-  const growth = speed / (1 - speed);
   let at = from;
-  let held = allowance;
+  let width = allowance;
   let priority = AT_THE_VIEWER;
-  while (at < end && zones.length < MOST_ZONES) {
-    const share = held * growth;
-    const to = Math.min(end, at + share);
+  while (at < end && priority > NOBODY_IS_COMING + 1) {
+    const to = Math.min(end, at + width);
     zones.push({ from: at, to, priority });
-    held += to - at;
     at = to;
-    // The next zone is one step less urgent: the viewer meets the one before it
-    // first. One scale for every viewer, or merging two maps would compare
-    // numbers that mean different things.
-    priority = Math.max(THE_REST + 1, priority - 1);
+    width *= 2;
+    priority -= 1;
   }
   if (at < end) {
-    zones.push({ from: at, to: end, priority: THE_REST });
+    // Everything left is equally far off: at this distance one more band would
+    // not change any decision.
+    zones.push({ from: at, to: end, priority: NOBODY_IS_COMING + 1 });
   }
   return zones;
 }

package/services/priority/PriorityOrchestrator.js

@@ -0,0 +1,149 @@
+/**
+ * @file The priority map, built once and handed to everybody who acts on it.
+ *
+ * One map per film, in seconds of film against a number. It is built from where
+ * the viewers are and nothing else, and both of the things that do work — the
+ * encoding and the downloading — read it and decide for themselves. They do not
+ * talk to each other, and neither of them tells this class anything.
+ *
+ * **Why it has to be published rather than asked for.** The downloading lives
+ * in another thread. Until now it took its orders from the reads themselves:
+ * every read declared a window around its own head, so fifteen reads declared
+ * fifteen windows on a piece store that holds sixteen pieces. Half of all
+ * evictions then took a piece a reader had said it wanted, two thirds of reads
+ * came back from disk, and what `/stream` handed out stopped being the file's
+ * bytes — twenty-two source-parse errors, a segment the player could not
+ * append, and an empty picture for six minutes (field 2026-09-05).
+ */
+
+import { mapForViewer, mergeMaps } from "./PriorityMap.js";
+
+export class PriorityOrchestrator {
+  /** Where the map goes once it is built. @type {(published: object) => void} */
+  #publish;
+
+  /** The last map published per film and file, so an unchanged one is not resent. */
+  #last = new Map();
+
+  /** Who is watching one session. @type {(session: object) => Map<string, object>} */
+  #viewersOf;
+
+  /** How wide the first band of one session's file is. @type {(session: object) => number} */
+  #allowanceFor;
+
+  /**
+   * This layer states facts and imports nothing above itself, so what it needs
+   * of a session — who is watching it, and how wide an interruption this file
+   * has shown on this swarm — is passed in.
+   *
+   * @param {object} params
+   * @param {(published: { sourceKey: string, fileIndex: number, durationSeconds: number,
+   *   zones: { from: number, to: number, priority: number }[] }) => void} params.publish
+   * @param {(session: object) => Map<string, object>} [params.viewersOf]
+   * @param {(session: object) => number} [params.allowanceFor]
+   */
+  constructor({ publish, viewersOf, allowanceFor }) {
+    this.#publish = typeof publish === "function" ? publish : () => {};
+    this.#viewersOf = typeof viewersOf === "function" ? viewersOf : () => new Map();
+    this.#allowanceFor = typeof allowanceFor === "function" ? allowanceFor : () => 0;
+  }
+
+  /**
+   * The map for one film, from everyone watching it.
+   *
+   * @param {object} params
+   * @param {string} params.sourceKey
+   * @param {number} params.fileIndex
+   * @param {number} params.durationSeconds
+   * @param {number} params.allowanceSeconds - The measured depth below which an
+   *   interruption reaches a viewer of this file.
+   * @param {{ atSeconds: number, playing: boolean }[]} params.viewers
+   * @returns {{ from: number, to: number, priority: number }[]} Seconds of film
+   *   against a number, merged over everyone.
+   */
+  build({ sourceKey, fileIndex, durationSeconds, allowanceSeconds, viewers }) {
+    const zones = mergeMaps(
+      (viewers ?? []).map((viewer) =>
+        mapForViewer({
+          atSeconds: viewer.atSeconds,
+          durationSeconds,
+          allowanceSeconds,
+          playing: viewer.playing !== false
+        })
+      )
+    );
+    const key = `${sourceKey}:${fileIndex}`;
+    // Unchanged maps are not republished: the downloading rebuilds what it asks
+    // the swarm for on every one, and a viewer sitting still would otherwise
+    // make it do that several times a second.
+    const shape = JSON.stringify(zones);
+    if (this.#last.get(key) !== shape) {
+      this.#last.set(key, shape);
+      this.#publish({ sourceKey, fileIndex, durationSeconds, zones });
+    }
+    return zones;
+  }
+
+  /**
+   * Build and publish the map for every file anybody is watching.
+   *
+   * One map per FILE, not per output: the picture, a quality step and a
+   * soundtrack of one film are three outputs reading the same bytes, and the
+   * swarm is asked for bytes. Viewers of all of them merge into one map.
+   *
+   * @param {object} params
+   * @param {Iterable<object[]>} params.sessionGroups - The live sessions, in
+   *   whatever grouping the caller holds them; they are regrouped by file here.
+   * @param {number} params.staleAfterMs - How long a viewer may be silent and
+   *   still count as watching.
+   * @param {number} [params.now]
+   * @returns {void}
+   */
+  publishFor({ sessionGroups, staleAfterMs, now = Date.now() }) {
+    /** @type {Map<string, { sourceKey: string, fileIndex: number, durationSeconds: number, allowanceSeconds: number, viewers: object[] }>} */
+    const byFile = new Map();
+    for (const sessions of sessionGroups) {
+      for (const session of sessions) {
+        const key = `${session.sourceKey}:${session.fileIndex}`;
+        let held = byFile.get(key);
+        if (!held) {
+          held = {
+            sourceKey: session.sourceKey,
+            fileIndex: session.fileIndex,
+            durationSeconds: Number(session.file?.durationSeconds) || 0,
+            // The first band is as wide as an interruption this file has
+            // actually shown on this swarm, never a chosen number.
+            allowanceSeconds: this.#allowanceFor(session),
+            viewers: []
+          };
+          byFile.set(key, held);
+        }
+        for (const viewer of this.#viewersOf(session).values()) {
+          if (viewer.isPresent(now, staleAfterMs)) {
+            held.viewers.push({
+              atSeconds: viewer.positionSeconds() ?? 0,
+              playing: viewer.playing !== false
+            });
+          }
+        }
+      }
+    }
+    for (const one of byFile.values()) {
+      // A file of unknown length cannot be divided into zones, and a file
+      // nobody is watching has nothing to be urgent about.
+      if (one.durationSeconds > 0 && one.viewers.length > 0) {
+        this.build(one);
+      }
+    }
+  }
+
+  /**
+   * Nobody is watching this file any more.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   */
+  forget(sourceKey, fileIndex) {
+    this.#last.delete(`${sourceKey}:${fileIndex}`);
+  }
+}

package/services/torrent-pool.js

@@ -17,8 +17,12 @@ import { logger } from "../utils/logger.js";
 import { SharedPieceStore, findSharedStore } from "./piece-store/shared-piece-store.js";
 import { Urgency } from "./demand/index.js";
 import { demandFor, forgetTorrent, reconcileAll } from "./download/registry.js";
+import { AT_THE_VIEWER, NOBODY_IS_COMING } from "./priority/PriorityMap.js";
 import { deriveSourceKey } from "./torrent-source-key.js";
 
+/** How a window stated from the priority map names itself. */
+const MAP_CLAIMANT = "priority-map";
+
 // The DHT's entry points. Two of the three the library ships answer nothing —
 // measured 2026-08-21 from the addon host: `router.bittorrent.com` and
 // `router.utorrent.com` did not reply to a hand-written `ping` at all, while a
@@ -992,6 +996,106 @@ export class TorrentPool {
     }
   }
 
+  /**
+   * Take the priority map for one file and state what to fetch from it.
+   *
+   * THE MAP IS THE ONLY SOURCE. What used to state demand here was the reads
+   * themselves: every read declared a window around its own head, so fifteen
+   * reads declared fifteen windows on a piece store that holds sixteen pieces —
+   * half of all evictions then took a piece a reader had said it wanted, two
+   * thirds of reads came back from disk, and the bytes handed out stopped being
+   * the file's (field 2026-09-05).
+   *
+   * Seconds become bytes here, because this is the side that knows how the file
+   * is laid out. The map never learns about bytes and the viewer never appears.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {{ from: number, to: number, priority: number }[]} zones - Seconds of
+   *   film against a number, highest first in urgency.
+   * @param {number} durationSeconds
+   */
+  applyPriorityMap(torrent, fileIndex, zones, durationSeconds) {
+    const file = Array.isArray(torrent?.files) ? torrent.files[fileIndex] : null;
+    const length = Number(file?.length);
+    const duration = Number(durationSeconds);
+    if (!file || !(length > 0) || !(duration > 0) || !Array.isArray(zones)) {
+      return;
+    }
+    const { register } = demandFor(torrent);
+    // Highest number first, so the stretch a viewer reaches soonest is stated
+    // first and the rest fall in behind it.
+    const ordered = [...zones]
+      .filter((zone) => Number.isFinite(zone?.from) && Number.isFinite(zone?.to) && zone.to > zone.from)
+      .sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0));
+    /**
+     * Which level of urgency one zone is stated at, from the map's own number
+     * and nothing else. The map's numbers are a scale as long as the film needs
+     * — ten bands on a fifty-minute film — while the register has five levels,
+     * and the fit is by meaning:
+     *
+     *  - the top of the scale is where a viewer is standing, so it is the
+     *    cushion being built: {@link Urgency.NEAR}. Never BLOCKED — that level
+     *    means a reader is stopped on those bytes right now, which only a read
+     *    can say;
+     *  - the bottom is what nobody is approaching: behind a viewer moving
+     *    forward, and the whole film of a viewer who has stopped the picture.
+     *    Wanted only if somebody seeks back, which is {@link Urgency.BEHIND};
+     *  - one above the bottom is the far tail — wanted for certain if the
+     *    viewer watches on, and not before: {@link Urgency.TAIL};
+     *  - everything between is the lead being built: {@link Urgency.AHEAD}.
+     *
+     * Read from the scale's own ends rather than from the highest and lowest
+     * number in THIS file's map. The two speculative levels are withheld across
+     * every torrent at once while anything urgent is missing anywhere, so a
+     * paused viewer's film has to compare as wanted-last against another film
+     * somebody is watching — and relative to itself alone it would compare as
+     * the most urgent thing there is.
+     *
+     * @param {{ priority?: number }} zone
+     * @returns {number}
+     */
+    const levelOf = (zone) => {
+      const priority = zone.priority ?? 0;
+      if (priority <= NOBODY_IS_COMING) {
+        return Urgency.BEHIND;
+      }
+      if (priority <= NOBODY_IS_COMING + 1) {
+        return Urgency.TAIL;
+      }
+      return priority >= AT_THE_VIEWER ? Urgency.NEAR : Urgency.AHEAD;
+    };
+    ordered.forEach((zone, index) => {
+      // A second of film sits at that fraction of the file. Constant bitrate is
+      // an approximation, and it is the only one available without an index of
+      // the container — near enough to say which stretch matters more, which is
+      // all this decides.
+      const byteStart = Math.max(0, Math.floor((zone.from / duration) * length));
+      const byteEnd = Math.min(length - 1, Math.ceil((zone.to / duration) * length) - 1);
+      if (byteEnd < byteStart) {
+        return;
+      }
+      register.state({
+        claimant: `${MAP_CLAIMANT}:${fileIndex}:${index}`,
+        fileIndex,
+        byteStart,
+        byteEnd,
+        urgency: levelOf(zone)
+      });
+    });
+    // Bands the map no longer has: a viewer moved on, and what they had wanted
+    // is not wanted by anybody now.
+    for (const window of register.windows()) {
+      if (!String(window.claimant).startsWith(`${MAP_CLAIMANT}:${fileIndex}:`)) {
+        continue;
+      }
+      const index = Number(String(window.claimant).split(":").pop());
+      if (!(index < ordered.length)) {
+        register.withdraw(window.claimant);
+      }
+    }
+  }
+
   #reportStalledDownloads() {
     const now = Date.now();
     for (const torrent of this.torrents.values()) {

package/services/torrent-worker/client.js

@@ -432,6 +432,26 @@ export class TorrentWorkerClient {
     });
   }
 
+  /**
+   * Hand the download the priority map for one file.
+   *
+   * Seconds of film against a number, and nothing else: what is wanted and in
+   * what order. Turning that into bytes, into pieces, and into what the swarm
+   * is asked for is the download's own business, and so is what it keeps in
+   * memory.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, durationSeconds: number, zones: { from: number, to: number, priority: number }[] }} params
+   * @returns {Promise<void>}
+   */
+  async setPriorityMap({ sourceKey, fileIndex, zones, durationSeconds }) {
+    await this.#caller.call(Command.PRIORITY_MAP, {
+      sourceKey,
+      fileIndex,
+      zones,
+      durationSeconds
+    });
+  }
+
   /**
    * Pre-fetch the head and tail the codec probe needs.
    *