@torrent-tv/proxy 2.9.124 → 2.9.125

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 2.9.125
+
+- **Fix**: Playback works again. 2.9.124 shipped two names it never declared — `readSelfContainedStartSeconds`, called in `segment-formats/fmp4.js` and imported nowhere, and `SEGMENT_START_DISAGREEMENT_SEC` on the line after it — so preparing any segment cut at keyframes threw a `ReferenceError`. That is every ordinary file. Measured 2026-08-08: the playlist and the init segment were served, twelve finished segments lay in the session directory, and the request for segment #0 was held for 45 281 ms and then answered 404 because the browser had given up and released the session. Peers, download rate and transport were all healthy throughout, so nothing in the logs pointed anywhere near the cause.
+- **Fix**: A fault while preparing a file that EXISTS is now reported instead of being passed off as "not produced yet". One `try` covered both the existence check and everything after it, and its `catch` meant only the first, so the exception above came out as "still warming up" — the request was held, the next poll threw the same exception, and so on until the viewer left. Nothing was logged at any point. The existence check now stands alone; a file that goes away between the check and the read still means "not ready", and anything else is logged with its stack and answered as a failure. The same split applies to the init segment.
+- **Chore**: `npm test` runs the linter before the tests. The linter added in 2.9.103 exists precisely to catch an undeclared name, and it names both of these — it simply was not run before releasing 2.9.124, because nothing ran it.
+- **Chore**: A test asks the session manager for a segment that exists and insists on getting the bytes back. Every unit test of the fMP4 path passed while playback was dead: they import the function straight from `mp4-boxes.js`, so the missing import in its CALLER was invisible. A second test pins that a fault in preparing an existing segment is answered as a failure, not as an endless wait.
+
 ## 2.9.124
 
 - **Fix**: Subtitles no longer drift away from the picture. A segment was stamped with the time the PLAYLIST assigned it, and the playlist is built from the container keyframe index — which can be wrong. Measured 2026-08-06 on a Matroska file whose index claimed a keyframe at 157.99 s where the real ones were 153.820 and 164.247: ffmpeg cut at 153.820, the stamp said 157.99, and the player was told that picture belonged 4.17 s later than it did. Subtitles, extracted straight from the source with no offset of any kind, kept the true times, so speech and text sat 4.17 s apart for the whole stretch. The stamp now comes from the piece itself — the muxer records its position as an empty edit at the head of the track edit list, read before the header is stripped — and falls back to the playlist only when the piece does not say. Identical to the old figure whenever the index is honest, so a well-formed file is unaffected. When the two disagree by more than a quarter of a second the log names both, so an index that lies is visible rather than merely felt. Verified against ffmpeg on pieces cut the same way (12/30/36 s read back exactly), and covered by tests including a 64-bit edit list and a non-default movie timescale.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.124",
