@torrent-tv/proxy 2.83.2 → 2.83.3

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.83.3
+
+- **Fix**: LEAVING A SWARM IS NOW A CONSEQUENCE OF A DEPARTURE, not something a pass over every torrent decides. 2.83.1 asked every five seconds whether anybody was reading, and a torrent added three seconds earlier answered no — its edges still being read, its playback plan still being built — so it left its swarm with 741 connections let go and nothing rejoined it: rejoining waits for a reader, and the reader was waiting for the header the swarm had been fetching. 2.83.2 covered that with a state, "read at least once", which was a patch over the poll rather than a removal of it. The pair is now acted on where the facts happen: the last file claim being released lets the swarm go, and a claim being taken brings it back. A torrent nobody has read yet cannot leave one at all, because there is no longer anything that asks it to.
+- **Chore**: `leaveSwarm` and `rejoinSwarm` are functions of a torrent, like `decideUploadLimit` and `torrentsForUploadPolicy` beside them, so both can be exercised without building a pool — the previous shape could only be checked by faking one, and a fake pool is what hid the missing state in the first place.
+
 ## 2.83.2
 
 - **Fix**: 2.83.1 COULD NOT START PLAYBACK AT ALL, and the cause was its own new rule. A torrent nobody has stated anything about leaves its swarm — and a torrent that has just been added has stated nothing yet, because the read of the file's edges is still in flight and the playback plan is still being built. Field 2026-09-11: added at 20:57:17, first peer at 20:57:18, out of the swarm at 20:57:21 with 741 connections let go. Nothing ever rejoined it: rejoining waits for a reader, and the reader was waiting for the header the swarm had been fetching. `[stats]` then read `peers=0 connected of 0 known (94 queued, 5 tracker(s) offered up to 683 seeders)` for as long as the viewer was willing to wait.

package/package.json

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

package/services/torrent-pool.js

@@ -428,6 +428,83 @@ export function decideUploadLimit(activeTorrents, opts = {}) {
   return { bytesPerSec: floor, reason: "active readers, not choke-starved" };
 }
 
