@torrent-tv/proxy 2.9.105 → 2.9.107

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.107
+
+- **Fix**: 2.9.106 could not produce a playback plan at all — `Failed to prepare playback plan: firstSegmentMs is not defined`. Moving the two host timings to be read when a plan is ANSWERED removed the two variables but left the object literal still naming them, on the path that builds a fresh plan. My own linter reports it in four seconds and I did not run it, which is the second time an undeclared name has reached a release; `npm publish` now runs it, so this class of error cannot leave the machine again. The test added with 2.9.106 did not catch it because it exercises the cached path only — the fresh-plan path needs a real probe.
+
+## 2.9.106
+
+- **Fix**: The two figures the browser needs to say how long until playback now reach it for the file that needs them most. Both are medians of sessions already finished on this host, and the plan read them at the moment it was BUILT and then cached the result — so the very first file opened after a restart got `null` for both and kept answering `null` for the life of the process, however many sessions ran afterwards. Measured 2026-08-05: a fresh proxy answered `null`, then created the session in 6 ms and produced the first segment in 21 479 ms. They are now read when the plan is ANSWERED, so a cached plan reports what the host currently knows. Covered by tests.
+- **New**: When the stats route has nothing to report it says which thing is missing — the torrent handle, the file index, or neither. A source answered `peers=0 file=n/a header=n/a` for minutes on 2026-08-05 while that very torrent was announcing to trackers with hundreds of seeders, and the line could not tell those cases apart. That line is what the viewer's loading screen shows, so it has to be answerable from the log.
+
 ## 2.9.105
 
 - **Fix**: A reader's claim on pieces is put back when WebTorrent drops it, which is what stopped a download dead for eleven minutes. A reader declares the window it needs as a selection and withdraws it when it ends; that claim turns out not to be durable — the library deletes a selection the moment every piece in it is present (`remove fully downloaded selection`). While the reader keeps moving this is invisible, because the next window is claimed at once. It is fatal when the reader STOPS: the encoder gets held back by the look-ahead cap, ffmpeg stops reading, the reader parks on a window that is fully downloaded, the selection disappears, and no code of ours can notice because the reader is parked inside a write. Measured 2026-08-05: the encoder was suspended at 22:44:51, the download hit zero at 22:45:05 and stayed there for eleven minutes with 150 peer connections open and the new diagnostic reading `0 selection(s) covering 0 piece(s), 0 being asked, 0 blocks in flight`; when the encoder was let go there was nothing ahead of it. Live reader windows are now re-asserted from the pool's own timer, using the set the piece store already keeps, and only where something is actually missing — re-claiming a satisfied window would only be deleted again on the next pass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.105",
+  "version": "2.9.107",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -17,7 +17,8 @@
     "start": "node ./bin/cli.js",
     "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
     "test": "node --test",
-    "lint": "biome lint ."
+    "lint": "biome lint .",
+    "prepublishOnly": "npm run lint"
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",

package/routes/api/sources/stats/get.js