+  "version": "2.9.125",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -19,7 +19,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",
+    "test": "npm run lint && node --test",
     "lint": "biome lint ."
   },
   "dependencies": {

package/services/hls-session-manager.js

@@ -293,6 +293,12 @@ const PROGRESS_LOG_INTERVAL_MS = 5_000;
 // hashing starves the event loop in bursts, so fewer read iterations means
 // far less time lost between chunks while serving the first segments.
 const SEGMENT_READ_HIGH_WATER_MARK = 4 * 1024 * 1024;
+// How far a segment's own recorded start may sit from the one the playlist
+// assigned it before the disagreement is worth a log line. The two are built
+// from the same keyframe index and normally match to the sample; a quarter of a
+// second is below any drift a viewer could notice, so anything above it is the
+// index being wrong about where a keyframe is rather than rounding.
+const SEGMENT_START_DISAGREEMENT_SEC = 0.25;
 
 /**
  * Resolve after a given number of milliseconds.
@@ -3338,10 +3344,20 @@ export class HlsSessionManager {
           contentType: session.segmentFormat.initContentType,
           isPlaylist: false
         };
-      } catch {
-        // Not produced yet — the encode run started at session creation writes
-        // it early; the caller long-polls until it appears.
-        return { kind: "warming-up" };
+      } catch (error) {
+        if (error?.code === "ENOENT") {
+          // Not produced yet — the encode run started at session creation
+          // writes it early; the caller long-polls until it appears.
+          return { kind: "warming-up" };
+        }
+        logger.error(
+          `transcode ${session.id} could not serve ${initFileName}: ${error?.message ?? error}` +
+          (error?.stack ? `\n${error.stack}` : "")
+        );
+        return {
+          kind: "failed",
+          message: `Could not serve ${initFileName}: ${error?.message ?? String(error)}`
+        };
       }
     }
 
@@ -3360,9 +3376,21 @@ export class HlsSessionManager {
         this.#enforceLookAheadFor(session);
       }
     }
+    // Whether the file is there is asked on its own, and nothing else shares
+    // this catch. Everything below is PREPARATION of a file that exists, and a
+    // failure there means something entirely different from "not produced yet"
+    // — but for one release the two were caught together, so an undeclared name
+    // in the fMP4 path read as "the segment is not ready". Every poll threw the
+    // same ReferenceError, every poll answered "wait", and playback never began
+    // on any file cut at keyframes (2.9.124; measured 2026-08-08: segment #0
+    // held for 45 281 ms with twelve finished segments on disk).
     try {
       await access(filePath);
-
+    } catch {
+      // Not produced yet.
+      return this.#holdForProduction(session, fileName, isPlaylist, options);
+    }
+    try {
       // Existing is not the same as finished. The `hls` muxer wrote each
       // segment to a temporary name and renamed it once complete, so a file
       // appearing WAS a finished segment. The `segment` muxer has no such
@@ -3500,10 +3528,38 @@ export class HlsSessionManager {
           : session.segmentFormat.segmentContentType,
         isPlaylist
       };
-    } catch (_error) {
-      // File not produced yet.
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        // The file went away between the check and the read — a leftover being
+        // removed so it can be produced again. Means exactly what never having
+        // existed means.
+        return this.#holdForProduction(session, fileName, isPlaylist, options);
+      }
+      // Anything else is a fault in producing the answer. Name it: a request
+      // answered "wait" for ever tells the viewer nothing and leaves no trace
+      // of what actually happened.
+      logger.error(
+        `transcode ${session.id} could not serve ${fileName}: ${error?.message ?? error}` +
+        (error?.stack ? `\n${error.stack}` : "")
+      );
+      return {
+        kind: "failed",
+        message: `Could not serve ${fileName}: ${error?.message ?? String(error)}`
+      };
     }
+  }
 
+  /**
+   * Answer a request for a file that is not on disk: make sure the encoder is
+   * heading for it, and hold the request.
+   *
+   * @param {HlsSession} session
+   * @param {string} fileName
+   * @param {boolean} isPlaylist
+   * @param {{ requestSeq?: number }} options
+   * @returns {{ kind: "warming-up" }}
+   */
+  #holdForProduction(session, fileName, isPlaylist, options) {
     // A segment was requested that ffmpeg has not produced yet.  Decide whether
     // to wait for the current encode run to reach it or to restart the encoder
     // at this position (server-side seeking).  The caller long-polls.

package/services/segment-formats/fmp4.js

@@ -10,7 +10,12 @@
  * See {@link SegmentFormat} in `./index.js` for the interface contract.
  */
 
-import { readTrackTimescales, stampSegmentStartTime, walkBoxes } from "./mp4-boxes.js";
+import {
+  readSelfContainedStartSeconds,
+  readTrackTimescales,
+  stampSegmentStartTime,
+  walkBoxes
+} from "./mp4-boxes.js";
 
 /**
  * How many distinct tracks have a fragment in this segment.

package/test/segment-serve-wiring.test.js

@@ -0,0 +1,205 @@
+/**
+ * @file A finished segment on disk must reach the viewer as bytes.
+ *
+ * The module tests cover each piece of the fMP4 path on its own, and every one
+ * of them passed while playback was dead: 2.9.124 called
+ * `readSelfContainedStartSeconds` from `fmp4.js` without importing it, and the
+ * unit test imports that function straight from `mp4-boxes.js`, so the gap
+ * between a module and its CALLER was invisible. This test asks the session
+ * manager for a segment that exists and insists on getting it.
+ *
+ * The second half pins the reason a one-word slip cost a whole release: the
+ * failure was reported as "still being produced". Measured 2026-08-08 — segment
+ * #0 was held for 45 281 ms with twelve finished segments in the directory, and
+ * the log said nothing at all. Anything that goes wrong while preparing a file
+ * that EXISTS must be named and answered, never turned into an endless wait.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const MOVIE_TIMESCALE = 1000;
+const VIDEO_TIMESCALE = 90_000;
+const AUDIO_TIMESCALE = 48_000;
+const SEGMENT_START_SECONDS = 12.5;
+const SESSION_ID = "11111111-2222-3333-4444-555555555555";
+
+/**
+ * @param {string} type
+ * @param {Buffer} body
+ * @returns {Buffer}
+ */
+function box(type, body) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(8 + body.length, 0);
+  head.write(type, 4, "latin1");
+  return Buffer.concat([head, body]);
+}
+
+/**
+ * `elst` holding one empty edit — how the `segment` muxer records where the
+ * piece sits on the source timeline.
+ *
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function emptyEdit(offsetSeconds) {
+  const body = Buffer.alloc(16);
+  body.writeUInt32BE(1, 4);                                        // entry count
+  body.writeUInt32BE(Math.round(offsetSeconds * MOVIE_TIMESCALE), 8); // duration
+  body.writeInt32BE(-1, 12);                                       // media_time
+  return box("elst", body);
+}
+
+/**
+ * @param {number} trackId
+ * @param {number} timescale
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function trak(trackId, timescale, offsetSeconds) {
+  const tkhdBody = Buffer.alloc(84);
+  tkhdBody.writeUInt32BE(trackId, 12);
+  const mdhdBody = Buffer.alloc(20);
+  mdhdBody.writeUInt32BE(timescale, 12);
+  return box("trak", Buffer.concat([
+    box("tkhd", tkhdBody),
+    box("edts", emptyEdit(offsetSeconds)),
+    box("mdia", box("mdhd", mdhdBody))
+  ]));
+}
+
+/**
+ * @param {number} trackId
+ * @returns {Buffer}
+ */
+function traf(trackId) {
+  const tfhdBody = Buffer.alloc(8);
+  tfhdBody.writeUInt32BE(trackId, 4);
+  const tfdtBody = Buffer.alloc(12);
+  tfdtBody.writeUInt8(1, 0);                       // version 1 — 64-bit
+  tfdtBody.writeBigUInt64BE(0n, 4);                // what ffmpeg writes: zero
+  return box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
+}
+
+/**
+ * A piece shaped like the `segment` muxer's output: header, two fragments and a
+ * trailing random-access index, all in one file.
+ *
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function selfContainedPiece(offsetSeconds) {
+  const mvhdBody = Buffer.alloc(100);
+  mvhdBody.writeUInt32BE(MOVIE_TIMESCALE, 12);
+  const moov = box("moov", Buffer.concat([
+    box("mvhd", mvhdBody),
+    trak(1, VIDEO_TIMESCALE, offsetSeconds),
+    trak(2, AUDIO_TIMESCALE, offsetSeconds)
+  ]));
+  const moof = box("moof", Buffer.concat([traf(1), traf(2)]));
+  const mdat = box("mdat", Buffer.alloc(64, 0x5a));
+  const mfra = box("mfra", Buffer.alloc(24, 0));
+  return Buffer.concat([box("ftyp", Buffer.alloc(16, 0)), moov, moof, mdat, mfra]);
+}
+
+/**
+ * A manager holding one session whose segments are already on disk, cut at
+ * explicit times — the ordinary keyframe-cut path.
+ *
+ * @param {{ segmentFormat?: object }} [overrides]
+ * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string }>}
+ */
+async function managerWithReadySegment(overrides = {}) {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "segment-serve-"));
+  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
+  // Two segments, because a piece is only finished once the next one exists.
+  await writeFile(path.join(dirPath, "segment-00000.mp4"), piece);
+  await writeFile(path.join(dirPath, "segment-00001.mp4"), piece);
+
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    fileName: "video.mkv",
+    startedAt: Date.now(),
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    ffmpeg: null,
+    lastError: "",
+    consumers: new Set(),
+    segmentFormat: overrides.segmentFormat ?? fmp4Format,
+    usesExplicitCuts: true,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentBoundaries: [0, SEGMENT_START_SECONDS, 25],
+    initBytes: fmp4Format.extractInit(piece),
+    encodeStartIndex: 0,
+    firstSegmentLogged: false,
+    waitEpoch: 0
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  return { manager, session, dirPath };
+}
+
+test("a segment that exists is served, not reported as still being produced", async (t) => {
+  const { manager, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(result.kind, "file", "a finished segment on disk must come back as bytes");
+  assert.equal(result.contentType, fmp4Format.segmentContentType);
+
+  const chunks = [];
+  for await (const chunk of result.stream) {
+    chunks.push(chunk);
+  }
+  const served = Buffer.concat(chunks);
+  assert.equal(served.toString("latin1", 4, 8), "moof", "the init header must be stripped off a media segment");
+
+  // The position the PIECE states, carried into the fragment it belongs to.
+  // Reading it is the step that threw in 2.9.124.
+  assert.equal(
+    Number(served.readBigUInt64BE(served.indexOf("tfdt") + 8)),
+    Math.round(SEGMENT_START_SECONDS * VIDEO_TIMESCALE),
+    "the segment must be stamped with where it really begins"
+  );
+});
+
+test("a fault while preparing an existing segment is named, not turned into a wait", async (t) => {
+  const broken = {
+    ...fmp4Format,
+    readSegmentStartSeconds() {
+      throw new ReferenceError("readSelfContainedStartSeconds is not defined");
+    }
+  };
+  const { manager, dirPath } = await managerWithReadySegment({ segmentFormat: broken });
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(
+    result.kind,
+    "failed",
+    "answering 'warming-up' hides the fault and holds every request until the viewer gives up"
+  );
+  assert.match(result.message, /readSelfContainedStartSeconds is not defined/);
+});