@torrent-tv/proxy 2.71.0 → 2.71.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.71.1
+
+- **Fix**: A reader stated the same thing twice — `protectRange` to the piece store for memory, and a window to the torrent for download — and the two were separate lists that could drift. There is one statement now: `SwarmSelection.reconcile` derives both views from the register, so the swarm and the store are told what to do from the same words. Only the urgent levels reach memory: it holds what will be READ soon, and protecting the speculative tail would push out a piece the decoder is about to want.
+- **New**: A file this machine cannot sustain at ANY height is refused rather than served badly. Both offered lists empty means not even copying the picture — which costs no encoder at all — can keep up, so a session made there produces a slideshow and takes the swarm and the processor from whoever is already watching. Field 2026-08-28: five sessions on one file put every rung at 0.04x of realtime. The plan now carries `cannotServe` with the reason, which is a different thing from a spinner that never ends.
+- **Chore**: `SwarmSelection` takes its store lookup as a parameter, so the memory projection is driven by a test without constructing a real piece store.
+
 ## 2.71.0
 
 - **Fix**: The torrent thread's log lines never reached the log file. A worker thread loads its own instance of every module, so the logger's file handle — set once, on the main thread — was null there for the life of the process. Measured over a whole 49 938-line file: zero lines from the piece reader and zero from the torrent pool, against 52 and 36 of them in the container's output, which every release destroys. That is why the comparison of the two claim strategies could never be read: it was being printed into a place we wipe ourselves. The worker now sends its lines to the main thread, which is the only writer — two threads appending to one file would race on the rotation and could interleave mid-line.

package/package.json

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

package/services/download/SwarmSelection.js

@@ -29,6 +29,7 @@ import {
   Urgency,
   urgencyName
 } from "../demand/index.js";
