@torrent-tv/proxy 2.39.1 → 2.40.1

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2.40.1
+
+- **Fix**: The patched `utp-native` now replaces every copy in the tree, not just the top one. Installed at this package's own level, it left `webtorrent/node_modules/utp-native` untouched — and Node resolves from the requiring module outward, so WebTorrent went on loading the published build with the defect in it. The crash of 2026-08-19 21:03 names that exact path in frame 2, and every earlier one did too: the substitution shipped in 2.36.2 was never once in the loading path. `overrides` in this package's manifest now redirects the whole tree, npm applies it because a global install makes this package the root, and the addon image additionally deletes any nested copy and FAILS THE BUILD if a surviving `utp_native.node` belongs to another package. A silent fallback to the broken one is what made a fix that changed nothing look like a fix that worked.
+
+## 2.40.0
+
+- **New**: What a reader wants is claimed in four bands of decreasing urgency instead of one, and which way it claims is decided per read so the two can be compared on real viewing. Until now there was one band at priority 1 with WebTorrent's own whole-file selection at 0 beneath it, so "what the viewer reaches in seconds" and "the rest of the film" were the same thing to the picker. The bands are: what the viewer reaches in seconds, anchored at the first piece not already held; the near lead; the far lead; and, only once the lead has covered everything to the end of the file, whatever was never downloaded BEHIND the position — which a backward seek needs and which must never compete with the picture being watched. Priorities are 4, 3, 2, 1 and none of them zero, because zero is where the library's own background fill sits, and they are distinct because the library deliberately shuffles selections of equal non-zero priority against each other.
+- **New**: The widths of the lead bands are derived from what has been measured about this file on this swarm, not chosen. The near band covers the worst interruption this reader has actually met (`worst wait × the rate the consumer is taking bytes at`); the far band covers what the swarm can put ahead of the viewer between interruptions (`(download rate - consumption) × the median interval between them`). A swarm with no surplus produces no far band, which is right: there is nothing to get ahead with. The consumption rate is measured by the reader as it hands bytes over, so nothing has to be passed in or assumed about who is reading. Until two interruptions have been seen there are no figures and both bands fall back to the reader's own window, and the log says which of the two it is.
+- **New**: Every wait line names the mode it happened under and the bands as they stood (`mode=bands p4:340-352 p3:353-370 p2:371-500`), and the periodic supply summary compares the two arms directly — `flat N waits median Xms worst Yms, bands M waits median Zms worst Wms` — appearing only once both have samples. `TORRENT_TV_READ_MODE=flat|bands` pins one arm for a deployment that wants no alternation.
+- **New**: A wait is also recorded against whether the blocked piece was steered onto another peer at all, and the summary states both — `steered N waits median Xms, unsteered M waits median Yms`. The steering itself has been logged per wait since 2.29.0; what could not be read from it was what it bought, which is a difference between waits and not a property of one.
+
 ## 2.39.1
 
 - **Fix**: The block duplication of 2.39.0 is removed, because measured against what a viewer actually feels it never paid. 2.39.0 was shipped on a measurement of the median wait for a piece; the quantity that matters is the seconds the picture stands still, and measured on that (2026-08-19, a reader paced at the film's own byte rate with an eight-second lead, arms alternated per position) it is neutral at best and costly at worst. On a well-seeded film every arm read 67 MB in 59 s and stopped for at most 2.6 s — nothing to improve. With the download capped just above the film's rate, which is what a home line IS whenever the swarm can fill it, duplication made the picture stop for **28.8 s against 12.8 s** at one position and left the other unchanged: under one shared budget a duplicate spends the very bytes it is trying to go around. The regime where it could pay — several slow peers, each with capacity of its own — could not be reproduced: the thin-swarm candidate turned out to have no live swarm at all (4 peers, 179.5 s of a 209 s run spent stopped). A lever with no measured gain and a measured cost does not stay on by default. Narrowing the read window to the blocked piece was tried in the same experiment and is not shipped for the same reason: it was never better and reached **44.8 s against 12.8 s**. What stays is the measurement that decided it (`research/tail-duplication-2026-08-19.md`) and the `tail …` line from 2.38.1, which is what will say whether a real thin swarm ever behaves differently.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.39.1",
+  "version": "2.40.1",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -42,5 +42,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.7"
+  },
+  "overrides": {
+    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.1"
   }
 }

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

