@torrent-tv/proxy 2.80.5 → 2.80.6

package/services/priority/PriorityMap.js

@@ -44,165 +44,319 @@
  */
 
 /**
- * How urgently a stretch of film is wanted. Higher is sooner.
+ * THE MAP ITSELF: one number per second of film.
+ *
+ * Literally an array as long as the film, where the value at second `x` says how
+ * urgently that second is wanted. Stated by the user 2026-09-06, and it replaced
+ * a list of stretches each carrying two numbers.
+ *
+ * Two arrays rather than one, because two different questions are asked of the
+ * map and only one of them can be answered by a rank:
+ *
+ * - `priority` orders the work. Only the ORDER between values is meaningful;
+ *   the scale below says what the numbers separate;
+ * - `secondsUntilPlayed` is a quantity, and it is what makes lateness
+ *   computable at all: whoever fills the map compares "when is this needed"
+ *   against "when would it arrive", and only the second half is theirs to work
+ *   out. `Infinity` where nobody is on their way.
+ *
+ * @typedef {object} PriorityMap
+ * @property {number} durationSeconds - The film's length, in whole seconds.
+ * @property {Uint8Array} priority - One entry per second. Zero means nothing is
+ *   wanted there, which happens only where nobody is watching at all.
+ * @property {Float64Array} secondsUntilPlayed - One entry per second.
+ * @property {Uint8Array} behind - One entry per second, 1 where the second lies
+ *   behind EVERY viewer. Stated rather than worked out from the other two,
+ *   because working it out means knowing this file's scale, and the consumers
+ *   are in other layers. Inferred from the absence of a time, as it was, it was
+ *   wrong for a stopped viewer: their whole film carries no time, so the film in
+ *   front of them counted as behind them and the encoders wandered to the start
+ *   of the file.
+ */
+
+/**
+ * A stretch of the map with one value throughout — the same facts said as a
+ * range instead of as a run of equal entries.
  *
  * @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.
+ * @property {number} from - First second, inclusive.
+ * @property {number} to - Last second, exclusive.
+ * @property {number} priority
+ * @property {number} withinSeconds
+ * @property {boolean} behind - Whether this lies behind every viewer.
  */
 
 /**
- * The number a stretch gets when nobody is heading towards it.
+ * THE SCALE. Three bands, and the order between them is the whole of what the
+ * numbers claim.
+ *
+ * 1. IN FRONT OF SOMEBODY WHO IS WATCHING — the top value at the second they
+ *    are about to see, falling as the film gets further from them;
+ * 2. IN FRONT OF SOMEBODY WHO HAS STOPPED — the same shape, and every value of
+ *    it below every value of band 1. A stopped viewer will watch this film when
+ *    they press play, so it is still in front of them; nobody is waiting for it
+ *    now, so it yields to anybody who is;
+ * 3. BEHIND EVERYBODY — reachable only by a seek back, and nothing measures how
+ *    likely that is, so it is one value rather than a shape.
  *
- * 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.
+ * IN FRONT ALWAYS OUTRANKS BEHIND, at any distance and whoever is stopped. The
+ * bands make that true by construction rather than by a comparison somebody has
+ * to remember to write.
+ *
+ * The values inside a band are AN ENCODING OF AN ORDER, not a measurement:
+ * every consumer asks only which of two seconds comes first, so any strictly
+ * decreasing shape does the same work, and none of these numbers claims
+ * anything about the world.
  */
+export const AT_A_WATCHING_VIEWER = 100;
+const WATCHING_FLOOR = 70;
+const AT_A_STOPPED_VIEWER = 69;
+const STOPPED_FLOOR = 39;
+
+/** Behind everybody. */
 export const NOBODY_IS_COMING = 1;
 