+import { findSharedStore } from "../piece-store/shared-piece-store.js";
 
 export class SwarmSelection {
   #torrent;
@@ -37,15 +38,22 @@ export class SwarmSelection {
   #stated = new Map();
   /** Pieces this instance marked for displacement, so it clears only its own. */
   #displacing = null;
+  /** Claimants whose windows are currently protected in memory. */
+  #protectedInMemory = new Set();
+  #findStore;
 
   /**
    * @param {object} params
    * @param {import("webtorrent").Torrent} params.torrent
    * @param {import("../demand/index.js").DemandRegister} params.register
+   * @param {(torrent: object) => object | null} [params.findStore] - How the
+   *   piece store is reached. Injectable so a test can drive the memory
+   *   projection without constructing a real store.
    */
-  constructor({ torrent, register }) {
+  constructor({ torrent, register, findStore = findSharedStore }) {
     this.#torrent = torrent;
     this.#register = register;
+    this.#findStore = findStore;
   }
 
   /**
@@ -107,6 +115,7 @@ export class SwarmSelection {
     }
 
     this.#markDisplacement();
+    this.#projectIntoMemory();
     return { stated, withdrawn };
   }
 
@@ -117,6 +126,11 @@ export class SwarmSelection {
     }
     this.#stated.clear();
     this.#clearDisplacement();
+    const store = this.#findStore(this.#torrent);
+    for (const claimant of this.#protectedInMemory) {
+      store?.releaseProtection?.(claimant);
+    }
+    this.#protectedInMemory.clear();
   }
 
   /**
@@ -182,6 +196,46 @@ export class SwarmSelection {
     }
   }
 
+  /**
+   * Tell the piece store which bytes will be read soon, from the same stated
+   * needs the swarm is told about.
+   *
+   * The second half of stating a need once. Until 2026-09-02 a reader said the
+   * same thing twice — `protectRange` to the store for memory and a selection
+   * to the torrent for download — and a third piece of code read the first to
+   * rebuild the second. Now there is one statement and two views of it, both
+   * computed here.
+   *
+   * Only the urgent levels. Memory holds what will be READ soon; the tail and
+   * the gap behind the playhead are fetched speculatively and must not push a
+   * piece the decoder is about to want out of memory.
+   *
+   * @returns {void}
+   */
+  #projectIntoMemory() {
+    const store = this.#findStore(this.#torrent);
+    if (!store || typeof store.protectRange !== "function") {
+      return;
+    }
+    const holding = new Set();
+    for (const urgency of [Urgency.BLOCKED, Urgency.NEAR, Urgency.AHEAD]) {
+      for (const window of this.#register.at(urgency)) {
+        const range = this.#piecesFor(window);
+        if (!range) {
+          continue;
+        }
+        store.protectRange(window.claimant, range.from, range.to);
+        holding.add(window.claimant);
+      }
+    }
+    for (const claimant of this.#protectedInMemory) {
+      if (!holding.has(claimant)) {
+        store.releaseProtection?.(claimant);
+      }
+    }
+    this.#protectedInMemory = holding;
+  }
+
   /** @returns {void} */
   #clearDisplacement() {
     if (!this.#displacing || !Array.isArray(this.#torrent._critical)) {

package/services/piece-store/shared-piece-store.js

@@ -373,6 +373,8 @@ export class SharedPieceStore {
   #blocksAllocated = 0;
   /** Whether a reader has ever declared a window here. See `wantedBytes`. */
   #everHadReader = false;
+  /** Whether the last revision had to exceed the machine's share. */
+  #beyondTheMachine = false;
   /**
    * How long a block sat free before it was taken again, in milliseconds.
    * Bounded, because what is wanted is the longest gap of RECENT work: an
@@ -467,6 +469,19 @@ export class SharedPieceStore {
     };
   }
 
+  /**
+   * Whether the machine's share of memory is smaller than one reader's window.
+   *
+   * The store holds the window anyway — refusing would leave the read it is
+   * serving unable to finish, which is worse — but it is the honest measure of
+   * "this machine cannot take any more", and it is measured rather than
+   * guessed: it is the last revision's own comparison of what the machine
+   * allowed against what the widest reader declared.
+   */
+  get isBeyondTheMachine() {
+    return this.#beyondTheMachine;
+  }
+
   /** What this store holds right now, in bytes. */
   get residentBytes() {
     return this.#buffers.size * this.#chunkLength;
@@ -527,6 +542,7 @@ export class SharedPieceStore {
     const belowAWindow = demand.readers > 0
       && Number.isFinite(wanted)
       && wanted < demand.widestPieces;
+    this.#beyondTheMachine = belowAWindow;
     // The LRU is told too. It was constructed with the store's original
     // capacity and never revised, so `isFull()` answered against a number that
     // had not been the limit for some time — dormant only because nothing calls

package/services/playback-planner.js

@@ -475,7 +475,7 @@ export function createPlaybackPlanner({
   }
 
   function withHostTimings(plan) {
-    return {
+    const withOffer = {
       ...plan,
       expectedFirstSegmentMs: expectedFirstSegmentMs?.() ?? null,
       expectedSessionCreateMs: expectedSessionCreateMs?.() ?? null,
@@ -490,6 +490,20 @@ export function createPlaybackPlanner({
         : null,
       mediaInfoForOffer: undefined
     };
+    // Refused rather than served badly. Both lists empty means this machine
+    // cannot sustain this file at ANY height — not even by copying the picture,
+    // which costs no encoder at all — so a session made here would produce a
+    // slideshow and take the swarm and the processor from whoever is already
+    // watching. Field 2026-08-28: five sessions on one file put every rung at
+    // 0.04x of realtime and the viewer watched one before the process was
+    // killed. The viewer is told why, which is a different thing from a spinner
+    // that never ends.
+    const offer = withOffer.offeredHeights;
+    if (offer && offer.copy.length === 0 && offer.transcode.length === 0) {
+      withOffer.cannotServe =
+        "This proxy cannot keep up with this file at any quality right now.";
+    }
+    return withOffer;
   }
 
   return {

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

@@ -861,14 +861,13 @@ export async function* readFragments({
     for (const band of wanted) {
       stateBand(band);
     }
+    // One call, and it does both: the swarm is told what to fetch and the store
+    // is told what will be read soon, from the same stated needs. The store used
+    // to be told separately here, which made the same intent two lists that
+    // could drift.
     selection.reconcile();
     claimed = wanted;
     window = next;
-    // Tell the store these pieces are wanted, so it evicts something else.
-    // Without it the piece the decoder reads next looks exactly as stale as one
-    // the encoder fetched forty minutes ahead, and the second kind is what
-    // fills the store while the encoder runs ahead of the viewer.
-    store.protectRange?.(readerId, next.from, next.to);
     if (isJump) {
       waitBelongsToJump = true;
       // A jump — a seek, not the window sliding along — can land on pieces that
@@ -1200,9 +1199,8 @@ export async function* readFragments({
     if (blockedStated) {
       register.withdraw(`${readerId}:${urgencyName(Urgency.BLOCKED)}`);
     }
-    store.releaseProtection?.(readerId);
-    // The swarm is told once, after everything has been withdrawn, so it is not
-    // asked to reconcile four times on the way out.
+    // Once, after everything has been withdrawn — and it releases this reader's
+    // hold on memory as well, because both views come from the same statement.
     selection.reconcile();
   }
 }

package/test/swarm-selection.test.js

@@ -26,6 +26,7 @@ function stubTorrent({ have = [], files = 1 } = {}) {
   const items = [];
   return {
     pieceLength: PIECE,
+    store: null,
     files: Array.from({ length: files }, (unused, index) => ({
       offset: index * 10 * PIECE,
       length: 10 * PIECE
@@ -189,3 +190,31 @@ test("releasing everything leaves the library holding nothing of ours", () => {
   assert.equal(selection.statedRanges().length, 0);
   assert.equal(torrent._critical.some((marked) => marked === true), false);
 });
+
+test("the store is told what will be read soon, from the same stated needs", () => {
+  const torrent = stubTorrent();
+  const protectedBy = new Map();
+  torrent.store = {
+    protectRange: (claimant, from, to) => protectedBy.set(claimant, `${from}-${to}`),
+    releaseProtection: (claimant) => protectedBy.delete(claimant)
+  };
+  const register = new DemandRegister();
+  const selection = new SwarmSelection({ torrent, register, findStore: () => torrent.store });
+
+  register.state({ claimant: "video", fileIndex: 0, byteStart: 0, byteEnd: PIECE - 1, urgency: Urgency.NEAR });
+  register.state({ claimant: "fill", fileIndex: 0, byteStart: 5 * PIECE, byteEnd: 9 * PIECE - 1, urgency: Urgency.TAIL });
+  selection.reconcile();
+
+  // One statement, two views of it. Until 2026-09-02 a reader said the same
+  // thing twice — once to the store for memory, once to the torrent for
+  // download — and a third piece of code read the first to rebuild the second.
+  assert.equal(protectedBy.get("video"), "0-0");
+  // But only the urgent levels: memory holds what will be READ soon, and the
+  // tail is fetched speculatively. Protecting it would push out a piece the
+  // decoder is about to want.
+  assert.equal(protectedBy.has("fill"), false);
+
+  register.withdraw("video");
+  selection.reconcile();
+  assert.equal(protectedBy.size, 0, "a reader that withdrew still held memory");
+});