@@ -1,69 +1,82 @@
-import { logger } from "../../../../utils/logger.js";
-
-/**
- * Return download statistics for a registered torrent source.
- *
- * Provides peer count, transfer speeds, and per-file download progress so
- * that the browser client can display meaningful feedback while the proxy is
- * pre-fetching file metadata (MOOV atom / EBML headers) before codec probing.
- *
- * GET /api/sources/:sourceKey/stats?fileIndex=N
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{
- *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
- *   torrentPool: import("../../../../services/torrent-pool.js").TorrentPool
- * }} deps
- * @returns {Promise<void>}
- */
-export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool }) {
-  const sourceKey = typeof req.params.sourceKey === "string" ? req.params.sourceKey.trim() : "";
-  if (!sourceKey) {
-    return reply.code(400).send({ error: "sourceKey is required." });
-  }
-
-  const sourceRecord = sourceRegistry.get(sourceKey);
-  if (!sourceRecord) {
-    return reply.code(404).send({ error: "Source key was not found." });
-  }
-
-  let torrent;
-  try {
-    // getTorrent resolves immediately when the torrent is already loaded.
-    torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return reply.code(500).send({ error: `Failed to load torrent: ${message}` });
-  }
-
-  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
-  const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
-
-  // Optional: pin the resume window to a FIXED byte offset for the duration of
-  // one buffering episode (see getFileStats JSDoc) instead of the live, moving
-  // read position — otherwise "bytes needed" can jump up mid-poll as the window
-  // slides forward with playback/encoding progress.
-  const resumeAnchorRaw = typeof req.query.resumeAnchorByteStart === "string" ? req.query.resumeAnchorByteStart : "";
-  const resumeAnchorByteStart = resumeAnchorRaw !== "" && /^\d+$/.test(resumeAnchorRaw) ? Number(resumeAnchorRaw) : null;
-
-  // Awaited: with the torrent on its own thread this is a round trip, not a
-  // local lookup. Without the await the reply was the pending promise itself,
-  // which serialises to `{}` — the empty stats seen in the field 2026-08-02.
-  const stats = await torrentPool.getFileStats(torrent, fileIndex, { resumeAnchorByteStart });
-
-  // Diagnostic: surface the real swarm state per poll so a cold-start download
-  // stall (0 peers / header not advancing → playback-plan blocks on the codec
-  // probe → browser timeout) is visible in the proxy log.
-  const downKbps = (stats.downloadSpeed / 1024).toFixed(0);
-  const filePct = stats.fileProgress != null ? `${(stats.fileProgress * 100).toFixed(1)}%` : "n/a";
-  const header =
-    stats.headerBytes != null
-      ? `${stats.headerDownloadedBytes}/${stats.headerBytes}B`
-      : "n/a";
-  logger.info(
-    `[stats] ${sourceKey.slice(0, 8)} peers=${stats.numPeers} down=${downKbps}KB/s file=${filePct} header=${header}`
-  );
-
-  return reply.send(stats);
-}
+import { logger } from "../../../../utils/logger.js";
+
+/**
+ * Return download statistics for a registered torrent source.
+ *
+ * Provides peer count, transfer speeds, and per-file download progress so
+ * that the browser client can display meaningful feedback while the proxy is
+ * pre-fetching file metadata (MOOV atom / EBML headers) before codec probing.
+ *
+ * GET /api/sources/:sourceKey/stats?fileIndex=N
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{
+ *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
+ *   torrentPool: import("../../../../services/torrent-pool.js").TorrentPool
+ * }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool }) {
+  const sourceKey = typeof req.params.sourceKey === "string" ? req.params.sourceKey.trim() : "";
+  if (!sourceKey) {
+    return reply.code(400).send({ error: "sourceKey is required." });
+  }
+
+  const sourceRecord = sourceRegistry.get(sourceKey);
+  if (!sourceRecord) {
+    return reply.code(404).send({ error: "Source key was not found." });
+  }
+
+  let torrent;
+  try {
+    // getTorrent resolves immediately when the torrent is already loaded.
+    torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return reply.code(500).send({ error: `Failed to load torrent: ${message}` });
+  }
+
+  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
+  const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
+
+  // Optional: pin the resume window to a FIXED byte offset for the duration of
+  // one buffering episode (see getFileStats JSDoc) instead of the live, moving
+  // read position — otherwise "bytes needed" can jump up mid-poll as the window
+  // slides forward with playback/encoding progress.
+  const resumeAnchorRaw = typeof req.query.resumeAnchorByteStart === "string" ? req.query.resumeAnchorByteStart : "";
+  const resumeAnchorByteStart = resumeAnchorRaw !== "" && /^\d+$/.test(resumeAnchorRaw) ? Number(resumeAnchorRaw) : null;
+
+  // Awaited: with the torrent on its own thread this is a round trip, not a
+  // local lookup. Without the await the reply was the pending promise itself,
+  // which serialises to `{}` — the empty stats seen in the field 2026-08-02.
+  const stats = await torrentPool.getFileStats(torrent, fileIndex, { resumeAnchorByteStart });
+
+  // Diagnostic: surface the real swarm state per poll so a cold-start download
+  // stall (0 peers / header not advancing → playback-plan blocks on the codec
+  // probe → browser timeout) is visible in the proxy log.
+  const downKbps = (stats.downloadSpeed / 1024).toFixed(0);
+  const filePct = stats.fileProgress != null ? `${(stats.fileProgress * 100).toFixed(1)}%` : "n/a";
+  const header =
+    stats.headerBytes != null
+      ? `${stats.headerDownloadedBytes}/${stats.headerBytes}B`
+      : "n/a";
+  // When the answer is empty, say WHICH thing is missing. Field 2026-08-05: a
+  // source reported `peers=0 file=n/a header=n/a` for minutes while that very
+  // torrent was announcing to trackers with hundreds of seeders — and the line
+  // above cannot tell apart "the torrent handle is not the live one", "the file
+  // index did not resolve" and "no file index was asked for". That is what the
+  // viewer's loading screen was showing at the time, so it has to be
+  // answerable from the log rather than by reasoning about it afterwards.
+  const emptyAnswer = stats.fileProgress == null || (stats.numPeers === 0 && torrent.done !== true);
+  const detail = emptyAnswer
+    ? ` | infoHash=${String(torrent.infoHash).slice(0, 8)} files=${torrent.files?.length ?? "?"}` +
+      ` askedFor=${fileIndex ?? "none"} resolved=${torrent.files?.[fileIndex ?? -1] ? "yes" : "no"}` +
+      ` wires=${torrent.wires?.length ?? "?"} done=${torrent.done === true}`
+    : "";
+  logger.info(
+    `[stats] ${sourceKey.slice(0, 8)} peers=${stats.numPeers} down=${downKbps}KB/s file=${filePct} header=${header}${detail}`
+  );
+
+  return reply.send(stats);
+}

package/services/playback-planner.js

@@ -286,6 +286,31 @@ export function createPlaybackPlanner({
    */
   const mediaInfoCache = new Map();
 