+/** Nothing is wanted here at all. */
+const NOTHING = 0;
+
+/**
+ * Does this value mean "behind every viewer"?
+ *
+ * A read of the scale, so that nobody has to infer the side from the absence of
+ * a deadline. Inferred that way it was wrong for a stopped viewer, whose whole
+ * film carries no deadline: the film in front of them then counted as behind
+ * them, and the encoders were free to wander to the start of the file.
+ *
+ * @param {number} priority
+ * @returns {boolean}
+ */
+export function isBehindEverybody(priority) {
+  return priority <= NOBODY_IS_COMING;
+}
+
+/**
+ * Is this second the one a viewer is about to watch?
+ *
+ * The top step of the watching band: the film under their feet and the measured
+ * allowance in front of it, which is the depth below which an interruption
+ * reaches them.
+ *
+ * @param {number} priority
+ * @returns {boolean}
+ */
+export function isAtAWatchingViewer(priority) {
+  return priority >= AT_A_WATCHING_VIEWER;
+}
+
+/**
+ * Is this second in front of somebody who has STOPPED, and of nobody who is
+ * watching?
+ *
+ * Wanted, and wanted after everything anybody is walking towards: they will see
+ * it when they press play, and nothing here knows when that is.
+ *
+ * @param {number} priority
+ * @returns {boolean}
+ */
+export function isNobodyComingNow(priority) {
+  return priority > NOBODY_IS_COMING && priority <= AT_A_STOPPED_VIEWER;
+}
+
+/**
+ * How far into its band a second sits, given its distance from the viewer.
+ *
+ * The step doubles: near the viewer the difference between now and ten seconds
+ * away decides what is made first, while twenty minutes out the difference
+ * between twenty and twenty-one minutes changes nothing. The first step is the
+ * MEASURED allowance for this file on this swarm — the depth below which an
+ * interruption reaches the viewer — so how finely the map divides comes from a
+ * measurement rather than from a number chosen here.
+ *
+ * @param {number} distanceSeconds
+ * @param {number} allowanceSeconds
+ * @returns {number} Zero at the viewer, growing with distance.
+ */
+function stepsAway(distanceSeconds, allowanceSeconds) {
+  if (!(distanceSeconds > 0)) {
+    return 0;
+  }
+  return Math.floor(Math.log2(1 + distanceSeconds / allowanceSeconds));
+}
+
 /**
- * The number the second a viewer is about to watch gets. Everything else ahead
- * of them counts down from here.
+ * An empty map of the right length: nothing wanted anywhere.
  *
- * 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.
+ * @param {number} durationSeconds
+ * @returns {PriorityMap}
  */
