@torrent-tv/proxy 2.67.0 → 2.68.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.68.0
+
+- **Fix**: The background fetch of a soundtrack now stands aside after a stall, not only during one. Pausing only while a reader is blocked is not enough on a swarm with no surplus: between stalls the fetch still takes bandwidth the picture needs, and the stalls themselves are the proof there was none to spare. Field 2026-08-31 — the swarm delivered 200-600 KB/s against the 399 KB/s the film eats, one piece waited 101 s after a seek, and the picture stood still 145.6 s before the player gave up. A chunk is fetched only when the stall count has not moved since the previous one, re-baselined after each quiet pause so it can resume; on a starving swarm it stops altogether, which is the right answer.
+- **Chore**: `piece-reader.js` counts the stalls a torrent's readers have had, so work of lower importance can ask "did the viewer stall while I was busy?" — a stricter and more useful question than "is the viewer stalled right now".
+
 ## 2.67.0
 
 - **New**: A soundtrack or subtitle file shipped beside the picture is fetched WHOLE as soon as the viewer opens the episode, using only the room their own reading leaves. The ordering is the design: what plays now comes first — the picture at the playhead, the soundtrack being heard, the subtitles being shown — the other tracks next, and reading the film far ahead last. The middle tier stays below the first by a condition that is measured rather than chosen: it fetches only while NO reader on the torrent is inside a wait, re-asked before every piece, because a torrent that was healthy a moment ago is not evidence about the next second. A soundtrack is about a twentieth of the picture, and having it on disk is what turns a later switch into a local read: in the field on 2026-08-31 the first piece of one took 27.7 s to arrive, which is longer than a switch is willing to wait.

package/package.json

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

package/services/torrent-worker/background-fill.js

@@ -28,7 +28,7 @@
  */
 
 import { logger } from "../../utils/logger.js";
-import { readersAreBlockedOn } from "./piece-reader.js";
+import { readersAreBlockedOn, stallsSeenOn } from "./piece-reader.js";
 
 /**
  * How long to stand aside after finding the viewer's own reading blocked.
@@ -101,7 +101,7 @@ function readRange(file, start, end) {
  * @param {object} torrent
  * @param {number} fileIndex
  * @param {string} sourceKey
- * @param {{ chunkBytes?: number, isBlocked?: (infoHash: string) => boolean }} [options]
+ * @param {{ chunkBytes?: number, isBlocked?: (infoHash: string) => boolean, stallsSeen?: (infoHash: string) => number }} [options]
  *   `isBlocked` answers "is the viewer's own reading starving right now"; it is
  *   the tier boundary, and it is a parameter so it can be exercised without a
  *   swarm.
@@ -123,7 +123,8 @@ export function fillFileInBackground(torrent, fileIndex, sourceKey, options = {}
     ? options.chunkBytes
     : (Number(torrent?.pieceLength) || 4 * 1024 * 1024);
   const isBlocked = typeof options.isBlocked === "function" ? options.isBlocked : readersAreBlockedOn;
-  const work = fill(torrent, file, fileIndex, chunkBytes, isBlocked).finally(() => {
+  const stallsSeen = typeof options.stallsSeen === "function" ? options.stallsSeen : stallsSeenOn;
+  const work = fill(torrent, file, fileIndex, chunkBytes, isBlocked, stallsSeen).finally(() => {
     running.delete(key);
   });
   running.set(key, work);
@@ -136,25 +137,41 @@ export function fillFileInBackground(torrent, fileIndex, sourceKey, options = {}
  * @param {number} fileIndex
  * @param {number} chunkBytes
  * @param {(infoHash: string) => boolean} isBlocked
+ * @param {(infoHash: string) => number} stallsSeen
  * @returns {Promise<void>}
  */