@@ -197,3 +197,83 @@ export function describePieceTail(torrent, pieceIndex) {
   outstanding.sort((left, right) => left.bytesPerSecond - right.bytesPerSecond);
   return { chunks, missing, outstanding };
 }
+
+/**
+ * Ask a second wire for blocks the reader is still waiting on.
+ *
+ * WebTorrent reserves each block for exactly one wire, so once `Piece.reserve()`
+ * answers -1 there is no request left to place and the read ends when the
+ * holder of the last block delivers it — however fast the rest of the swarm is.
+ * The library's own remedy is `_hotswap`, and it does precisely the right
+ * thing: `piece.cancel(blockIndex)` frees the reservation while leaving the
+ * first wire's request in flight, so a second wire can be asked for the same
+ * block and whichever arrives first wins. What it will not do is apply that to
+ * these tails. It is gated on speed — the held-up wire must be under 48 KB/s
+ * (`3 * BLOCK_LENGTH`) and at least twice as slow as the asker — and measured
+ * on a real swarm 2026-08-19, the tails a reader waits on sit at 109, 317 and
+ * 870 KB/s. Peers the library rightly considers good, because for bulk
+ * downloading they are; the gate is about throughput across a torrent and knows
+ * nothing about a reader blocked on one piece now.
+ *
+ * Speed is not even what is wrong with them: two blocks — 32 KB — on a wire
+ * measured at 109 KB/s is 0.3 s of transfer, and that read waited 4.6 s. The
+ * blocks are not travelling slowly, they are queued behind that wire's other
+ * work, which no average speed can show.
+ *
+ * The cost is bounded by the same measurement: the tails were 2 to 14 blocks of
+ * 512, so 32 to 224 KB against the 8 MiB piece they hold up. At most one
+ * duplicate is asked per candidate wire per call, and the caller repeats every
+ * half second, so a longer tail is covered across attempts rather than in one
+ * burst.
+ *
+ * Safe against the completion path: a block that arrives twice is dropped by
+ * `Piece.set`, which writes only into an empty slot, and a piece already
+ * flushed answers `false` from `Piece.init` so the second arrival returns
+ * before `flush()` is reached.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @returns {{ duplicated: number, missing: number, wires: number }}
+ *   `duplicated` counts requests the library actually placed for a block that
+ *   was already outstanding elsewhere.
+ */
+export function duplicateTailFor(torrent, pieceIndex) {
+  const piece = torrent?.pieces?.[pieceIndex];
+  const buffer = Array.isArray(piece?._buffer) ? piece._buffer : null;
+  if (!piece || !buffer || typeof piece.cancel !== "function") {
+    return { duplicated: 0, missing: 0, wires: 0 };
+  }
+  const chunks = Number.isFinite(piece._chunks) ? piece._chunks : buffer.length;
+  const missing = [];
+  for (let index = 0; index < chunks; index += 1) {
+    if (!buffer[index]) {
+      missing.push(index);
+    }
+  }
+  const candidates = wiresForPiece(torrent, pieceIndex);
+  if (missing.length === 0 || candidates.length === 0) {
+    return { duplicated: 0, missing: missing.length, wires: candidates.length };
+  }
+
+  let duplicated = 0;
+  // One block per wire: that is what the pipelines can usefully take at once,
+  // and it needs no number of its own.
+  for (let index = 0; index < Math.min(missing.length, candidates.length); index += 1) {
+    // Freeing the reservation is what makes the block askable again; the
+    // request already in flight is deliberately left alone, because the point
+    // is to have two of them.
+    piece.cancel(missing[index]);
+    // `false` is hotswap: the library's own swap must not run on top of this,
+    // or it would free a THIRD wire's block as well.
+    if (torrent._request(candidates[index], pieceIndex, false) === true) {
+      duplicated += 1;
+      continue;
+    }
+    // The wire's pipeline is full. The block stays in the piece's cancellation
+    // stack and will be handed to whoever asks next, which is harmless — it is
+    // already in flight elsewhere — but there is no point asking the remaining
+    // wires, whose pipelines are no emptier.
+    break;
+  }
+  return { duplicated, missing: missing.length, wires: candidates.length };
+}