-export const AT_THE_VIEWER = 32;
+export function emptyMap(durationSeconds) {
+  const seconds = Number.isFinite(durationSeconds) && durationSeconds > 0
+    ? Math.ceil(durationSeconds)
+    : 0;
+  return {
+    durationSeconds: seconds,
+    priority: new Uint8Array(seconds),
+    secondsUntilPlayed: new Float64Array(seconds).fill(Number.POSITIVE_INFINITY),
+    behind: new Uint8Array(seconds).fill(1)
+  };
+}
 
 /**
- * One viewer's map: seconds of film against a number, and nothing else.
+ * One viewer's map.
  *
- * **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 number is a reading of how soon they will be there.** A viewer watching
+ * forward reaches second `x` after `x - p` seconds of film. That distance — not
+ * a clock time — is what the value 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.
+ * **A pause removes the time, not the direction.** A stopped viewer is still
+ * standing somewhere, and the film in front of them is still the film they will
+ * watch, so their map keeps its shape and moves into the band below. Collapsed
+ * to one flat value over the whole film, as it was, their position disappeared
+ * entirely — and with it the rule that what is in front is made first.
  *
  * **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.
+ * where a piece boundary falls, and what has already been made. 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. 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.
+ *   interruption reaches this viewer. The width of the first step.
+ * @param {boolean} [params.playing] - Whether the picture is moving.
+ * @returns {PriorityMap}
  */
 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 > 0)) {
-    return [];
-  }
-  const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0 ? allowanceSeconds : 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 = [];
-  if (from > 0) {
-    zones.push({ from: 0, to: from, priority: NOBODY_IS_COMING });
-  }
-  let at = from;
-  let width = allowance;
-  let priority = AT_THE_VIEWER;
-  while (at < end && priority > NOBODY_IS_COMING + 1) {
-    const to = Math.min(end, at + width);
-    zones.push({ from: at, to, priority });
-    at = to;
-    width *= 2;
-    priority -= 1;
+  const map = emptyMap(durationSeconds);
+  if (map.durationSeconds === 0) {
+    return map;
   }
-  if (at < end) {
-    // 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 });
+  const at = Number.isFinite(atSeconds) && atSeconds > 0 ? Math.floor(atSeconds) : 0;
+  const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0
+    ? allowanceSeconds
+    : 1;
+  const watching = playing !== false;
+  const top = watching ? AT_A_WATCHING_VIEWER : AT_A_STOPPED_VIEWER;
+  const floor = watching ? WATCHING_FLOOR : STOPPED_FLOOR;
+  for (let second = 0; second < map.durationSeconds; second += 1) {
+    if (second < at) {
+      map.priority[second] = NOBODY_IS_COMING;
+      continue;
+    }
+    map.behind[second] = 0;
+    const distance = second - at;
+    map.priority[second] = Math.max(floor, top - stepsAway(distance, allowance));
+    // A viewer who has stopped is on their way nowhere, so there is no second by
+    // which any of this must exist. The direction survives the pause, in the
+    // priority above; the time does not, because there is none to state.
+    map.secondsUntilPlayed[second] = watching ? distance : Number.POSITIVE_INFINITY;
   }
-  return zones;
+  return map;
 }
 
 /**
  * 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.
+ * The highest priority per second wins, and the soonest time: film two people
+ * want is as urgent as the more urgent of them, and making it once serves both.
+ * The two are taken separately on purpose — the priority is coarse, so two
+ * viewers can tie on it while one is genuinely nearer, and whoever schedules
+ * against the time must be given the nearer one.
  *
- * @param {DemandZone[][]} maps
- * @returns {DemandZone[]} Ascending by position.
+ * In front of ANYBODY is in front, and the third array says so directly.
+ *
+ * @param {PriorityMap[]} maps
+ * @returns {PriorityMap}
  */
 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);
-      }
-    }
-  }
+  const all = (maps ?? []).filter((map) => map && map.durationSeconds > 0);
   if (all.length === 0) {
-    return [];
+    return emptyMap(0);
   }