+  /**
+   * Attach what this host currently measures itself taking to create a session
+   * and to produce a first segment.
+   *
+   * Read at RESPONSE time, deliberately. Both are medians of sessions that have
+   * already finished on this host, so at the moment a plan is BUILT the very
+   * first file opened after a restart has none and gets `null` — and the plan
+   * is then cached, so that file kept answering `null` for the life of the
+   * process however many sessions ran afterwards. Measured 2026-08-05: a fresh
+   * 2.9.103 answered `null` for both, then produced the session in 6 ms and the
+   * first segment in 21 479 ms. The figures existed; the plan could not carry
+   * them, and the browser's estimate fell back to its own guess in exactly the
+   * cold-start case the feature was built for.
+   *
+   * @param {PlaybackPlan} plan
+   * @returns {PlaybackPlan}
+   */
+  function withHostTimings(plan) {
+    return {
+      ...plan,
+      expectedFirstSegmentMs: expectedFirstSegmentMs?.() ?? null,
+      expectedSessionCreateMs: expectedSessionCreateMs?.() ?? null
+    };
+  }
+
   return {
     /**
      * Media info the planner already probed for this file, or `null`. Lets the
@@ -322,7 +347,7 @@ export function createPlaybackPlanner({
       const cacheKey = `${sourceKey}:${fileIndex}`;
       const cached = cache.get(cacheKey);
       if (cached) {
-        return cached;
+        return withHostTimings(cached);
       }
       // Where the time before playback goes. `cold-start` already breaks down
       // everything from the transcode-session request onwards, but the plan
@@ -365,7 +390,7 @@ export function createPlaybackPlanner({
           subtitleTracks: []
         };
         cache.set(cacheKey, plan);
-        return plan;
+        return withHostTimings(plan);
       }
 
       // Pre-fetch file edges (head + tail), then probe — retrying while the
@@ -402,8 +427,6 @@ export function createPlaybackPlanner({
       }
       const { audioCodec, videoCodec, container, durationSeconds, videoWidth, videoHeight, audioTracks, subtitleTracks } = probe;
       const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
-      const firstSegmentMs = expectedFirstSegmentMs?.() ?? null;
-      const sessionCreateMs = expectedSessionCreateMs?.() ?? null;
       logger.info(
         `plan ${sourceKey.slice(0, 8)}:${fileIndex} torrent-ready=${torrentReadyMs}ms ` +
           `file-edges=${edgesReadyMs - torrentReadyMs}ms probe=${Date.now() - planEntryMs - edgesReadyMs}ms ` +
@@ -430,11 +453,11 @@ export function createPlaybackPlanner({
         // Full track inventory for the browser's audio/subtitle menus.
         audioTracks: audioTracks ?? [],
         subtitleTracks: subtitleTracks ?? [],
-        // What this host has recently taken to make a session's first segment.
-        // Null until one has finished since startup.
-        expectedFirstSegmentMs: firstSegmentMs,
-        // Second term of the browser's estimate; see research/playback-eta-2026-08-05.md.
-        expectedSessionCreateMs: sessionCreateMs
+        // Both host timings are filled in by `withHostTimings` on the way out,
+        // never here: read at build time they would be frozen into the cached
+        // plan, which is the bug fixed in 2.9.106.
+        expectedFirstSegmentMs: null,
+        expectedSessionCreateMs: null
       };
       // Only cache a plan whose codecs were actually detected. An empty probe is
       // a "header not downloaded yet" signal, not a valid result — caching it
@@ -463,9 +486,9 @@ export function createPlaybackPlanner({
             timeoutMs: 60_000
           })
           .catch(() => {});
-        return plan;
+        return withHostTimings(plan);
       }
-      return { ...plan, pending: true };
+      return withHostTimings({ ...plan, pending: true });
     }
   };
 }

package/test/plan-host-timings.test.js

@@ -0,0 +1,68 @@
+/**
+ * @file The host's own timings must reach the browser for the file that needs
+ * them most.
+ *
+ * The plan carries two figures the browser cannot measure for itself: how long
+ * this host takes to create a session, and how long it takes to produce a first
+ * segment. Both are medians of sessions that have already finished here, so at
+ * the moment a plan is BUILT the very first file opened after a restart has
+ * neither — and the plan is cached, so that file kept answering `null` for the
+ * life of the process however many sessions ran afterwards. Measured
+ * 2026-08-05: a fresh proxy answered `null` for both, then created the session
+ * in 6 ms and produced the first segment in 21 479 ms.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createPlaybackPlanner } from "../services/playback-planner.js";
+
+/**
+ * A planner whose host timings can be changed between calls, over a source that
+ * needs no torrent: transcoding disabled short-circuits to a cached direct plan
+ * without probing anything.
+ */
+function plannerWithTimings() {
+  const timings = { create: null, first: null };
+  const planner = createPlaybackPlanner({
+    ffmpegBin: "ffmpeg",
+    localBaseUrl: "http://127.0.0.1:9090/stream",
+    sourceRegistry: { get: () => ({ sourceType: "magnet", source: "magnet:?xt=urn:btih:0" }) },
+    torrentPool: { getTorrent: async () => ({ files: [{ name: "a.mkv", length: 10 }] }) },
+    transcodeAudioEnabled: false,
+    expectedSessionCreateMs: () => timings.create,
+    expectedFirstSegmentMs: () => timings.first
+  });
+  return { planner, timings };
+}
+
+test("a plan built before the host had measured anything still reports them later", async () => {
+  const { planner, timings } = plannerWithTimings();
+
+  const cold = await planner.getPlan({ sourceKey: "src", fileIndex: 0 });
+  assert.equal(cold.expectedSessionCreateMs, null, "nothing has finished yet, so there is nothing to report");
+  assert.equal(cold.expectedFirstSegmentMs, null);
+
+  // Sessions run; the host now knows what it costs.
+  timings.create = 6;
+  timings.first = 21_479;
+
+  const warm = await planner.getPlan({ sourceKey: "src", fileIndex: 0 });
+  assert.equal(
+    warm.expectedSessionCreateMs,
+    6,
+    "the cached plan withheld the figure the browser needed"
+  );
+  assert.equal(warm.expectedFirstSegmentMs, 21_479);
+});
+
+test("the figures follow the host as they change", async () => {
+  const { planner, timings } = plannerWithTimings();
+  timings.create = 100;
+  timings.first = 800;
+  const first = await planner.getPlan({ sourceKey: "src", fileIndex: 0 });
+  assert.equal(first.expectedFirstSegmentMs, 800);
+
+  timings.first = 7_000; // a re-encode session — an order of magnitude slower
+  const later = await planner.getPlan({ sourceKey: "src", fileIndex: 0 });
+  assert.equal(later.expectedFirstSegmentMs, 7_000, "the plan reported a stale figure");
+});