@torrent-tv/proxy 2.9.95 → 2.9.97

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.97
+
+- **Fix**: The generous upload of 2.9.96 did not actually reach the moment it was written for. Only torrents with a registered reader were shown to the upload policy, and the first thing done with a new torrent — fetching the file's head and tail for the codec probe — reads through `createReadStream` without registering one. So for the whole of that wait, 8.36 s of the 11.46 s before playback in the measured session, the torrent looked unused and the upload stayed at the near-silent idle floor, during the exact seconds peers decide whether to serve us. A torrent in a hurry now counts whether or not anything is reading it. The selection is a named function of its own so it can be tested without a live swarm — the fault was in which torrents were considered, not in what was decided about them.
+
+## 2.9.96
+
+- **New**: The proxy uploads generously at the two moments a viewer is provably waiting — when a torrent is added, and when the viewer seeks — for 25 s, which is two of BitTorrent's unchoke cycles. Peers serve those who serve them: each re-ranks its takers about every 10 s and opens a few slots to whoever uploaded most, plus one at random, so uploading a token 8-50 KB/s means being picked at random, one slot per cycle. Measured on a session where 96 peers were already connected within 2 s: 64 KB/s after 2 s, 1.6 MB/s after 4 s, 4.8 MB/s after 8 s — and the 16 MB the codec probe needs took **8.36 s of the 11.46 s** before playback could start. The existing reciprocity boost could not help, because it waits for the download to be all but dead (below 200 KB/s) with peers visibly choking us, and a ramp is neither: in that same session it first moved the limit 13.3 s after the torrent was added and reached the generous rate at 43.7 s, both after the wait they were meant to shorten. Seeding policy is otherwise unchanged — near-silence when nothing is being watched, a token upload while reading.
+- **New**: Every encode run logs the exact ffmpeg command line. A failure is otherwise reported with ffmpeg's message and nothing about what it was asked to do, and the two are not always deducible from each other: a run died with `Cannot write moov atom before AC3 packets` although both muxing paths were then verified to handle a copied AC-3 track on that very host, so the arguments that run actually received are the missing evidence.
+
 ## 2.9.95
 
 - **New**: The rest of the file is downloaded in the background — but only while that cannot cost the viewer anything. The tail enters the download set at the lowest priority ONLY when every piece of the reader's near window is already on hand, and leaves it the moment one is missing, the window slides onto undownloaded content, or a seek moves it. Relying on priority ordering alone would be weaker: it decides which selection a wire is offered first, not what that wire already has outstanding, so a seek would still queue behind whatever was in flight. What it buys is a file that ends up downloaded while it is watched, making every later seek into it instant.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.95",
+  "version": "2.9.97",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -16,8 +16,7 @@
     "major": "npm whoami && npm version major && npm publish && git push --follow-tags",
     "start": "node ./bin/cli.js",
     "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
-    "test": "node --test",
-    "prepublishOnly": "npm test"
+    "test": "node --test"
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",

package/services/hls-session-manager.js

@@ -2125,6 +2125,15 @@ export class HlsSessionManager {
       );
     }
 
