@torrent-tv/proxy 2.9.101 → 2.9.103

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 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`).
+
 ## 2.9.101
 
 - **New**: The playback plan reports what this host takes to produce a session's first segment — the median of its last eight, measured from session-create to a servable segment (782-1518 ms on the field host). The browser needs it for the gap between "the file is downloaded" and "a segment exists", where until now it assumed the pipeline merely keeps up with realtime and therefore showed 15 s where 3.8 s were left. It is per-host, so a weak box and a fast one each answer for themselves.

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.101",
+  "version": "2.9.103",
   "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/server.js

@@ -165,7 +165,8 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     sourceRegistry,
     torrentPool,
     warmKeyframeIndex: (params) => hlsSessionManager.warmKeyframeIndex(params),
-    expectedFirstSegmentMs: () => hlsSessionManager.expectedFirstSegmentMs()
+    expectedFirstSegmentMs: () => hlsSessionManager.expectedFirstSegmentMs(),
+    expectedSessionCreateMs: () => hlsSessionManager.expectedSessionCreateMs()
   });
 
   app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));

package/services/hls-session-manager.js

@@ -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
@@ -808,6 +815,16 @@ export class HlsSessionManager {
    */
   #firstSegmentLatencies = [];
 
+  /**
+   * Recent times to create a session, in ms — the second term of the browser's
+   * estimate. Measured for the same reason as the first: it is 116-843 ms
+   * depending on whether the keyframe index is already in hand, and guessing it
+   * was one of the ways the shown figure stopped describing the whole wait.
+   *
+   * @type {number[]}
+   */
+  #sessionCreateLatencies = [];
+
   /**
    * @param {HlsSessionManagerOptions} options
    */
@@ -980,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));
@@ -1121,6 +1137,7 @@ export class HlsSessionManager {
         );
       });
     }
+    this.#rememberSessionCreateLatency(Date.now() - createEntryMs);
     logger.info(
       `cold-start ${sessionId.slice(0, 8)}: media-info=${mediaInfoMs}ms (${mediaInfoSource}) ` +
         `keyframes=${keyframeMs === -1 ? "skipped" : keyframeMs === -2 ? "background" : `${keyframeMs}ms`} ` +
@@ -1165,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,
@@ -2750,6 +2775,30 @@ export class HlsSessionManager {
    * @param {number} latencyMs
    * @returns {void}
    */
+  #rememberSessionCreateLatency(latencyMs) {
+    if (!Number.isFinite(latencyMs) || latencyMs <= 0) {
+      return;
+    }
+    this.#sessionCreateLatencies.push(latencyMs);
+    if (this.#sessionCreateLatencies.length > FIRST_SEGMENT_SAMPLES) {
+      this.#sessionCreateLatencies.shift();
+    }
+  }
+
+  /**
+   * What this host typically takes to create a session, in ms — the median of
+   * recent ones, or null before any has finished.
+   *
+   * @returns {number | null}
+   */
+  expectedSessionCreateMs() {
+    if (this.#sessionCreateLatencies.length === 0) {
+      return null;
+    }
+    const sorted = [...this.#sessionCreateLatencies].sort((left, right) => left - right);
+    return sorted[Math.floor(sorted.length / 2)];
+  }
+
   #rememberFirstSegmentLatency(latencyMs) {
     if (!Number.isFinite(latencyMs) || latencyMs <= 0) {
       return;

package/services/playback-planner.js

@@ -269,6 +269,7 @@ export function createPlaybackPlanner({
   // downloaded" and "a segment exists": until now it assumed the pipeline
   // merely keeps up with realtime, and showed 15 s where 3.8 s were left.
   expectedFirstSegmentMs,
+  expectedSessionCreateMs,
   // Optional. Called once the file's edges are downloaded, so the keyframe
   // index — which reads the same tail of the file — is fetched alongside the
   // codec probe instead of after it. Late-bound to the HLS session manager,
@@ -402,6 +403,7 @@ 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,7 +432,9 @@ export function createPlaybackPlanner({
         subtitleTracks: subtitleTracks ?? [],
         // What this host has recently taken to make a session's first segment.
         // Null until one has finished since startup.
-        expectedFirstSegmentMs: firstSegmentMs
+        expectedFirstSegmentMs: firstSegmentMs,
+        // Second term of the browser's estimate; see research/playback-eta-2026-08-05.md.
+        expectedSessionCreateMs: sessionCreateMs
       };
       // 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

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