@torrent-tv/proxy 2.9.129 → 2.9.131

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.9.131
+
+- **Fix**: The first segment of an encoder run is served once the encoder has passed it, instead of waiting for a successor nobody is producing. A segment counted as finished only when the NEXT one had been started — sound while a run moves forward through a file, and meaningless for the segment a run BEGINS at, because the run has only just arrived there. That is precisely the segment a resume or a seek depends on. Measured 2026-08-09 with the hold instrument: `#807 exists, but the next segment (#808) has not been started yet`, held while it lay complete on disk; in August the same shape held `#317` for 46 s and then answered 404 to a browser that had already given up, three releases in a row. A run whose reported output position is past a segment's end has necessarily closed that segment, so that is what decides it now. Covered by a test that builds exactly the resume shape — a run start with no successor on disk — and insists on the bytes.
+
+## 2.9.130
+
+- **New**: A segment being held says WHY, at most once every five seconds per file. A hold was silent, and that silence has now cost three releases: a file that exists, a route answering "not yet", and nothing anywhere naming which of the several reasons applied. Measured 2026-08-09 — a run begun mid-file at segment #317 produced two minutes of video from #317 upwards at 10.5x, while #317 itself was held 46 s and then answered 404 once the browser had given up, with not one line about the cause. The line names the reason, the segment the run began at, where the viewer is, whether the encoder is alive, and which index was asked for. The case that matters most is called out on its own: the first segment of a run started mid-file is held by a rule that waits for the NEXT one to exist, and that is exactly the segment a resume depends on.
+
 ## 2.9.129
 
 - **New**: A held segment says why it is held. A hold was silent, and that silence has now cost three releases: a file that exists, a route answering "not yet", and nothing saying which of the several reasons applied. Measured 2026-08-09 — a run begun mid-file at segment #317 produced two minutes of video from #317 upwards at 10.5x while #317 itself was held for 46 116 ms and then answered 404, once the browser had already given up. At most once every five seconds per file it now names the reason (not on disk, or present but the next segment has not been started), together with the index the run began at, where the viewer is, and whether the encoder is alive. The readiness rule — a segment counts as finished once the NEXT one exists — is the suspect for a resume, because for the first segment of a mid-file run that rule decides whether playback begins at all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.129",
+  "version": "2.9.131",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/hls-session-manager.js

@@ -3404,12 +3404,27 @@ export class HlsSessionManager {
         const isLast = index >= Math.max(0, (session.segmentBoundaries?.length ?? 1) - 2);
         if (!isLast && session.ffmpeg) {
           const nextPath = path.join(session.dirPath, session.segmentFormat.segmentFileName(index + 1));
+          // The FIRST segment of a run cannot be judged by "the next one
+          // exists": nothing is producing a next one yet, because the run has
+          // only just begun here. Waiting for it holds precisely the segment a
+          // resume depends on — measured 2026-08-09, #807 held while it lay on
+          // disk, and in August the same shape held #317 for 46 s and then
+          // answered 404 to a browser that had given up.
+          //
+          // What "finished" means for it is that the encoder has moved PAST the
+          // end of its span. ffmpeg reports the output timestamp of its last
+          // encoded frame, so a run whose position is beyond this segment's end
+          // has necessarily closed it.
+          const isRunStart = index === (session.encodeStartIndex ?? -1);
+          const encoderPosition = Number(session.progress?.processedSeconds);
+          const segmentEnd = this.#segmentStartTime(session, index + 1);
+          if (isRunStart && Number.isFinite(encoderPosition) && encoderPosition > segmentEnd) {
+            // Past its end — it is complete, whatever the directory says about
+            // what comes next.
+          } else {
           try {
             await access(nextPath);
           } catch {
-            // The rule is "finished once the NEXT one has been started". For the
-            // FIRST segment of a run begun mid-file this is the one that decides
-            // whether a resume plays at all, so it must say so out loud.
             this.#explainHold(
               session,
               fileName,
@@ -3417,6 +3432,7 @@ export class HlsSessionManager {
             );
             return { kind: "warming-up" };
           }
+          }
         }
       }
       // Cold-start: log the first servable SEGMENT of this session exactly once

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

@@ -1,205 +1,228 @@
-/**
- * @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/);
-});
+/**
+ * @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/);
+});
+
+test("a run's FIRST segment is served once the encoder has passed it, without waiting for a next one", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The shape a resume takes: a run begun mid-file, so its first segment has no
+  // successor and nothing is producing one. Waiting for that successor is what
+  // held #317 for 46 s and then answered 404 to a browser that had given up.
+  await rm(path.join(dirPath, "segment-00001.mp4"));
+  session.encodeStartIndex = 0;
+  session.ffmpeg = { killed: true, kill() {} };
+  session.progress = { processedSeconds: SEGMENT_START_SECONDS + 10 };
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(
+    result.kind,
+    "file",
+    "the encoder is past this segment's end, so it is finished — the absence of a next one says nothing"
+  );
+});