+/**
+ * Let go of the swarm of a torrent whose last reader has just left.
+ *
+ * A PROXY THAT NEEDS NOTHING FROM A SWARM SHOULD NOT BE IN THAT SWARM. While a
+ * file is being read every connection is worth keeping — the one that has
+ * delivered nothing yet may deliver next — so this is not a limit on
+ * connections and never fires during playback.
+ *
+ * What that state cost until now: WebTorrent enforces `maxConns` only on peers
+ * it dials (`_drain`), while `_addIncomingPeer` checks that the torrent is
+ * neither destroyed nor paused and registers the peer. A proxy with its port
+ * mapped is reachable, so connections arrive and are never turned away — field
+ * 2026-09-11, 249 connected at the start of one viewing and 596 at the end,
+ * 15 862 more queued, on a file complete for three quarters of an hour.
+ *
+ * CALLED FROM THE DEPARTURE ITSELF, not from a pass over every torrent. The
+ * first version asked every five seconds whether anybody was reading, and a
+ * torrent added three seconds earlier — its edges still being read, its
+ * playback plan still being built — answered no. It was taken out of its swarm
+ * with 741 connections let go, and nothing rejoined it: rejoining waits for a
+ * reader, and the reader was waiting for the header the swarm had been
+ * fetching. Playback did not start at all (2.83.1).
+ *
+ * Asked at the moment the last claim is released, leaving cannot happen
+ * spontaneously: it is a consequence of a departure, and a torrent nobody has
+ * read yet has nothing to depart from.
+ *
+ * `paused` is the library's own word for this and the path it already checks,
+ * so nothing here fights it. The pause alone does not close what is already
+ * open, so the peers are let go by hand; the data stays exactly where it is.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {number} Connections let go.
+ */
+export function leaveSwarm(torrent) {
+  if (!torrent || torrent.destroyed || torrent.paused === true) {
+    return 0;
+  }
+  torrent.pause();
+  const open = Array.isArray(torrent.wires) ? torrent.wires.length : 0;
+  let closed = 0;
+  for (const peer of [...(torrent._peers?.values?.() ?? [])]) {
+    try {
+      peer.destroy();
+      closed += 1;
+    } catch {
+      // A peer already going: nothing to do, and nothing worth failing for.
+    }
+  }
+  logger.info(
+    `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] left the swarm — its last reader went, ` +
+    `${open} connection(s) open, ${closed} let go; the data stays and the next reader rejoins`
+  );
+  return closed;
+}
+
+/**
+ * Take the swarm back for a torrent a reader has just arrived at.
+ *
+ * The other half of the pair: a departure lets a swarm go, an arrival takes it
+ * back. Both are acted on at the moment they happen, and neither is discovered
+ * by asking.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {boolean} Whether it had to be taken back.
+ */
+export function rejoinSwarm(torrent) {
+  if (!torrent || torrent.destroyed || torrent.paused !== true) {
+    return false;
+  }
+  torrent.resume();
+  logger.info(
+    `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] rejoined the swarm — a reader arrived`
+  );
+  return true;
+}
+
 /**
  * Compute the default disk cap: the smaller of a fixed 10 GB and half of the
  * currently free space on the store's filesystem (so a tiny host is never
@@ -938,88 +1015,6 @@ export class TorrentPool {
     this.#uploadAdjustTimer.unref?.();
   }
 
-  /**
-   * Leave the swarm of a torrent nobody is reading, and rejoin it when
-   * somebody is.
-   *
-   * A PROXY THAT NEEDS NOTHING FROM A SWARM SHOULD NOT BE IN THAT SWARM. While
-   * a file is being watched every connection is worth keeping — the one that
-   * has delivered nothing yet may deliver next — so this is not a limit on
-   * connections and never fires during playback. It fires when NOTHING is
-   * stated about this torrent at all: no window from any reader, no file held.
-   *
-   * What that state cost until now: WebTorrent enforces `maxConns` only on
-   * peers it dials (`_drain`), while `_addIncomingPeer` checks that the torrent
-   * is neither destroyed nor paused and registers the peer. A proxy with its
-   * port mapped is reachable, so connections arrive and are never turned away —
-   * field 2026-09-11, 249 connected at the start of one viewing and 596 at the
-   * end, 15 862 more queued, on a file complete for three quarters of an hour,
-   * each of them served by reading a 4 MB piece off the disk for every 16 KB
-   * sent.
-   *
-   * `paused` is the library's own word for this and the path it already checks,
-   * so nothing here fights it. The pause alone does not close what is already
-   * open, so the peers are let go by hand; the data stays exactly where it is,
-   * and the next reader resumes the torrent rather than fetching it again.
-   *
-   * @param {import("webtorrent").Torrent} torrent
-   * @returns {void}
-   */
-  followTheReaders(torrent) {
-    if (!torrent || torrent.destroyed) {
-      return;
-    }
-    const usage = this.fileUsageByTorrent.get(torrent);
-    const isRead = Boolean(usage && usage.size > 0);
-    if (isRead) {
-      // Recorded on the torrent, as `hasActiveReader` and `hasUnmetDemand`
-      // beside it are: it is a fact about this torrent and it lives as long as
-      // the torrent does.
-      torrent.hasBeenRead = true;
-    }
-    const isWanted = isRead || demandFor(torrent).register.windows().length > 0;
-    // A TORRENT NOBODY HAS READ YET IS BEING SET UP, NOT ABANDONED. Field
-    // 2026-09-11, and it broke playback outright: a torrent was added at
-    // 20:57:17, its first peer connected at 20:57:18, and this pass took it out
-    // of the swarm at 20:57:21 — while the read of the file's edges was still
-    // in flight and the playback plan was being built. Nothing rejoined it,
-    // because rejoining waits for a reader and a reader cannot arrive: the
-    // header it needs is downloaded by the swarm that was just let go.
-    //
-    // The condition is a state and not a period: having been read at least once
-    // is what tells a film somebody left from a film nobody has opened yet. One
-    // that is never read at all goes by the pool's own idle removal, which is
-    // where that belongs.
-    if (!isWanted && torrent.hasBeenRead !== true) {
-      return;
-    }
-    if (isWanted && torrent.paused === true) {
-      torrent.resume();
-      logger.info(
-        `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] rejoined the swarm — somebody is reading it again`
-      );
-      return;
-    }
-    if (isWanted || torrent.paused === true) {
-      return;
-    }
-    torrent.pause();
-    const open = Array.isArray(torrent.wires) ? torrent.wires.length : 0;
-    let closed = 0;
-    for (const peer of [...(torrent._peers?.values?.() ?? [])]) {
-      try {
-        peer.destroy();
-        closed += 1;
-      } catch {
-        // A peer already going: nothing to do, and nothing worth failing for.
-      }
-    }
-    logger.info(
-      `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] left the swarm — nobody is reading it, ` +
-      `${open} connection(s) open, ${closed} let go; the data stays and the next reader rejoins`
-    );
-  }
-
   /**
    * Re-evaluate and apply the client-wide upload limit from current swarm state
    * (see {@link decideUploadLimit}). Runs on a timer; only calls into WebTorrent
@@ -1352,9 +1347,6 @@ export class TorrentPool {
       this.#stateBackgroundFill(torrent);
     }
     this.#reportStalledDownloads();
-    for (const torrent of this.torrents.values()) {
-      this.followTheReaders(torrent);
-    }
     const { bytesPerSec, reason } = decideUploadLimit(active);
     if (bytesPerSec === this.#uploadLimit) {
       return;
@@ -1769,15 +1761,10 @@ export class TorrentPool {
     // it recently accessed so LRU eviction keeps it.
     this.#cancelIdleRemoval(torrent);
     this.#lastAccess.set(torrent, Date.now());
-    // And rejoin its swarm HERE rather than at the next five-second pass: a
-    // reader that has just arrived is about to ask for bytes, and a torrent
-    // still paused answers by fetching nothing at all.
-    if (torrent.paused === true) {
-      torrent.resume();
-      logger.info(
-        `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] rejoined the swarm — a reader arrived`
-      );
-    }
+    // AND REJOIN ITS SWARM, which is the other half of the pair: a departure
+    // lets a swarm go, an arrival takes it back. Both are acted on at the
+    // moment they happen, and neither is discovered by asking.
+    rejoinSwarm(torrent);
     usage.set(fileIndex, (usage.get(fileIndex) ?? 0) + 1);
 
     let released = false;
@@ -1796,6 +1783,8 @@ export class TorrentPool {
         this.fileUsageByTorrent.delete(torrent);
         // No active readers — schedule removal (with store) after an idle TTL.
         this.#scheduleIdleRemoval(torrent);
+        // THE READER LEFT, AND THAT IS THE ONLY MOMENT A SWARM MAY BE LET GO.
+        leaveSwarm(torrent);
       }
       };
   }

package/test/swarm-follows-readers.test.js

@@ -3,21 +3,25 @@
  *
  * WebTorrent enforces `maxConns` only on peers it dials (`_drain`), while
  * `_addIncomingPeer` checks that the torrent is neither destroyed nor paused
- * and registers the peer. A proxy with its port mapped is reachable, so
- * connections arrive and are never turned away — field 2026-09-11: 249
- * connected at the start of one viewing, 596 at the end, 15 862 more queued, on
- * a file that had been complete for three quarters of an hour, each connection
- * served by reading a 4 MB piece off the disk for every 16 KB sent.
+ * and registers the peer. A proxy with its port mapped is reachable, so on a
+ * popular torrent connections arrive and are never turned away — field
+ * 2026-09-11: 249 connected at the start of one viewing, 596 at the end, 15 862
+ * more queued, on a file complete for three quarters of an hour.
  *
- * The rule is not a limit on connections. While anybody is reading, every
- * connection is worth keeping: the one that has delivered nothing yet may
- * deliver next. It is about a torrent nobody is reading at all.
+ * The rule is not a limit on connections. While anybody is reading, every one is
+ * worth keeping: the one that has delivered nothing yet may deliver next.
+ *
+ * AND IT IS ACTED ON AT THE DEPARTURE ITSELF. The first version asked every
+ * five seconds whether anybody was reading, and a torrent added three seconds
+ * earlier answered no — its edges still being read, its plan still being built.
+ * It left the swarm with 741 connections let go, and nothing rejoined it:
+ * rejoining waits for a reader, and the reader was waiting for the header the
+ * swarm had been fetching. Playback did not start at all.
  */
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { TorrentPool } from "../services/torrent-pool.js";
-import { demandFor, forgetTorrent } from "../services/download/registry.js";
+import { leaveSwarm, rejoinSwarm } from "../services/torrent-pool.js";
 
 /**
  * A torrent that records what was done to it. Only the surface the rule
@@ -39,7 +43,7 @@ function torrentWith(peerCount) {
   }
   return {
     infoHash: "f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0",
-    files: [{ length: 1024 }],
+    files: [{ length: 1024 }, { length: 2048 }],
     paused: false,
     wires: [...peers.values()].map((peer) => peer.wire),
     _peers: peers,
@@ -52,117 +56,37 @@ function torrentWith(peerCount) {
   };
 }
 
-/**
- * @param {object} torrent
- * @returns {TorrentPool}
- */
-function poolWith(torrent) {
-  const pool = Object.create(TorrentPool.prototype);
-  pool.torrents = new Map([["source", torrent]]);
-  pool.fileUsageByTorrent = new WeakMap();
-  return pool;
-}
-
-test("a torrent nobody is reading is let go of, and its data is not", () => {
+test("letting a swarm go pauses the torrent and closes what the pause does not", () => {
   const torrent = torrentWith(6);
-  const pool = poolWith(torrent);
-  try {
-    // Read once and left, which is the state this is about: a film nobody has
-    // opened yet is being set up, and the test below covers that.
-    pool.fileUsageByTorrent.set(torrent, new Map([[0, 1]]));
-    pool.followTheReaders(torrent);
-    pool.fileUsageByTorrent.set(torrent, new Map());
-    pool.followTheReaders(torrent);
 
-    assert.equal(torrent.paused, true, "the swarm was not left");
-    assert.equal(torrent._peers.size, 0, "the connections the pause does not close were not let go");
-  } finally {
-    forgetTorrent(torrent);
-  }
-});
+  const closed = leaveSwarm(torrent);
 
-test("a torrent somebody is reading keeps every connection it has", () => {
-  const torrent = torrentWith(6);
-  const pool = poolWith(torrent);
-  pool.fileUsageByTorrent.set(torrent, new Map([[0, 1]]));
-  try {
-    pool.followTheReaders(torrent);
-
-    assert.equal(torrent.paused, false, "a torrent being read was taken out of its swarm");
-    assert.equal(torrent._peers.size, 6, "connections were closed while somebody was reading");
-  } finally {
-    forgetTorrent(torrent);
-  }
+  assert.equal(torrent.paused, true, "the library's own word for this was not used");
+  assert.equal(closed, 6);
+  assert.equal(torrent._peers.size, 0, "the connections the pause does not close were not let go");
 });
 
-test("a stated window keeps the swarm even with no file held", () => {
-  // The register is what the download layer states; a reader that has declared
-  // a window but not yet taken a file hold is still a reader.
-  const torrent = torrentWith(2);
-  const pool = poolWith(torrent);
-  demandFor(torrent).register.state({
-    claimant: "read-1",
-    fileIndex: 0,
-    byteStart: 0,
-    byteEnd: 1023,
-    urgency: 0
-  });
-  try {
-    pool.followTheReaders(torrent);
-    assert.equal(torrent.paused, false, "a declared window did not count as somebody reading");
-  } finally {
-    forgetTorrent(torrent);
-  }
+test("a swarm already let go is not let go twice", () => {
+  const torrent = torrentWith(4);
+  leaveSwarm(torrent);
+  assert.equal(leaveSwarm(torrent), 0);
 });
 
-test("the swarm is rejoined when a reader comes back", () => {
+test("the reader that comes back takes the swarm with it", () => {
   const torrent = torrentWith(3);
-  const pool = poolWith(torrent);
-  try {
-    pool.fileUsageByTorrent.set(torrent, new Map([[0, 1]]));
-    pool.followTheReaders(torrent);
-    pool.fileUsageByTorrent.set(torrent, new Map());
-    pool.followTheReaders(torrent);
-    assert.equal(torrent.paused, true);
+  leaveSwarm(torrent);
 
-    pool.fileUsageByTorrent.set(torrent, new Map([[0, 1]]));
-    pool.followTheReaders(torrent);
-    assert.equal(torrent.paused, false, "the next reader was left with a torrent that fetches nothing");
-  } finally {
-    forgetTorrent(torrent);
-  }
+  assert.equal(rejoinSwarm(torrent), true);
+  assert.equal(torrent.paused, false, "the next reader was left with a torrent that fetches nothing");
+  assert.equal(rejoinSwarm(torrent), false, "a torrent already in its swarm was resumed again");
 });
 
-test("a torrent nobody has read yet is being set up, and is left alone", () => {
-  // Field 2026-09-11, and it broke playback outright: a torrent added at
-  // 20:57:17 had its first peer at 20:57:18 and was taken out of the swarm at
-  // 20:57:21 — while the read of the file's edges was still in flight. Nothing
-  // rejoined it, because rejoining waits for a reader and the reader was
-  // waiting for the header the swarm was fetching.
+test("a torrent nobody has read yet is never asked to leave", () => {
+  // The field failure of 2026-09-11 is closed by WHERE this is called from, not
+  // by anything inside it: leaving is a consequence of the last claim being
+  // released, and a torrent being opened has released nothing. There is no pass
+  // that can ask it.
   const torrent = torrentWith(103);
-  const pool = poolWith(torrent);
-  try {
-    pool.followTheReaders(torrent);
-    assert.equal(torrent.paused, false, "a torrent being opened was taken out of its swarm");
-    assert.equal(torrent._peers.size, 103, "and its connections were let go");
-  } finally {
-    forgetTorrent(torrent);
-  }
-});
-
-test("once it has been read, leaving is allowed again", () => {
-  const torrent = torrentWith(4);
-  const pool = poolWith(torrent);
-  try {
-    // A reader arrives and goes.
-    pool.fileUsageByTorrent.set(torrent, new Map([[0, 1]]));
-    pool.followTheReaders(torrent);
-    assert.equal(torrent.paused, false);
-
-    pool.fileUsageByTorrent.set(torrent, new Map());
-    pool.followTheReaders(torrent);
-    assert.equal(torrent.paused, true, "a film somebody left keeps its swarm for nobody");
-  } finally {
-    forgetTorrent(torrent);
-  }
+  assert.equal(torrent.paused, false);
+  assert.equal(torrent._peers.size, 103);
 });