@torrent-tv/proxy 2.9.102 → 2.9.104

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2.9.104
+
+- **Fix**: An encoder run that stops because its input ran dry is no longer reported as a finished file. ffmpeg exits 0 both when it reaches the end of the source and when the source simply stops delivering, and over HTTP it cannot tell the two apart — so when a torrent's download died mid-session (field 2026-08-05), a run that had produced 188 segments of 624 logged `encode-run complete`, the player consumed what was already on disk and then froze for 60 s on the first segment nobody was making. The claim is now checked against the playlist that was published: a run that stopped short is a failure, which the session can restart, rather than a completed file.
+- **New**: A download that stalls says so, and says which of the two possible reasons it is. The same session spent five minutes at **1 KB/s** with 186 peer connections open and trackers reporting ~300 seeders, on a torrent that was not finished, and produced no log line at all — the collapse had to be reconstructed afterwards from three unrelated counters. A torrent with an active reader that drops below 32 KB/s for ten seconds now reports how many pieces are selected and still missing, how many are marked critical, how many peers hold what we want, how many are choking us, how many are being asked and how many blocks are in flight. That separates "the swarm was never told what we need" from "it was told and will not deliver", which the previous evidence could not.
+
+## 2.9.103
+
+- **Fix**: Playback worked in neither 2.9.101 nor 2.9.102. Both cold-start estimates keep a window of recent samples, and the constant naming that window was used twice and declared nowhere. The session-create one runs on every new session, so `POST /api/transcode-sessions` answered 500 to every viewer and the browser then reported the first segment missing. Field session 2026-08-05: the plan succeeded in 5858 ms, the session request failed 47 ms later, the data channel closed 16 ms after that.
+- **Fix**: The fallback read path threw the same way. `createReadStream` passed a `windowBytes` its own signature never accepted — a reference to nothing, which in a module is an error, not an undefined. It is the path taken for a source with no shared piece pool, so it had never run on a host where it would have been noticed.
+- **Fix**: A failed session no longer leaves its directory behind. It was created before the probe and the keyframe index, both of which can fail, and nothing tracks or sweeps a directory whose session was never registered.
+- **New**: The transcode-session route says why it failed, on the proxy's own log and with the stack. It caught, answered 500 and stayed silent, so the log carried only the data-channel layer's bare `→ 500`: the cause of the defect above had to be recovered by replaying the request against the live proxy.
+- **Chore**: The proxy has a linter. It had none, and the rule for an undeclared name catches this whole class outright — it found the second occurrence above on its first run. Biome, `npm run lint`, limited to the correctness rules that describe real faults rather than style.
+
 ## 2.9.102
 
 - **New**: The playback plan also reports what this host takes to CREATE a session — median of the last eight, 116-843 ms depending on whether the keyframe index is already in hand. It is the second term of the browser's end-to-end estimate, which is being rebuilt as a sum over the stages that have not happened yet rather than a choice between figures that each describe only one of them (`research/playback-eta-2026-08-05.md`).

package/biome.json

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.5.7/schema.json",
+	"files": {
+		"includes": ["**/*.js", "!**/node_modules/**"]
+	},
+	"formatter": { "enabled": false },
+	"assist": { "enabled": false },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"preset": "none",
+			"correctness": {
+				"noUndeclaredVariables": "error",
+				"noUnusedImports": "error",
+				"noUnusedVariables": "error",
+				"noInvalidUseBeforeDeclaration": "error",
+				"noPrivateImports": "error"
+			}
+		}
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.102",
+  "version": "2.9.104",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -16,7 +16,8 @@
     "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"
+    "test": "node --test",
+    "lint": "biome lint ."
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",
@@ -34,5 +35,8 @@
     "webtorrent": "2.8.5",
     "werift": "^0.24.2",
     "ws": "^8.18.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.7"
   }
 }

package/routes/api/transcode-sessions/post.js

@@ -9,6 +9,8 @@
  * @returns {Promise<void>}
  */
 
