@torrent-tv/proxy 2.87.21 → 2.88.1

package/services/torrent/demand/Urgency.js

@@ -1,137 +1,137 @@
-/**
- * @file How urgent a stated need is, and what follows from that.
- *
- * Five levels, ordered. The ordering is not a set of numbers handed to
- * WebTorrent — measured 2026-09-02, the library does not keep them. Its picker
- * sorts selections by priority only at the moment one is inserted, and then, on
- * every wire it fills, moves the selection it just served to the BACK of the
- * whole group with a non-zero priority:
- *
- * ```js
- * function shufflePriority (i) {
- *   let last = i
- *   for (let j = i; j < self._selections.length && self._selections.get(j).priority; j++) last = j
- *   self._selections.swap(i, last)
- * }
- * ```
- *
- * So distinct non-zero numbers give an order once and a round robin thereafter.
- * Only two things hold: non-zero rotates fairly, zero is always last.
- *
- * Therefore urgency here is expressed by WHETHER a need is stated to the swarm
- * at all. A level is stated only while every level above it is satisfied, and
- * withdrawn the moment one is not — a withdrawn need is not in the download set
- * at all, so a peer with nothing urgent to give cannot fall through to it and
- * spend the shared link on it. A permanently low priority does exactly that,
- * which is why it is not what this does.
- *
- * The rotation is not merely tolerated, it is wanted: with two viewers of one
- * film both stopped, both their needs sit at {@link Urgency.BLOCKED} and the
- * swarm alternates between them instead of always serving whoever asked first.
- */
-
-/**
- * The levels, most urgent first. The value is the position, so `<` compares
- * urgency and nothing else may be read into it.
- *
- * @enum {number}
- */
-export const Urgency = {
-  /**
-   * The bytes a reader is stopped on. The picture is not moving until they
-   * arrive.
-   */
-  BLOCKED: 0,
-  /**
-   * The rest of that reader's own window — the cushion being built. Late here
-   * and the picture stops in a few seconds.
-   */
-  NEAR: 1,
-  /**
-   * Further along the file, as far as the encoder will reach. Late here costs
-   * nothing yet.
-   */
-  AHEAD: 2,
-  /**
-   * To the end of the file. Wanted for certain if the viewer watches on, and
-   * not before anything above is satisfied.
-   */
-  TAIL: 3,
-  /**
-   * The gap behind the playhead, left by a forward seek. Wanted only if the
-   * viewer seeks back, so it is last — but it is real: a backward seek into a
-   * hole is the longest wait this proxy produces (field: 93 s).
-   */
-  BEHIND: 4
-};
-
-/** Every level, most urgent first. */
-export const URGENCY_ORDER = [
-  Urgency.BLOCKED,
-  Urgency.NEAR,
-  Urgency.AHEAD,
-  Urgency.TAIL,
-  Urgency.BEHIND
-];
-
-/**
- * Whether a level may take a block away from a slow peer and give it to a fast
- * one — WebTorrent's `critical`.
- *
- * Only the level that is being waited on. Displacement throws away the part of
- * the block the slow peer had already fetched, so it buys time exactly where
- * time is what is short, and wastes bandwidth everywhere else.
- *
- * @param {number} urgency
- * @returns {boolean}
- */
-export function mayDisplaceSlowPeer(urgency) {
-  return urgency === Urgency.BLOCKED;
-}
-
-/**
- * Whether a level is stated to the swarm only while the levels above it want
- * nothing.
- *
- * The three urgent levels are always stated: they are what the viewer is
- * waiting for. The two speculative ones are stated only in the room the urgent
- * ones leave.
- *
- * @param {number} urgency
- * @returns {boolean}
- */
-export function isConditional(urgency) {
-  return urgency >= Urgency.TAIL;
-}
-
-/**
- * The number handed to `torrent.select`.
- *
- * Two values only, because two is all the library keeps: everything urgent
- * shares one non-zero priority and rotates fairly among itself; the
- * speculative levels take zero, which the library always places last and never
- * rotates into the group above.
- *
- * @param {number} urgency
- * @returns {number}
- */
-export function selectionPriority(urgency) {
-  return isConditional(urgency) ? 0 : 1;
-}
-
-/**
- * A level's name, for the log.
- *
- * @param {number} urgency
- * @returns {string}
- */
-export function urgencyName(urgency) {
-  switch (urgency) {
-    case Urgency.BLOCKED: return "blocked";
-    case Urgency.NEAR: return "near";
-    case Urgency.AHEAD: return "ahead";
-    case Urgency.TAIL: return "tail";
-    case Urgency.BEHIND: return "behind";
-    default: return `urgency-${urgency}`;
-  }
-}
+/**
+ * @file How urgent a stated need is, and what follows from that.
+ *
+ * Five levels, ordered. The ordering is not a set of numbers handed to
+ * WebTorrent — measured 2026-09-02, the library does not keep them. Its picker
+ * sorts selections by priority only at the moment one is inserted, and then, on
+ * every wire it fills, moves the selection it just served to the BACK of the
+ * whole group with a non-zero priority:
+ *
+ * ```js
+ * function shufflePriority (i) {
+ *   let last = i
+ *   for (let j = i; j < self._selections.length && self._selections.get(j).priority; j++) last = j
+ *   self._selections.swap(i, last)
+ * }
+ * ```
+ *
+ * So distinct non-zero numbers give an order once and a round robin thereafter.
+ * Only two things hold: non-zero rotates fairly, zero is always last.
+ *
+ * Therefore urgency here is expressed by WHETHER a need is stated to the swarm
+ * at all. A level is stated only while every level above it is satisfied, and
+ * withdrawn the moment one is not — a withdrawn need is not in the download set
+ * at all, so a peer with nothing urgent to give cannot fall through to it and
+ * spend the shared link on it. A permanently low priority does exactly that,
+ * which is why it is not what this does.
+ *
+ * The rotation is not merely tolerated, it is wanted: with two viewers of one
+ * film both stopped, both their needs sit at {@link Urgency.BLOCKED} and the
+ * swarm alternates between them instead of always serving whoever asked first.
+ */
+
+/**
+ * The levels, most urgent first. The value is the position, so `<` compares
+ * urgency and nothing else may be read into it.
+ *
+ * @enum {number}
+ */
+export const Urgency = {
+  /**
+   * The bytes a reader is stopped on. The picture is not moving until they
+   * arrive.
+   */
+  BLOCKED: 0,
+  /**
+   * The rest of that reader's own window — the cushion being built. Late here
+   * and the picture stops in a few seconds.
+   */
+  NEAR: 1,
+  /**
+   * Further along the file, as far as the encoder will reach. Late here costs
+   * nothing yet.
+   */
+  AHEAD: 2,
+  /**
+   * To the end of the file. Wanted for certain if the viewer watches on, and
+   * not before anything above is satisfied.
+   */
+  TAIL: 3,
+  /**
+   * The gap behind the playhead, left by a forward seek. Wanted only if the
+   * viewer seeks back, so it is last — but it is real: a backward seek into a
+   * hole is the longest wait this proxy produces (field: 93 s).
+   */
+  BEHIND: 4
+};
+
+/** Every level, most urgent first. */
+export const URGENCY_ORDER = [
+  Urgency.BLOCKED,
+  Urgency.NEAR,
+  Urgency.AHEAD,
+  Urgency.TAIL,
+  Urgency.BEHIND
+];
+
+/**
+ * Whether a level may take a block away from a slow peer and give it to a fast
+ * one — WebTorrent's `critical`.
+ *
+ * Only the level that is being waited on. Displacement throws away the part of
+ * the block the slow peer had already fetched, so it buys time exactly where
+ * time is what is short, and wastes bandwidth everywhere else.
+ *
+ * @param {number} urgency
+ * @returns {boolean}
+ */
+export function mayDisplaceSlowPeer(urgency) {
+  return urgency === Urgency.BLOCKED;
+}
+
+/**
+ * Whether a level is stated to the swarm only while the levels above it want
+ * nothing.
+ *
+ * The three urgent levels are always stated: they are what the viewer is
+ * waiting for. The two speculative ones are stated only in the room the urgent
+ * ones leave.
+ *
+ * @param {number} urgency
+ * @returns {boolean}
+ */
+export function isConditional(urgency) {
+  return urgency >= Urgency.TAIL;
+}
+
+/**
+ * The number handed to `torrent.select`.
+ *
+ * Two values only, because two is all the library keeps: everything urgent
+ * shares one non-zero priority and rotates fairly among itself; the
+ * speculative levels take zero, which the library always places last and never
+ * rotates into the group above.
+ *
+ * @param {number} urgency
+ * @returns {number}
+ */
+export function selectionPriority(urgency) {
+  return isConditional(urgency) ? 0 : 1;
+}
+
+/**
+ * A level's name, for the log.
+ *
+ * @param {number} urgency
+ * @returns {string}
+ */
+export function urgencyName(urgency) {
+  switch (urgency) {
+    case Urgency.BLOCKED: return "blocked";
+    case Urgency.NEAR: return "near";
+    case Urgency.AHEAD: return "ahead";
+    case Urgency.TAIL: return "tail";
+    case Urgency.BEHIND: return "behind";
+    default: return `urgency-${urgency}`;
+  }
+}

