@torrent-tv/proxy 2.28.0 → 2.29.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.29.0
+
+- **New**: A piece a reader is blocked on is handed to the fastest peers that hold it. Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times in two minutes, 1.0-4.5 s each, on pieces a median of five peers already had. A block belongs to exactly one wire, so the read ends when the SLOWEST holder delivers, and `critical()` only lets the library take a block from a slow wire when its own picker happens to visit an idle one. This asks for it deliberately: when the wait starts, and again on the sampling tick that already runs while it lasts, the piece is pushed onto the three fastest unchoked holders through the library's own request entry with hotswap enabled. Nothing is duplicated — the library moves a block to a wire at least twice as fast, which bounds how often it can move at all. A refusal is counted rather than ignored (a full pipeline, or nothing reservable even with hotswap, means the piece waits on the wire and not on the picker), and a build that offers no such entry says so instead of failing silently. The wait line now reports `steered onto N of M holders`, so the next session says by number whether the tail shortened.
+
 ## 2.28.0
 
 - **Fix**: The playlist and the media agree again, and the container's keyframe table was never at fault. On a file whose first timestamp is 2.002 s, the copied picture was asked to cut at 808.808 s on the 0-based grid and cut at 806.806 s — exactly the container's start time early, because that branch keeps the source's own timestamps and re-labels the output afterwards, so a cut list stated in 0-based terms is applied 2 s away from where it means. The soundtrack, re-encoded and on the other branch, cut where it was asked. The two then wrote different values into the shared boundary table and corrected each other for the whole session (#202: 808.808 → 806.806 → 808.750 → …), the playlist drifted a whole segment from the media, and the player refetched fragments it could not place. The cut list is now stated in the source's terms on that branch, which is the same shift the seek on it already applies.

package/package.json

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

package/services/torrent-worker/fastest-wires.js