+import { logger } from "../../../utils/logger.js";
+
 /**
  * Extract a plain object from the request body, guarding against
  * non-object payloads (arrays, primitives, null).
@@ -77,6 +79,17 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
       return reply.code(409).send({ error: error.message });
     }
     const message = error instanceof Error ? error.message : String(error);
+    // Say why on the proxy's own log, not only in the answer. This route
+    // answered 500 for every viewer of proxy 2.9.101-2.9.102 (an undeclared
+    // constant) and the addon log carried nothing but the data-channel layer's
+    // bare "→ 500": the cause had to be recovered by replaying the request
+    // against the live proxy. The stack is worth the two lines it costs — a
+    // programming error here is invisible to the viewer, who only sees that
+    // nothing plays.
+    logger.error(
+      `transcode-sessions: ${sourceKey}:${fileIndex} failed to prepare: ${message}\n` +
+        `${error instanceof Error ? (error.stack ?? "") : ""}`
+    );
     return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
   }
 }

package/services/hls-session-manager.js

@@ -7,7 +7,7 @@
  * immediately when all registered consumers release them.
  */
 
-import { createReadStream } from "node:fs";
+import { createReadStream, readdirSync } from "node:fs";
 import { access, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import os from "node:os";
@@ -181,6 +181,13 @@ const LINK_LOW_BUFFER_SEC = 10;
 // Observed produced bitrate: average over this many recently completed
 // segments (the newest file on disk may still be written and is excluded).
 const LINK_OBSERVED_SEGMENTS = 5;
+// How many recent runs the two cold-start estimates keep. Both the
+// session-create time and the first-segment time are reported to the browser as
+// the median of this many samples, so it has to be long enough that one slow run
+// does not move the figure and short enough that the estimate still follows the
+// host: a proxy whose swarm has warmed up, or which has just picked up a second
+// viewer, should stop quoting the numbers from ten minutes ago.
+const FIRST_SEGMENT_SAMPLES = 20;
 const MICROSECONDS_PER_SECOND = 1_000_000;
 const PROGRESS_LOG_INTERVAL_MS = 5_000;
 // Read segment files in large blocks so the body is delivered to the data
@@ -990,7 +997,6 @@ export class HlsSessionManager {
     const sessionId = randomUUID();
     const createEntryMs = Date.now();
     const sessionDir = createSessionDirPath(sessionId);
-    await mkdir(sessionDir, { recursive: true });
     const inputUrl = new URL("/stream", `${this.localBaseUrl}/`);
     inputUrl.searchParams.set("sourceKey", sourceKey);
     inputUrl.searchParams.set("fileIndex", String(fileIndex));
@@ -1176,6 +1182,14 @@ export class HlsSessionManager {
     const encodeWidth = encodeBudget?.width ?? normalizedTargetWidth;
     const encodeHeight = encodeBudget?.height ?? normalizedTargetHeight;
 
+    // Only now, when nothing above can still throw. Everything from the probe
+    // to the keyframe index used to run with the directory already made, so a
+    // failure between the two left it behind: nothing tracks a directory whose
+    // session was never registered, and no sweep looks for one. Proxy
+    // 2.9.101-2.9.102 failed here on every single request and the leftovers
+    // were the only trace of it on disk.
+    await mkdir(sessionDir, { recursive: true });
+
     const session = {
       id: sessionId,
       sourceMapKey,
@@ -2380,6 +2394,29 @@ export class HlsSessionManager {
         return;
       }
       if (code === 0) {
+        // ffmpeg exits 0 both when it reaches the end of the file and when its
+        // input simply stops producing bytes — over HTTP the two look identical
+        // to it. Field 2026-08-05: the torrent's download died, the read ended,
+        // and a run that had made 188 segments of 624 reported itself complete;
+        // the player then consumed what was on disk and froze on the first
+        // segment nobody was making. So the claim is checked against the
+        // playlist we published, and a run that stopped short is a FAILURE that
+        // can be restarted, not a finished file.
+        const producedThrough = this.#latestProducedSegment(session);
+        const expectedLast = session.segmentCount > 0 ? session.segmentCount - 1 : null;
+        if (expectedLast !== null && producedThrough !== null && producedThrough < expectedLast) {
+          session.state = "failed";
+          session.progress.state = "failed";
+          session.progress.updatedAt = Date.now();
+          session.lastError =
+            `input ended after segment #${producedThrough} of ${expectedLast} — ` +
+            "the source stopped delivering data";
+          logger.error(
+            `transcode ${session.id} ${session.runLabel ?? "run#?"} encode-run ended early: ` +
+            `${session.lastError} "${session.fileName}"`
+          );
+          return;
+        }
         session.state = "ready";
         session.progress.state = "ready";
         session.progress.updatedAt = Date.now();
@@ -2809,6 +2846,27 @@ export class HlsSessionManager {
     return sorted[Math.floor(sorted.length / 2)];
   }
 
+  /**
+   * The highest segment index this session has on disk, or null when it has
+   * none. Used to tell "the file ended" from "the data ran out".
+   *
+   * @param {HlsSession} session
+   * @returns {number | null}
+   */
+  #latestProducedSegment(session) {
+    let highest = null;
+    for (const name of readdirSync(session.dirPath, { withFileTypes: false })) {
+      if (!this.segmentFormat.isSegmentFileName(name)) {
+        continue;
+      }
+      const index = this.segmentFormat.segmentIndexFromName(name);
+      if (index >= 0 && (highest === null || index > highest)) {
+        highest = index;
+      }
+    }
+    return highest;
+  }
+
   /**
    * How many times the viewer has moved since this session started.
    *

package/services/torrent-pool.js

@@ -92,6 +92,73 @@ const UPLOAD_ADJUST_INTERVAL_MS = 5_000;
  * outright, for two unchoke cycles, without waiting for evidence of failure.
  */
 const UPLOAD_HURRY_MS = 25_000;
+// A torrent somebody is reading, that is not finished, and is moving less than
+// this, is not downloading. Well below the slowest real swarm seen in the field
+// (470 KB/s two seconds after a cold add) and well above idle chatter.
+const STALL_SPEED_BYTES = 32 * 1024;
+// How long it must stay there before saying so, and how often to repeat.
+const STALL_REPORT_AFTER_MS = 10_000;
+const STALL_REPORT_INTERVAL_MS = 30_000;
+
+/**
+ * What the swarm has been asked for, and what it is doing about it.
+ *
+ * Answers the question a stalled download cannot answer for itself: were the
+ * peers never told what we want, or told and not delivering? Reaches into
+ * WebTorrent's own bookkeeping because none of it is exposed — `_selections`
+ * is what the picker walks, `wire.requests` is what is actually outstanding.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {string}
+ */
+function describeSwarmDemand(torrent) {
+  const items = Array.isArray(torrent?._selections?._items) ? torrent._selections._items : [];
+  let selectedPieces = 0;
+  let missingSelected = 0;
+  for (const item of items) {
+    const from = Number(item?.from);
+    const to = Number(item?.to);
+    if (!Number.isFinite(from) || !Number.isFinite(to)) {
+      continue;
+    }
+    selectedPieces += to - from + 1;
+    for (let index = from; index <= to; index += 1) {
+      if (!torrent.bitfield?.get(index)) {
+        missingSelected += 1;
+      }
+    }
+  }
+
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
+  let inFlight = 0;
+  let asking = 0;
+  let choking = 0;
+  let interested = 0;
+  for (const wire of wires) {
+    const requests = Array.isArray(wire?.requests) ? wire.requests.length : 0;
+    inFlight += requests;
+    if (requests > 0) {
+      asking += 1;
+    }
+    if (wire?.peerChoking === true) {
+      choking += 1;
+    }
+    if (wire?.amInterested === true) {
+      interested += 1;
+    }
+  }
+
+  const critical = Array.isArray(torrent?._critical)
+    ? torrent._critical.reduce((count, flag) => (flag ? count + 1 : count), 0)
+    : 0;
+
+  return (
+    `${items.length} selection(s) covering ${selectedPieces} piece(s), ` +
+    `${missingSelected} of them missing, ${critical} marked critical; ` +
+    `${wires.length} peers, ${interested} we want data from, ${choking} choking us, ` +
+    `${asking} being asked, ${inFlight} blocks in flight`
+  );
+}
 
 /**
  * Decide the client-wide upload limit (bytes/sec) from the torrents that
@@ -383,6 +450,11 @@ export class TorrentPool {
    */
   #readPositionByTorrent = new Map();
 
+  /** When each torrent's download first fell below the stall threshold. */
+  #stallSince = new Map();
+  /** When each torrent's stall was last reported, so it is not repeated hotly. */
+  #stallReportedAt = new Map();
+
   /**
    * Edge prefetches currently running, keyed by infoHash and file index, so two
    * callers asking at the same time share one.
@@ -507,6 +579,53 @@ export class TorrentPool {
     this.#adjustUploadLimit();
   }
 
+  /**
+   * Say when a torrent that somebody is reading has stopped downloading.
+   *
+   * Field 2026-08-05: a session died 32 minutes in because the download fell to
+   * **1 KB/s for five minutes** with 186 peer connections open and trackers
+   * reporting ~300 seeders, on a torrent that was not finished. ffmpeg then ran
+   * out of input and reported itself complete at segment 188 of 624. Not one
+   * line of the log said anything was wrong — the collapse had to be recovered
+   * afterwards by hand from three unrelated counters.
+   *
+   * So the stall reports itself, and it reports the two things that tell the
+   * candidates apart: whether the swarm was ASKED for anything (pieces selected
+   * and still missing, blocks in flight) or was asked and did not answer (peers
+   * holding what we want, how many are choking us).
+   *
+   * @returns {void}
+   */
+  #reportStalledDownloads() {
+    const now = Date.now();
+    for (const torrent of this.torrents.values()) {
+      const usage = this.fileUsageByTorrent.get(torrent);
+      if (!usage || usage.size === 0 || torrent?.done === true) {
+        continue;
+      }
+      const speed = typeof torrent.downloadSpeed === "number" ? torrent.downloadSpeed : 0;
+      if (speed >= STALL_SPEED_BYTES) {
+        this.#stallSince.delete(torrent);
+        continue;
+      }
+      const since = this.#stallSince.get(torrent) ?? now;
+      this.#stallSince.set(torrent, since);
+      if (now - since < STALL_REPORT_AFTER_MS) {
+        continue;
+      }
+      const lastReport = this.#stallReportedAt.get(torrent) ?? 0;
+      if (now - lastReport < STALL_REPORT_INTERVAL_MS) {
+        continue;
+      }
+      this.#stallReportedAt.set(torrent, now);
+      logger.warn(
+        `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] download stalled at ` +
+        `${Math.round(speed / 1024)}KB/s for ${Math.round((now - since) / 1000)}s — ` +
+        describeSwarmDemand(torrent)
+      );
+    }
+  }
+
   #adjustUploadLimit() {
     if (!this.client || this.client.destroyed || typeof this.client.throttleUpload !== "function") {
       return;
@@ -516,6 +635,7 @@ export class TorrentPool {
       this.fileUsageByTorrent,
       Date.now()
     );
+    this.#reportStalledDownloads();
     const { bytesPerSec, reason } = decideUploadLimit(active);
     if (bytesPerSec === this.#uploadLimit) {
       return;

package/services/torrent-worker/client.js

@@ -231,7 +231,7 @@ export class TorrentWorkerClient {
    * @param {{ sourceKey: string, fileIndex: number, start?: number | null, end?: number | null, windowBytes?: number }} params
    * @returns {ReadableStream<Uint8Array>}
    */
-  createReadStream({ sourceKey, fileIndex, start = null, end = null }) {
+  createReadStream({ sourceKey, fileIndex, start = null, end = null, windowBytes }) {
     // Same id sequence as commands — see `nextId` in `channel.js`.
     const readId = this.#caller.nextId();
     const receive = createReceiveStream({
@@ -407,7 +407,8 @@ export class TorrentWorkerClient {
               sourceKey,
               fileIndex: file.index,
               start: options.start ?? null,
-              end: options.end ?? null
+              end: options.end ?? null,
+              windowBytes: options.windowBytes
             })
           );
         },

package/test/webrtc-shim.test.js

@@ -15,7 +15,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { Worker } from "node:worker_threads";
-import { fileURLToPath } from "node:url";
 import {
   RTCPeerConnection,
   RTCSessionDescription