-async function fill(torrent, file, fileIndex, chunkBytes, isBlocked) {
+async function fill(torrent, file, fileIndex, chunkBytes, isBlocked, stallsSeen) {
   const startedAt = Date.now();
   const infoHash = String(torrent?.infoHash ?? "");
   let read = 0;
   let stoodAsideMs = 0;
+  // The stall count this fill last saw. A chunk is fetched only when it has not
+  // moved since the previous one.
+  let quietSince = stallsSeen(infoHash);
   logger.info(
     `background-fill: "${String(file.name).slice(0, 40)}" (${(file.length / 1e6).toFixed(1)}MB) will be ` +
       "fetched whole while the viewer's own reading leaves room"
   );
   for (let start = 0; start < file.length; start += chunkBytes) {
-    // Stand aside for as long as anything the viewer is watching is waiting on
-    // the swarm. This is the tier boundary, and it is checked before every
-    // chunk rather than once at the beginning: a torrent that was healthy a
-    // moment ago is not evidence about the next second.
-    while (isBlocked(infoHash)) {
+    // Stand aside while anything the viewer is watching is waiting on the
+    // swarm — AND for as long after it as it takes for a quiet stretch to
+    // pass. Pausing only DURING a stall is not enough: on a swarm delivering
+    // exactly what the film needs, this still takes bandwidth between stalls,
+    // and the stalls themselves are the proof there was none to spare. Field
+    // 2026-08-31, the case that forced this: 200-600 KB/s delivered against
+    // the 399 KB/s the film eats, one piece waited 101 s, and the picture
+    // stood still 145.6 s.
+    //
+    // "A quiet stretch" is measured, not chosen: the stall counter must not
+    // have moved while the previous chunk was being fetched. On a starving
+    // swarm it moves constantly and this stops altogether, which is the right
+    // answer — there is no spare room to use.
+    while (isBlocked(infoHash) || stallsSeen(infoHash) !== quietSince) {
       stoodAsideMs += STAND_ASIDE_MS;
       await pause(STAND_ASIDE_MS);
+      // Re-baselined after the pause, so a stretch that passes without a new
+      // stall lets the fill go on. Without this it could never resume.
+      quietSince = stallsSeen(infoHash);
     }
     // The torrent may have been destroyed under us — a viewer who left, the
     // disk sweep, a restart. Reading a destroyed file throws, and there is
@@ -162,6 +179,11 @@ async function fill(torrent, file, fileIndex, chunkBytes, isBlocked) {
     if (!torrent?.files?.[fileIndex]) {
       return;
     }
+    // Taken BEFORE the read, and deliberately not refreshed after it: a stall
+    // that happens while this chunk is in flight must still be visible to the
+    // next iteration. Refreshing afterwards erased exactly that evidence, which
+    // is the defect a test caught here.
+    quietSince = stallsSeen(infoHash);
     const bytes = await readRange(file, start, Math.min(start + chunkBytes, file.length) - 1);
     if (bytes === 0) {
       logger.info(

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

@@ -617,6 +617,14 @@ function describeSteering(key) {
  */
 const blockedReaders = new Map();
 
+/**
+ * How many stalls a torrent's readers have had, ever. Only differences between
+ * two readings of it mean anything.
+ *
+ * @type {Map<string, number>}
+ */
+const stallsSeen = new Map();
+
 /**
  * Whether any reader on this torrent is waiting for a piece right now.
  *
@@ -627,6 +635,25 @@ export function readersAreBlockedOn(infoHash) {
   return (blockedReaders.get(infoHash) ?? 0) > 0;
 }
 
+/**
+ * How many times a reader on this torrent has been blocked since the process
+ * started.
+ *
+ * Exists so that work of lower importance can ask "did the viewer stall while I
+ * was busy?" — which is a different and stricter question than "is the viewer
+ * stalled right now". On a swarm delivering exactly what the film needs, a
+ * background fetch that only pauses DURING a stall still takes bandwidth
+ * between them, and the stalls are the proof it had none to spare. Field
+ * 2026-08-31: the swarm delivered 200-600 KB/s against the 399 KB/s the film
+ * needs, and the picture stood still 145.6 s.
+ *
+ * @param {string} infoHash
+ * @returns {number}
+ */
+export function stallsSeenOn(infoHash) {
+  return stallsSeen.get(infoHash) ?? 0;
+}
+
 /**
  * @param {string} infoHash
  * @param {number} delta
@@ -636,6 +663,9 @@ function countBlockedReader(infoHash, delta) {
   if (!infoHash) {
     return;
   }
+  if (delta > 0) {
+    stallsSeen.set(infoHash, (stallsSeen.get(infoHash) ?? 0) + 1);
+  }
   const next = (blockedReaders.get(infoHash) ?? 0) + delta;
   if (next > 0) {
     blockedReaders.set(infoHash, next);

package/test/background-fill.test.js

@@ -154,3 +154,37 @@ test("the gate is re-asked before every chunk, not once at the start", async ()
   await waitFor(() => !fillIsRunning("source-f", 0));
   assert.equal(file.reads.length, 3);
 });
+
+test("a stall during a chunk makes the next one wait, not just a stall in progress", async () => {
+  // The case this exists for: a swarm delivering exactly what the film needs.
+  // Nothing is blocked at the moment the gate is asked, but the viewer stalled
+  // while the last chunk was in flight — which is the proof there was no room.
+  const file = fakeFile({ length: 12 });
+  const torrent = { infoHash: "ggg", pieceLength: 4, files: [file] };
+  let stalls = 0;
+  let starving = true;
+  // A stall happens DURING every chunk, exactly as it does on a swarm with no
+  // surplus — and nothing is blocked at the moment the gate is asked.
+  const originalRead = file.createReadStream.bind(file);
+  file.createReadStream = (range) => {
+    if (starving) {
+      stalls += 1;
+    }
+    return originalRead(range);
+  };
+
+  fillFileInBackground(torrent, 0, "source-g", {
+    chunkBytes: 4,
+    isBlocked: () => false,
+    stallsSeen: () => stalls
+  });
+
+  await waitFor(() => file.reads.length === 1);
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  assert.equal(file.reads.length, 1, "a stall during the chunk holds the next one back");
+
+  // The swarm settles: no further stalls, so it may go on.
+  starving = false;
+  await waitFor(() => !fillIsRunning("source-g", 0), 8000);
+  assert.equal(file.reads.length, 3);
+});