-  // 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;
+  const merged = emptyMap(Math.max(...all.map((map) => map.durationSeconds)));
+  for (const map of all) {
+    for (let second = 0; second < map.durationSeconds; second += 1) {
+      if (map.priority[second] > merged.priority[second]) {
+        merged.priority[second] = map.priority[second];
+      }
+      if (map.secondsUntilPlayed[second] < merged.secondsUntilPlayed[second]) {
+        merged.secondsUntilPlayed[second] = map.secondsUntilPlayed[second];
+      }
+      // In front of ANYBODY is in front: a stretch one viewer has passed is
+      // still the film another is walking towards.
+      if (map.behind[second] === 0) {
+        merged.behind[second] = 0;
       }
     }
-    if (priority <= 0) {
+  }
+  return merged;
+}
+
+/**
+ * The map as stretches: runs of seconds that agree on both numbers.
+ *
+ * A VIEW of the map, never a second copy of it. Consumers that work in ranges —
+ * the swarm is asked for byte ranges, an encoder is given a stretch of pieces —
+ * would otherwise each write this walk for themselves.
+ *
+ * @param {PriorityMap} map
+ * @returns {DemandZone[]} Ascending, without gaps or overlaps. Seconds nobody
+ *   wants are left out.
+ */
+export function runsOf(map) {
+  /** @type {DemandZone[]} */
+  const runs = [];
+  if (!map || !(map.durationSeconds > 0)) {
+    return runs;
+  }
+  for (let second = 0; second < map.durationSeconds; second += 1) {
+    const priority = map.priority[second];
+    if (priority === NOTHING) {
       continue;
     }
-    const previous = merged[merged.length - 1];
-    if (previous && previous.priority === priority && previous.to === from) {
-      previous.to = to;
+    const behind = map.behind[second] === 1;
+    const previous = runs[runs.length - 1];
+    if (
+      previous
+      && previous.to === second
+      && previous.priority === priority
+      && previous.behind === behind
+    ) {
+      previous.to = second + 1;
       continue;
     }
-    merged.push({ from, to, priority });
+    // THE TIME OF A STRETCH IS THE TIME OF ITS NEAR EDGE. A stretch is met at
+    // its beginning, so its beginning is when it must exist; whoever needs the
+    // time of a second inside it walks forward from there, at a second of film
+    // per second, which is the same arithmetic that put the number here.
+    //
+    // Merging on the exact time as well would merge nothing at all: the time is
+    // the distance, so it differs at every second, and the map came back as one
+    // stretch per second of film.
+    const withinSeconds = map.secondsUntilPlayed[second];
+    runs.push({
+      from: second,
+      to: second + 1,
+      priority,
+      withinSeconds,
+      behind
+    });
   }
-  return merged;
+  return runs;
 }
 
 /**
- * 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.
+ * The 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
+ * @param {DemandZone[]} runs
  * @returns {DemandZone[]}
  */
-export function inWorkingOrder(merged) {
-  return [...(merged ?? [])].sort(
+export function inWorkingOrder(runs) {
+  return [...(runs ?? [])].sort(
     (left, right) => right.priority - left.priority || left.from - right.from
   );
 }

package/services/priority/PriorityOrchestrator.js

@@ -16,7 +16,7 @@
  * append, and an empty picture for six minutes (field 2026-09-05).
  */
 
-import { mapForViewer, mergeMaps } from "./PriorityMap.js";
+import { emptyMap, mapForViewer, mergeMaps, runsOf } from "./PriorityMap.js";
 
 export class PriorityOrchestrator {
   /** Where the map goes once it is built. @type {(published: object) => void} */
@@ -25,6 +25,10 @@ export class PriorityOrchestrator {
   /** The last map published per film and file, so an unchanged one is not resent. */
   #last = new Map();
 
+  /** The last map BUILT per film and file, for whoever reads instead of being
+   * handed it. @type {Map<string, import("./PriorityMap.js").PriorityMap>} */
+  #maps = new Map();
+
   /** Who is watching one session. @type {(session: object) => Map<string, object>} */
   #viewersOf;
 
@@ -58,11 +62,11 @@ export class PriorityOrchestrator {
    * @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.
+   * @returns {import("./PriorityMap.js").PriorityMap} One number per second of
+   *   film, merged over everyone watching it.
    */
   build({ sourceKey, fileIndex, durationSeconds, allowanceSeconds, viewers }) {
-    const zones = mergeMaps(
+    const map = mergeMaps(
       (viewers ?? []).map((viewer) =>
         mapForViewer({
           atSeconds: viewer.atSeconds,
@@ -73,15 +77,18 @@ export class PriorityOrchestrator {
       )
     );
     const key = `${sourceKey}:${fileIndex}`;
+    this.#maps.set(key, map);
     // 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.
+    // make it do that several times a second. Compared as stretches rather than
+    // second by second, which is the same comparison over far fewer values.
+    const zones = runsOf(map);
     const shape = JSON.stringify(zones);
     if (this.#last.get(key) !== shape) {
       this.#last.set(key, shape);
       this.#publish({ sourceKey, fileIndex, durationSeconds, zones });
     }
-    return zones;
+    return map;
   }
 
   /**
@@ -143,7 +150,25 @@ export class PriorityOrchestrator {
    * @param {string} sourceKey
    * @param {number} fileIndex
    */
+  /**
+   * The map this class last built for one file.
+   *
+   * Read by whoever acts on it and cannot be handed it at the moment it is
+   * made — the encoding decides per output, and one file has several. It is the
+   * SAME map: built once here, from where the viewers are, and neither read
+   * changes it.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @returns {import("./PriorityMap.js").PriorityMap} A map of no length where
+   *   none was built, which says the same as a map with nothing in it.
+   */
+  mapFor(sourceKey, fileIndex) {
+    return this.#maps.get(`${sourceKey}:${fileIndex}`) ?? emptyMap(0);
+  }
+
   forget(sourceKey, fileIndex) {
     this.#last.delete(`${sourceKey}:${fileIndex}`);
+    this.#maps.delete(`${sourceKey}:${fileIndex}`);
   }
 }