@@ -0,0 +1,121 @@
+/**
+ * @file Put the piece a reader is blocked on onto the fastest wires that hold
+ * it.
+ *
+ * Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed
+ * at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times
+ * in two minutes, 1.0-4.5 s each. So the shortage is not bandwidth. The piece
+ * that blocked had been requested from a median of five peers, and what set the
+ * tail was WHICH wire held the last outstanding block: a block is reserved for
+ * exactly one wire, and the read finishes when the slowest holder delivers.
+ *
+ * What the library already does, and what it does not: `torrent.critical()`
+ * (which the reader already sets over its window) enables HOTSWAP — an idle
+ * wire may take a block away from the SLOWEST holder. It does not duplicate:
+ * `piece.reserve()` returns -1 once every block is spoken for, and the
+ * end-game that would ask a second peer for the same block is commented out in
+ * `webtorrent/lib/torrent.js`. Hotswap therefore fires only when the library's
+ * own picker happens to visit an idle wire while our piece is critical.
+ *
+ * This asks for it on purpose, and chooses who: the wires that are unchoked,
+ * hold the piece and are measurably fastest are handed the piece through the
+ * same entry the library's picker uses, with hotswap enabled. Nothing is
+ * duplicated and no protocol rule is bent — the block moves to a faster holder
+ * instead of staying with whoever got it first.
+ */
+
+/**
+ * The library's own request entry. Internal, so its absence must be noticed
+ * rather than swallowed: without it this lever silently does nothing.
+ *
+ * @param {object} torrent
+ * @returns {boolean}
+ */
+export function canPlaceRequests(torrent) {
+  return typeof torrent?._request === "function";
+}
+
+/**
+ * Wires that could deliver this piece right now, fastest first.
+ *
+ * Excluded, each for its own reason: a wire that is choking us cannot be asked
+ * at all; one that does not hold the piece has nothing to give; a destroyed one
+ * is a corpse. Speed is the library's own measurement over its own window, so
+ * nothing here needs a history of its own.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @returns {object[]}
+ */
+export function wiresForPiece(torrent, pieceIndex) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
+  const usable = [];
+  for (const wire of wires) {
+    if (!wire || wire.destroyed || wire.peerChoking) {
+      continue;
+    }
+    if (wire.peerPieces?.get?.(pieceIndex) !== true) {
+      continue;
+    }
+    usable.push(wire);
+  }
+  return usable.sort((left, right) => speedOf(right) - speedOf(left));
+}
+
+/**
+ * A wire's measured download speed in bytes per second, or 0 when it has not
+ * been measured. Wrapped because `downloadSpeed` is a method on the wire and a
+ * throw from a destroyed one must not take the caller with it.
+ *
+ * @param {object} wire
+ * @returns {number}
+ */
+function speedOf(wire) {
+  try {
+    const speed = wire?.downloadSpeed?.();
+    return Number.isFinite(speed) ? speed : 0;
+  } catch {
+    // A wire that cannot say how fast it is ranks last, which is the honest
+    // answer — and the caller's own log line reports how many were asked.
+    return 0;
+  }
+}
+
+/**
+ * Ask the fastest holders of `pieceIndex` for it.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @param {number} [limit] - How many wires to push it onto.
+ * @returns {{ asked: number, considered: number, fastestBytesPerSecond: number }}
+ *   `asked` counts requests the library actually placed: it refuses when a
+ *   wire's pipeline is full or when nothing can be reserved even with hotswap,
+ *   and that refusal is information — a piece nobody can be asked for is
+ *   waiting on the wire, not on the picker.
+ */
+export function askFastestWiresFor(torrent, pieceIndex, limit = 3) {
+  if (!canPlaceRequests(torrent) || !Number.isInteger(pieceIndex) || pieceIndex < 0) {
+    return { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+  }
+  const candidates = wiresForPiece(torrent, pieceIndex);
+  let asked = 0;
+  for (const wire of candidates.slice(0, Math.max(1, limit))) {
+    try {
+      // `true` is hotswap: if every block is reserved, take one from the
+      // slowest holder. That is the whole point — the reader is blocked
+      // precisely because a slow holder has one.
+      if (torrent._request(wire, pieceIndex, true) === true) {
+        asked += 1;
+      }
+    } catch (error) {
+      // Internal call: report it once per attempt rather than letting the lever
+      // fail in silence.
+      throw new Error(`could not place a request for piece ${pieceIndex}: ${error?.message ?? error}`);
+    }
+  }
+  return {
+    asked,
+    considered: candidates.length,
+    fastestBytesPerSecond: candidates.length > 0 ? speedOf(candidates[0]) : 0
+  };
+}

package/services/torrent-worker/piece-reader.js

@@ -22,6 +22,7 @@
 
 import { findSharedStore } from "../piece-store/shared-piece-store.js";
 import { logger } from "../../utils/logger.js";
+import { askFastestWiresFor, canPlaceRequests } from "./fastest-wires.js";
 
 /** Only waits at least this long are reported; sequential reading stays silent. */
 const PIECE_WAIT_LOG_MS = 1_000;
@@ -438,6 +439,35 @@ export async function* readFragments({
       }
 
       const waitStartedAt = Date.now();
+      // The reader is blocked, so this piece is now the only thing that matters
+      // on this torrent: hand it to the fastest wires that hold it. A block is
+      // reserved for exactly one wire, and the read ends when the slowest
+      // holder delivers — measured 2026-08-17, the swarm had a fivefold surplus
+      // of bandwidth and the reader still waited 1.0-4.5 s, 47 times in two
+      // minutes, on pieces five peers already had.
+      let pushed = { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+      const pushToFastest = () => {
+        try {
+          const result = askFastestWiresFor(torrent, pieceIndex);
+          pushed = {
+            asked: pushed.asked + result.asked,
+            considered: result.considered,
+            fastestBytesPerSecond: result.fastestBytesPerSecond
+          };
+        } catch (error) {
+          // The entry is internal to the library; if a version changes it, this
+          // lever stops working and that must be visible rather than silent.
+          logger.warn(`piece-reader: could not steer piece ${pieceIndex} — ${error?.message ?? error}`);
+        }
+      };
+      if (canPlaceRequests(torrent)) {
+        pushToFastest();
+      } else {
+        logger.warn(
+          "piece-reader: this webtorrent build offers no way to place a request; " +
+            "the blocked piece cannot be steered onto a faster peer"
+        );
+      }
       // Sampled while waiting rather than after: once the piece lands, nothing
       // is outstanding on it any more and every count reads zero.
       let supply = null;
@@ -446,6 +476,9 @@ export async function* readFragments({
         if (!supply || sample.blocks > supply.blocks) {
           supply = sample;
         }
+        // Wires come and go, and their speeds change: a holder that was slow a
+        // moment ago may now be the fastest one available.
+        pushToFastest();
       }, 500);
       try {
         await whenPieceReady(torrent, pieceIndex, cancellation);
@@ -482,7 +515,14 @@ export async function* readFragments({
             (supply
               ? `${supply.holders}/${supply.peers} peers had it, ${supply.askedOf} were asked, ` +
                 `${supply.blocks} blocks (${Math.round((supply.blocks * 16384) / 1024)}KB) in flight at peak`
-              : "no sample taken")
+              : "no sample taken") +
+            // What WE did about it, so the next session says whether steering
+            // the piece onto faster holders shortens the tail — by number
+            // rather than by impression.
+            `; steered onto ${pushed.asked} of ${pushed.considered} holders` +
+            (pushed.fastestBytesPerSecond > 0
+              ? `, fastest ${Math.round(pushed.fastestBytesPerSecond / 1024)}KB/s`
+              : "")
         );
       }
 

package/test/fastest-wires.test.js

@@ -0,0 +1,121 @@
+/**
+ * @file Choosing who is asked for the piece a reader is blocked on.
+ *
+ * The measurement behind it (2026-08-17): a fivefold bandwidth surplus and 47
+ * blocking waits in two minutes, on pieces a median of five peers already had.
+ * A block belongs to one wire, so the read ends when the SLOWEST holder
+ * delivers — which makes "who holds it" the thing worth deciding.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { askFastestWiresFor, canPlaceRequests, wiresForPiece } from "../services/torrent-worker/fastest-wires.js";
+
+/**
+ * @param {{ speed: number, has?: boolean, choking?: boolean, destroyed?: boolean }} options
+ * @returns {object}
+ */
+function wire({ speed, has = true, choking = false, destroyed = false }) {
+  return {
+    destroyed,
+    peerChoking: choking,
+    peerPieces: { get: () => has },
+    downloadSpeed: () => speed
+  };
+}
+
+/**
+ * @param {object[]} wires
+ * @returns {{ torrent: object, asked: Array<{ speed: number, hotswap: boolean }> }}
+ */
+function torrentWith(wires, { refuse = false } = {}) {
+  /** @type {Array<{ speed: number, hotswap: boolean }>} */
+  const asked = [];
+  const torrent = {
+    wires,
+    _request(target, _index, hotswap) {
+      asked.push({ speed: target.downloadSpeed(), hotswap });
+      return !refuse;
+    }
+  };
+  return { torrent, asked };
+}
+
+test("the fastest holders are asked first", () => {
+  const { torrent, asked } = torrentWith([
+    wire({ speed: 100_000 }),
+    wire({ speed: 900_000 }),
+    wire({ speed: 400_000 })
+  ]);
+
+  const result = askFastestWiresFor(torrent, 42);
+
+  assert.deepEqual(
+    asked.map((entry) => entry.speed),
+    [900_000, 400_000, 100_000],
+    "fastest first — the read ends when the slowest holder delivers"
+  );
+  assert.equal(result.asked, 3);
+  assert.equal(result.fastestBytesPerSecond, 900_000);
+});
+
+test("hotswap is always on, because that is the whole point", () => {
+  // The reader is blocked precisely because every block is reserved and one of
+  // them sits with a slow wire. Without hotswap the library answers "nothing to
+  // reserve" and the lever does nothing at all.
+  const { torrent, asked } = torrentWith([wire({ speed: 10 })]);
+  askFastestWiresFor(torrent, 7);
+  assert.deepEqual(asked.map((entry) => entry.hotswap), [true]);
+});
+
+test("a wire that cannot deliver is not asked", () => {
+  const { torrent, asked } = torrentWith([
+    wire({ speed: 900_000, choking: true }),
+    wire({ speed: 800_000, has: false }),
+    wire({ speed: 700_000, destroyed: true }),
+    wire({ speed: 1_000 })
+  ]);
+
+  const result = askFastestWiresFor(torrent, 3);
+
+  assert.equal(asked.length, 1, "a choking, an absent and a dead wire are all unusable");
+  assert.equal(result.considered, 1);
+});
+
+test("a refusal is counted as a refusal", () => {
+  // The library refuses when a wire's pipeline is full or nothing can be
+  // reserved even with hotswap. That is information: the piece is waiting on
+  // the wire, not on the picker.
+  const { torrent } = torrentWith([wire({ speed: 500 }), wire({ speed: 400 })], { refuse: true });
+  const result = askFastestWiresFor(torrent, 11);
+  assert.equal(result.asked, 0);
+  assert.equal(result.considered, 2);
+});
+
+test("a build without the request entry is reported, not silently skipped", () => {
+  assert.equal(canPlaceRequests({ wires: [] }), false);
+  assert.equal(canPlaceRequests({ wires: [], _request: () => true }), true);
+  const result = askFastestWiresFor({ wires: [wire({ speed: 1 })] }, 1);
+  assert.deepEqual(result, { asked: 0, considered: 0, fastestBytesPerSecond: 0 });
+});
+
+test("a wire that cannot say how fast it is ranks last rather than throwing", () => {
+  const mute = wire({ speed: 0 });
+  mute.downloadSpeed = () => {
+    throw new Error("destroyed");
+  };
+  const ranked = wiresForPiece({ wires: [mute, wire({ speed: 5 })] }, 0);
+  assert.equal(ranked.length, 2);
+  assert.equal(ranked[0].downloadSpeed(), 5);
+});
+
+test("a throw from the library is raised, never swallowed", () => {
+  const torrent = {
+    wires: [wire({ speed: 1 })],
+    _request() {
+      throw new Error("internal");
+    }
+  };
+  assert.throws(() => askFastestWiresFor(torrent, 5), /could not place a request for piece 5/);
+});