package/services/torrent/demand/Window.js

@@ -1,118 +1,118 @@
-/**
- * @file One stated need: bytes of one file, by one claimant, at one urgency.
- *
- * **Bytes, not pieces.** A piece is how the protocol verifies data and how
- * memory is allocated; it is not the unit anything else should count in.
- * Counting in pieces means dividing and rounding down at every boundary, and
- * that rounding is where a real failure lives: with 16 MiB pieces a 64 MB
- * allowance is four places, while two readers asking for 96 MB each want six —
- * every resident piece then ends up pinned, the read returns zero bytes, and
- * ffmpeg takes that for the end of the file. In bytes the shortage is plain;
- * in pieces it is hidden behind a floor. The single conversion lives in
- * `pieces.js`.
- */
-
-/**
- * A range of one file that somebody says they will need.
- */
-export class Window {
-  /**
-   * @param {object} params
-   * @param {string} params.claimant - Who states it. A release names this, so a
-   *   stray release matches nothing rather than cancelling somebody else's
-   *   need.
-   * @param {number} params.fileIndex - Which file of the torrent.
-   * @param {number} params.byteStart - First byte, inclusive.
-   * @param {number} params.byteEnd - Last byte, inclusive.
-   * @param {number} params.urgency - A value of {@link import("./Urgency.js").Urgency}.
-   */
-  constructor({ claimant, fileIndex, byteStart, byteEnd, urgency }) {
-    if (typeof claimant !== "string" || claimant.length === 0) {
-      throw new Error("A window needs a claimant to release it by.");
-    }
-    if (!Number.isInteger(fileIndex) || fileIndex < 0) {
-      throw new Error(`File index must be a non-negative integer, got ${fileIndex}.`);
-    }
-    if (!Number.isInteger(byteStart) || byteStart < 0) {
-      throw new Error(`Byte start must be a non-negative integer, got ${byteStart}.`);
-    }
-    if (!Number.isInteger(byteEnd) || byteEnd < byteStart) {
-      throw new Error(`Byte end must be an integer at or after ${byteStart}, got ${byteEnd}.`);
-    }
-    if (!Number.isInteger(urgency) || urgency < 0) {
-      throw new Error(`Urgency must be a non-negative integer, got ${urgency}.`);
-    }
-    this.claimant = claimant;
-    this.fileIndex = fileIndex;
-    this.byteStart = byteStart;
-    this.byteEnd = byteEnd;
-    this.urgency = urgency;
-    Object.freeze(this);
-  }
-
-  /** How many bytes this window covers. */
-  get byteLength() {
-    return this.byteEnd - this.byteStart + 1;
-  }
-
-  /**
-   * Whether two windows cover any of the same bytes of the same file.
-   *
-   * @param {Window} other
-   * @returns {boolean}
-   */
-  overlaps(other) {
-    return this.fileIndex === other.fileIndex
-      && this.byteStart <= other.byteEnd
-      && other.byteStart <= this.byteEnd;
-  }
-
-  /**
-   * Whether two windows are the same statement — same file, same bytes, same
-   * urgency, same claimant.
-   *
-   * @param {Window} other
-   * @returns {boolean}
-   */
-  equals(other) {
-    return other instanceof Window
-      && this.claimant === other.claimant
-      && this.fileIndex === other.fileIndex
-      && this.byteStart === other.byteStart
-      && this.byteEnd === other.byteEnd
-      && this.urgency === other.urgency;
-  }
-
-  /** @returns {string} */
-  toString() {
-    return `${this.claimant} wants ${this.fileIndex}:${this.byteStart}-${this.byteEnd}`;
-  }
-}
-
-/**
- * The union of a set of ranges of ONE file, in order, with touching and
- * overlapping ones merged.
- *
- * The union and not the sum: a viewer's picture and sound are read by two
- * readers of the same file whose windows overlap by construction, and adding
- * them would report a demand that is not there.
- *
- * @param {Array<{ byteStart: number, byteEnd: number }>} ranges
- * @returns {Array<{ byteStart: number, byteEnd: number }>}
- */
-export function unionOf(ranges) {
-  const sorted = [...ranges].sort((left, right) => left.byteStart - right.byteStart);
-  /** @type {Array<{ byteStart: number, byteEnd: number }>} */
-  const merged = [];
-  for (const range of sorted) {
-    const last = merged[merged.length - 1];
-    // `+ 1` because ranges are inclusive: 0-99 and 100-199 are one run of 200
-    // bytes, not two runs with nothing between them.
-    if (last && range.byteStart <= last.byteEnd + 1) {
-      last.byteEnd = Math.max(last.byteEnd, range.byteEnd);
-      continue;
-    }
-    merged.push({ byteStart: range.byteStart, byteEnd: range.byteEnd });
-  }
-  return merged;
-}
+/**
+ * @file One stated need: bytes of one file, by one claimant, at one urgency.
+ *
+ * **Bytes, not pieces.** A piece is how the protocol verifies data and how
+ * memory is allocated; it is not the unit anything else should count in.
+ * Counting in pieces means dividing and rounding down at every boundary, and
+ * that rounding is where a real failure lives: with 16 MiB pieces a 64 MB
+ * allowance is four places, while two readers asking for 96 MB each want six —
+ * every resident piece then ends up pinned, the read returns zero bytes, and
+ * ffmpeg takes that for the end of the file. In bytes the shortage is plain;
+ * in pieces it is hidden behind a floor. The single conversion lives in
+ * `pieces.js`.
+ */
+
+/**
+ * A range of one file that somebody says they will need.
+ */
+export class Window {
+  /**
+   * @param {object} params
+   * @param {string} params.claimant - Who states it. A release names this, so a
+   *   stray release matches nothing rather than cancelling somebody else's
+   *   need.
+   * @param {number} params.fileIndex - Which file of the torrent.
+   * @param {number} params.byteStart - First byte, inclusive.
+   * @param {number} params.byteEnd - Last byte, inclusive.
+   * @param {number} params.urgency - A value of {@link import("./Urgency.js").Urgency}.
+   */
+  constructor({ claimant, fileIndex, byteStart, byteEnd, urgency }) {
+    if (typeof claimant !== "string" || claimant.length === 0) {
+      throw new Error("A window needs a claimant to release it by.");
+    }
+    if (!Number.isInteger(fileIndex) || fileIndex < 0) {
+      throw new Error(`File index must be a non-negative integer, got ${fileIndex}.`);
+    }
+    if (!Number.isInteger(byteStart) || byteStart < 0) {
+      throw new Error(`Byte start must be a non-negative integer, got ${byteStart}.`);
+    }
+    if (!Number.isInteger(byteEnd) || byteEnd < byteStart) {
+      throw new Error(`Byte end must be an integer at or after ${byteStart}, got ${byteEnd}.`);
+    }
+    if (!Number.isInteger(urgency) || urgency < 0) {
+      throw new Error(`Urgency must be a non-negative integer, got ${urgency}.`);
+    }
+    this.claimant = claimant;
+    this.fileIndex = fileIndex;
+    this.byteStart = byteStart;
+    this.byteEnd = byteEnd;
+    this.urgency = urgency;
+    Object.freeze(this);
+  }
+
+  /** How many bytes this window covers. */
+  get byteLength() {
+    return this.byteEnd - this.byteStart + 1;
+  }
+
+  /**
+   * Whether two windows cover any of the same bytes of the same file.
+   *
+   * @param {Window} other
+   * @returns {boolean}
+   */
+  overlaps(other) {
+    return this.fileIndex === other.fileIndex
+      && this.byteStart <= other.byteEnd
+      && other.byteStart <= this.byteEnd;
+  }
+
+  /**
+   * Whether two windows are the same statement — same file, same bytes, same
+   * urgency, same claimant.
+   *
+   * @param {Window} other
+   * @returns {boolean}
+   */
+  equals(other) {
+    return other instanceof Window
+      && this.claimant === other.claimant
+      && this.fileIndex === other.fileIndex
+      && this.byteStart === other.byteStart
+      && this.byteEnd === other.byteEnd
+      && this.urgency === other.urgency;
+  }
+
+  /** @returns {string} */
+  toString() {
+    return `${this.claimant} wants ${this.fileIndex}:${this.byteStart}-${this.byteEnd}`;
+  }
+}
+
+/**
+ * The union of a set of ranges of ONE file, in order, with touching and
+ * overlapping ones merged.
+ *
+ * The union and not the sum: a viewer's picture and sound are read by two
+ * readers of the same file whose windows overlap by construction, and adding
+ * them would report a demand that is not there.
+ *
+ * @param {Array<{ byteStart: number, byteEnd: number }>} ranges
+ * @returns {Array<{ byteStart: number, byteEnd: number }>}
+ */
+export function unionOf(ranges) {
+  const sorted = [...ranges].sort((left, right) => left.byteStart - right.byteStart);
+  /** @type {Array<{ byteStart: number, byteEnd: number }>} */
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    // `+ 1` because ranges are inclusive: 0-99 and 100-199 are one run of 200
+    // bytes, not two runs with nothing between them.
+    if (last && range.byteStart <= last.byteEnd + 1) {
+      last.byteEnd = Math.max(last.byteEnd, range.byteEnd);
+      continue;
+    }
+    merged.push({ byteStart: range.byteStart, byteEnd: range.byteEnd });
+  }
+  return merged;
+}

package/services/torrent/demand/index.js

@@ -1,8 +1,8 @@
-// Only what is imported through this file. `unionOf`, `mayDisplaceSlowPeer`,
-// `URGENCY_ORDER`, `nearestFirst`, `piecesNeededFor` and `piecesWithin` were
-// re-exported here and taken by nobody; each is still where it is declared, and
-// still used there.
-export { DemandRegister } from "./DemandRegister.js";
-export { Window } from "./Window.js";
-export { isConditional, selectionPriority, Urgency, urgencyName } from "./Urgency.js";
-export { bytesOf, piecesOf } from "./pieces.js";
+// Only what is imported through this file. `unionOf`, `mayDisplaceSlowPeer`,
+// `URGENCY_ORDER`, `nearestFirst`, `piecesNeededFor` and `piecesWithin` were
+// re-exported here and taken by nobody; each is still where it is declared, and
+// still used there.
+export { DemandRegister } from "./DemandRegister.js";
+export { Window } from "./Window.js";
+export { isConditional, selectionPriority, Urgency, urgencyName } from "./Urgency.js";
+export { bytesOf, piecesOf } from "./pieces.js";