@torrent-tv/proxy 2.95.27 → 2.95.28

package/package.json

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

package/services/torrent/demand/Urgency.js

@@ -18,12 +18,10 @@
  * 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.
+ * WebTorrent checks selections per wire and falls through to zero-priority
+ * selections when a wire has no piece from a non-zero selection. Therefore the
+ * global first class is the only urgent level stated while any urgent piece is
+ * missing. Conditional levels are stated only when no urgent piece is missing.
  *
  * 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
@@ -107,10 +105,10 @@ export function isConditional(urgency) {
 /**
  * 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.
+ * Two values only, because two is all the library keeps: selected first-class
+ * windows share one non-zero priority and rotate fairly among themselves;
+ * conditional levels take zero. Less urgent windows are withheld while an
+ * urgent piece is missing, rather than relying on zero to keep them back.
  *
  * @param {number} urgency
  * @returns {number}

package/services/torrent/download/SwarmSelection.js

@@ -17,23 +17,17 @@
  * vendored 2.8.5: selections are sorted by priority only when one is inserted,
  * and `shufflePriority` then moves the selection just served to the back of the
  * whole non-zero group. Distinct numbers therefore order the list once and
- * round-robin it afterwards. The library honours one distinction: non-zero
- * before zero. A wire with nothing left to take from the non-zero selections
- * goes on to the zero ones, and within a selection it takes the earliest piece
- * it holds.
+ * round-robin it afterwards. The library checks selections separately for each
+ * wire. If that wire holds no missing piece from a non-zero selection, it falls
+ * through to a zero selection. A zero priority therefore does not withhold a
+ * less urgent piece from a peer that lacks the first class.
  *
- * **So everything wanted is stated, and only the first class is non-zero.**
- * The first class is the most urgent level that is still missing anything, at
- * its highest priority, whatever its deadlines. Everything else that is not
- * speculative is stated at zero, so it is fetched only by a wire that would
- * otherwise stand idle. Stating only the earliest deadline, as this did after
- * #95, left every peer that held none of that segment's pieces without a
- * request: on Home Assistant, with three peers each holding every third piece
- * and one complete slow peer, twelve segments took 184 s at 0.61 MiB/s against
- * 18.3 s at 6.1 MiB/s when the whole band was stated
- * (`research/download-translation-2026-10-07.md`, torrent-tv/meta#95).
- * Speculative levels stay withheld while anything urgent is missing anywhere,
- * because the link is shared.
+ * While an urgent piece is missing, only the global first class is stated.
+ * This keeps a wire that lacks those pieces from spending its requests on a
+ * lower class. The first class is the most urgent missing level at its highest
+ * map priority, regardless of deadlines. Every window in that class is stated
+ * so peers holding different first-class pieces can all contribute. Once no
+ * urgent piece is missing, conditional levels may be stated at zero.
  */
 
 import {
@@ -90,16 +84,18 @@ export class SwarmSelection {
   reconcile({ speculativeAllowed = !this.hasUrgentMissing(), firstClass = null } = {}) {
     const missing = this.#register.windows().filter(window => !this.#isSatisfied(window));
     const first = firstClass ?? this.missingBand();
+    const strictFirstClass = first !== null && !isConditional(first.urgency);
     /** @type {Map<string, { from: number, to: number, priority: number }>} */
     const wanted = new Map();
     for (const priority of [1, 0]) {
       const ranges = [];
       for (const window of missing) {
         if (!speculativeAllowed && isConditional(window.urgency)) continue;
-        // Speculative levels are never the first class: the library keeps
-        // zero-priority selections last and never rotates them above.
+        // The first class is the only eligible urgent level; zero priority
+        // still falls through on wires that have none of its pieces.
         const inFirstClass = first !== null && !isConditional(window.urgency)
           && window.urgency === first.urgency && window.priority >= first.priority;
+        if (strictFirstClass && !inFirstClass) continue;
         if ((inFirstClass ? 1 : 0) !== priority) continue;
         const range = this.#piecesFor(window);
         if (range) ranges.push(range);

package/services/torrent/download/registry.js

@@ -125,7 +125,7 @@ export function reconcileAll() {
   const entries = [...live];
   const speculativeAllowed = !entries.some((entry) => entry.selection.hasUrgentMissing());
   // The first class across every torrent: the most urgent missing level and
-  // its highest priority. Each selection states it non-zero and the rest zero.
+  // its highest priority. Lower classes stay out of every torrent's selection.
   const bands = entries.map(entry => entry.selection.missingBand()).filter(Boolean);
   const urgency = bands.length ? Math.min(...bands.map(band => band.urgency)) : null;
   const firstClass = urgency === null ? null
@@ -142,8 +142,8 @@ export function reconcileAll() {
   } finally {
     publishingSelections = false;
   }
-  // What the swarm is told to fetch FIRST, said when it changes: the rest is
-  // fetched only by a wire with nothing first-class left to take.
+  // What the swarm is told to fetch FIRST, said when it changes. Lower classes
+  // are withheld because a wire with no first-class piece would fall through.
   const said = entries.map(entry => `${String(entry.torrent.infoHash ?? "").slice(0, 8)}: ` +
     `${(entry.selection.firstClassPieces ?? []).slice(0, 8).join(",") || "nothing"}` +
     `${(entry.selection.firstClassPieces?.length ?? 0) > 8 ? ` +${entry.selection.firstClassPieces.length - 8} more` : ""}`).join("; ");

package/services/torrent/torrent-pool.js

@@ -283,11 +283,36 @@ function describeSwarmDemand(torrent) {
     ? torrent._critical.reduce((count, flag) => (flag ? count + 1 : count), 0)
     : 0;
 
+  const firstClassPieces = [];
+  const seenFirstClassPieces = new Set();
+  let omittedFirstClassPieces = 0;
+  for (const item of items) {
+    if (!(Number(item?.priority) > 0)) continue;
+    const from = Number(item?.from);
+    const to = Number(item?.to);
+    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to)) continue;
+    for (let index = from; index <= to; index += 1) {
+      if (seenFirstClassPieces.has(index) || torrent.bitfield?.get(index)) continue;
+      seenFirstClassPieces.add(index);
+      if (firstClassPieces.length >= 32) {
+        omittedFirstClassPieces += 1;
+        continue;
+      }
+      const holders = wires.filter(wire => !wire?.destroyed && wire?.peerPieces?.get?.(index) === true);
+      const ready = holders.filter(wire => wire.peerChoking !== true).length;
+      const requests = wires.reduce((count, wire) => count + (Array.isArray(wire?.requests)
+        ? wire.requests.filter(request => request?.piece === index).length : 0), 0);
+      firstClassPieces.push(`${index}(holders=${holders.length},unchoked=${ready},requests=${requests})`);
+    }
+  }
+
   return (
     `${items.length} selection(s) covering ${selectedPieces} piece(s), ` +
     `${missingSelected} of them missing, ${critical} marked critical; ` +
     `${wires.length} peers, ${interested} we want data from, ${choking} choking us, ` +
-    `${asking} being asked, ${inFlight} blocks in flight`
+    `${asking} being asked, ${inFlight} blocks in flight; first-class missing ` +
+    `${firstClassPieces.join(", ") || "none"}` +
+    (omittedFirstClassPieces > 0 ? `; ${omittedFirstClassPieces} more first-class piece(s)` : "")
   );
 }
 
@@ -1183,10 +1208,10 @@ export class TorrentPool {
    * line of the log said anything was wrong — the collapse had to be recovered
    * afterwards by hand from three unrelated counters.
    *
-   * So the stall reports itself, and it reports the two things that tell the
-   * candidates apart: whether the swarm was ASKED for anything (pieces selected
-   * and still missing, blocks in flight) or was asked and did not answer (peers
-   * holding what we want, how many are choking us).
+   * So the stall reports itself, and it reports whether the swarm was asked for
+   * anything (pieces selected and still missing, blocks in flight) or was asked
+   * and did not answer (peer holders and outstanding requests for each missing
+   * first-class piece, plus how many peers are choking us).
    *
    * @returns {void}
    */