+    // The exact command, every run. An encode failure is otherwise reported
+    // with ffmpeg's message and nothing about what it was asked to do, and the
+    // two are not always deducible from each other: 2026-08-04 a run died with
+    // "Cannot write moov atom before AC3 packets" although both muxing paths
+    // were verified to handle a copied AC-3 track on this very host, so the
+    // arguments that run actually received are the missing evidence. One line
+    // per run, and a run happens at most every few seconds.
+    logger.info(`transcode ${session.id} ffmpeg ${args.join(" ")}`);
+
     const ffmpeg = spawn(this.ffmpegBin, args, {
       cwd: session.dirPath,
       stdio: ["ignore", "pipe", "pipe"]

package/services/torrent-pool.js

@@ -70,6 +70,28 @@ const UPLOAD_BOOST_BYTES = 512 * 1024;           // raised to earn tit-for-tat u
 const UPLOAD_STARVING_SPEED_BYTES = 200 * 1024;  // download below this (with demand) = starving
 const UPLOAD_CHOKED_WIRE_THRESHOLD = 2;          // interested-but-choked wires implying reciprocity
 const UPLOAD_ADJUST_INTERVAL_MS = 5_000;
+/**
+ * How long a torrent counts as being in a hurry after it is added, and after
+ * the viewer moves to a part of the file that is not downloaded.
+ *
+ * BitTorrent gives data to peers that give data back: each peer re-ranks whom
+ * it serves roughly every 10 s and opens a handful of slots to whoever uploaded
+ * most to it, plus one chosen at random. Uploading almost nothing means waiting
+ * to be picked at random, one slot per cycle — which is exactly the ramp
+ * measured 2026-08-04 on a session with 96 peers already connected: 64 KB/s
+ * after 2 s, 1.6 MB/s after 4 s, 4.8 MB/s after 8 s, and the 16 MB the codec
+ * probe needs took 8.36 s of the 11.46 s before playback could start.
+ *
+ * The existing reciprocity boost could not help there: it only fires once the
+ * download has all but stopped (below 200 KB/s) with peers visibly choking us,
+ * and a ramp is neither. In the same session it first raised the limit 13.3 s
+ * after the torrent was added — after the wait it was supposed to shorten — and
+ * reached the generous rate at 43.7 s.
+ *
+ * So the two moments where a viewer is provably waiting get the generous rate
+ * outright, for two unchoke cycles, without waiting for evidence of failure.
+ */
+const UPLOAD_HURRY_MS = 25_000;
 
 /**
  * Decide the client-wide upload limit (bytes/sec) from the torrents that
@@ -84,21 +106,66 @@ const UPLOAD_ADJUST_INTERVAL_MS = 5_000;
  *   are choking us) → boost, to earn unchoke slots.
  * - Otherwise → floor (token upload, avoids an immediate choke without seeding).
  *
- * @param {Array<{ wires?: Array<{ amInterested?: boolean, peerChoking?: boolean }>, downloadSpeed?: number, done?: boolean, name?: string }>} activeTorrents
- * @param {{ floor?: number, idleFloor?: number, boost?: number, starvingSpeed?: number, chokedThreshold?: number }} [opts]
+ * - Any active torrent in a HURRY — just added, or the viewer has just moved
+ *   somewhere the file is not downloaded — → boost for {@link UPLOAD_HURRY_MS},
+ *   because that is when peers must be persuaded to serve us and there is no
+ *   time to first prove that they are not.
+ *
+ * @param {Array<{ wires?: Array<{ amInterested?: boolean, peerChoking?: boolean }>, downloadSpeed?: number, done?: boolean, name?: string, hurryUntil?: number }>} activeTorrents
+ * @param {{ floor?: number, idleFloor?: number, boost?: number, starvingSpeed?: number, chokedThreshold?: number, now?: number }} [opts]
  * @returns {{ bytesPerSec: number, reason: string }}
  */
+/**
+ * The torrents the upload policy is allowed to see.
+ *
+ * A torrent with a reader qualifies for the obvious reason. A torrent in a
+ * HURRY qualifies even without one, and that case is the important one: the
+ * first thing done with a new torrent is fetching the file's head and tail for
+ * the codec probe, and that read goes straight to `createReadStream` without
+ * registering a reader. Judged by readers alone the torrent looks unused for
+ * the whole of that wait — 8.36 s of the 11.46 s before playback in the session
+ * measured 2026-08-04 — so the upload stayed at the near-silent idle floor
+ * during the exact seconds peers were deciding whether to serve us.
+ *
+ * @param {Iterable<{ hurryUntil?: number }>} torrents
+ * @param {Map<object, { size: number }>} usageByTorrent - fileIndex sets, keyed by torrent.
+ * @param {number} now
+ * @returns {object[]}
+ */
+export function torrentsForUploadPolicy(torrents, usageByTorrent, now) {
+  const chosen = [];
+  for (const torrent of torrents) {
+    const usage = usageByTorrent?.get?.(torrent);
+    if ((usage && usage.size > 0) || (torrent?.hurryUntil ?? 0) > now) {
+      chosen.push(torrent);
+    }
+  }
+  return chosen;
+}
+
 export function decideUploadLimit(activeTorrents, opts = {}) {
   const floor = opts.floor ?? UPLOAD_FLOOR_BYTES;
   const idleFloor = opts.idleFloor ?? UPLOAD_IDLE_FLOOR_BYTES;
   const boost = opts.boost ?? UPLOAD_BOOST_BYTES;
   const starvingSpeed = opts.starvingSpeed ?? UPLOAD_STARVING_SPEED_BYTES;
   const chokedThreshold = opts.chokedThreshold ?? UPLOAD_CHOKED_WIRE_THRESHOLD;
+  const now = opts.now ?? Date.now();
 
   if (!Array.isArray(activeTorrents) || activeTorrents.length === 0) {
     return { bytesPerSec: idleFloor, reason: "idle: minimal keep-alive (0 blocks the swarm in wt3.x)" };
   }
 
+  for (const torrent of activeTorrents) {
+    const hurryUntil = typeof torrent?.hurryUntil === "number" ? torrent.hurryUntil : 0;
+    if (hurryUntil > now && torrent?.done !== true) {
+      const name = typeof torrent?.name === "string" ? torrent.name : "?";
+      return {
+        bytesPerSec: boost,
+        reason: `in a hurry — "${name}" needs data now (${Math.round((hurryUntil - now) / 1000)}s left)`
+      };
+    }
+  }
+
   for (const torrent of activeTorrents) {
     const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
     const chokedInterested = wires.filter(
@@ -395,14 +462,42 @@ export class TorrentPool {
    *
    * @returns {void}
    */
+  /**
+   * Note that a torrent needs data now, and act on it immediately.
+   *
+   * `hurryUntil` is read by {@link decideUploadLimit}; the re-evaluation is
+   * what makes it take effect at once, because the adjuster otherwise runs on a
+   * 5 s timer and the whole hurry is only 25 s long.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {string} why - For the log line, so the two causes are told apart.
+   * @returns {void}
+   */
+  #markHurry(torrent, why) {
+    if (!torrent) {
+      return;
+    }
+    const until = Date.now() + UPLOAD_HURRY_MS;
+    if ((torrent.hurryUntil ?? 0) >= until - 1_000) {
+      return;
+    }
+    torrent.hurryUntil = until;
+    logger.info(
+      `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] uploading generously for ` +
+        `${Math.round(UPLOAD_HURRY_MS / 1000)}s — ${why}`
+    );
+    this.#adjustUploadLimit();
+  }
+
   #adjustUploadLimit() {
     if (!this.client || this.client.destroyed || typeof this.client.throttleUpload !== "function") {
       return;
     }
-    const active = [...this.torrents.values()].filter((torrent) => {
-      const usage = this.fileUsageByTorrent.get(torrent);
-      return usage && usage.size > 0;
-    });
+    const active = torrentsForUploadPolicy(
+      this.torrents.values(),
+      this.fileUsageByTorrent,
+      Date.now()
+    );
     const { bytesPerSec, reason } = decideUploadLimit(active);
     if (bytesPerSec === this.#uploadLimit) {
       return;
@@ -477,6 +572,9 @@ export class TorrentPool {
    * @returns {void}
    */
   #attachSwarmDiagnostics(label, torrent) {
+    // A torrent nobody has asked for yet does not exist: this is called the
+    // moment one is added, which is the moment a viewer started waiting.
+    this.#markHurry(torrent, "just added");
     const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
     logger.info(
       `torrent-pool: [${label}] added: files=${torrent.files?.length ?? 0} ` +
@@ -1084,6 +1182,10 @@ export class TorrentPool {
     const isJump =
       previousStart === undefined || Math.abs(safeStart - previousStart) > PRIORITY_WINDOW_BYTES;
     if (isJump) {
+      // A jump is a seek. Whatever the swarm was giving us was for somewhere
+      // else, and the pieces at the new position have to be earned from peers
+      // that are choking us — the same standing start as a fresh torrent.
+      this.#markHurry(torrent, "the viewer moved");
       const percent = ((safeStart / fileLength) * 100).toFixed(1);
       logger.info(
         `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] read position -> ` +

package/test/upload-hurry.test.js

@@ -0,0 +1,96 @@
+/**
+ * @file Uploading generously at the two moments a viewer is waiting.
+ *
+ * BitTorrent peers serve those who serve them: each re-ranks its takers about
+ * every 10 s and opens a few slots to whoever uploaded most, plus one at
+ * random. Uploading a token 8-50 KB/s means being picked at random, one slot
+ * per cycle. Measured 2026-08-04 on a session with 96 peers already connected:
+ * 64 KB/s after 2 s, 1.6 MB/s after 4 s, 4.8 MB/s after 8 s — and the 16 MB the
+ * codec probe needs took 8.36 s of the 11.46 s before playback began.
+ *
+ * The reciprocity boost could not help: it waits for the download to be all but
+ * dead (below 200 KB/s) with peers visibly choking us, which a ramp is not. In
+ * that session it first moved the limit 13.3 s after the torrent was added, and
+ * reached the generous rate at 43.7 s — both after the wait they were meant to
+ * shorten.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { decideUploadLimit, torrentsForUploadPolicy } from "../services/torrent-pool.js";
+
+const NOW = 1_000_000;
+const healthy = (extra = {}) => ({
+  name: "film.mkv",
+  wires: [{ amInterested: true, peerChoking: false }],
+  downloadSpeed: 5 * 1024 * 1024,
+  done: false,
+  ...extra
+});
+
+test("a torrent in a hurry gets the generous rate even while downloading well", () => {
+  const decision = decideUploadLimit([healthy({ hurryUntil: NOW + 10_000 })], { now: NOW });
+  assert.equal(decision.bytesPerSec, 512 * 1024);
+  assert.match(decision.reason, /in a hurry/);
+});
+
+test("the hurry expires on its own", () => {
+  const decision = decideUploadLimit([healthy({ hurryUntil: NOW - 1 })], { now: NOW });
+  assert.equal(decision.bytesPerSec, 50 * 1024, "back to the token upload once the rush is over");
+});
+
+test("a finished torrent is never in a hurry", () => {
+  // Nothing left to download, so there is nothing to buy with the upload — and
+  // seeding is what we deliberately avoid.
+  const decision = decideUploadLimit([healthy({ hurryUntil: NOW + 10_000, done: true })], { now: NOW });
+  assert.equal(decision.bytesPerSec, 50 * 1024);
+});
+
+test("nothing being watched still means near-silence", () => {
+  assert.equal(decideUploadLimit([], { now: NOW }).bytesPerSec, 8 * 1024);
+});
+
+test("the reciprocity boost still works when no hurry is on", () => {
+  const starving = {
+    name: "film.mkv",
+    wires: [
+      { amInterested: true, peerChoking: true },
+      { amInterested: true, peerChoking: true }
+    ],
+    downloadSpeed: 10 * 1024,
+    done: false
+  };
+  const decision = decideUploadLimit([starving], { now: NOW });
+  assert.equal(decision.bytesPerSec, 512 * 1024);
+  assert.match(decision.reason, /earn unchoke/);
+});
+
+test("a torrent with no reader still reaches the policy while it is in a hurry", () => {
+  // The moment that matters: a torrent has just been added and its head and
+  // tail are being fetched for the codec probe. That read goes straight to
+  // `createReadStream`, so no reader is registered — and the selection only
+  // ever kept torrents that had one, which is where the gap was.
+  const hurrying = { name: "film.mkv", hurryUntil: NOW + 20_000 };
+  const idle = { name: "other.mkv" };
+  const usage = new Map();
+
+  assert.deepEqual(
+    torrentsForUploadPolicy([hurrying, idle], usage, NOW),
+    [hurrying],
+    "a torrent with no reader yet was ignored"
+  );
+
+  assert.deepEqual(
+    torrentsForUploadPolicy([{ ...hurrying, hurryUntil: NOW - 1 }, idle], usage, NOW),
+    [],
+    "and stops counting once the rush is over"
+  );
+
+  const read = { name: "watched.mkv" };
+  usage.set(read, new Set([0]));
+  assert.deepEqual(
+    torrentsForUploadPolicy([read], usage, NOW),
+    [read],
+    "a torrent being read still counts, hurry or not"
+  );
+});