@torrent-tv/proxy 2.30.0 → 2.30.1

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.30.1
+
+- **Fix**: A seek was undone a second after it was made. Measured 2026-08-17: the viewer jumped to 2083.4 s, both runs restarted at segment #373 — correctly — and then a request for #371, issued by the player BEFORE the jump and reissued a second later, dragged the encoder back to #370. The viewer sat at #374 waiting for it to return. Two things let that happen, and both are fixed. The behind-head repair refuses a request that is behind the position the VIEWER themselves reported: its existing guard only holds while a seek is still settling, which by then it was not. And a segment request may no longer move the recorded viewer position BACKWARDS past a reported seek — playback only ever moves forward from one, so nothing legitimate is lost, while a stale request can no longer rewrite the viewer's own statement, which is how the repair came to believe it. A reported seek is the viewer stating where they are; a request is evidence about where the player is reading, and evidence may refine a statement forward, never contradict it backwards. Pinned by `test/stale-request-after-seek.test.js`, whose control case shows the same traffic still repairing a genuinely misplaced run when the viewer has said nothing.
+
 ## 2.30.0
 
 - **New**: The speed a step must sustain, and the smallest buffer that hides an interruption, are now COMPUTED from the supply's own behaviour instead of being chosen by hand — printed first, used later. A step producing at `v` gains `v - 1` seconds of cushion per second and an interruption of `W` seconds costs `W`, so it survives its own supply only while `(v - 1) × T > W`, that is `v > 1 + W / T`, with `W` the worst recent wait for a piece and `T` the median interval between such waits. On the field torrent of 2026-08-17 that is **2.42x**, against the 1.5 assumed today and the 1.05 measured on the step that stalled; on the same file's copied stream it is 1.31 against 8x measured, which is why a copy never stalls. The buffer follows from the same readings: one whole segment — the one being played — plus the worst interruption that can arrive before it refills, whichever source it comes from, which was **7-9 s** where the browser waits for 25. Both figures are logged per file every half minute, so the next session says whether the arithmetic describes reality BEFORE anything is decided by it. The arithmetic is a pure module with the field session's own numbers as its tests (`services/supply-margin.js`).

package/package.json

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

package/services/hls-session-manager.js

@@ -4263,6 +4263,26 @@ export class HlsSessionManager {
     if (session.seekSettleTimer != null) {
       return;
     }
+    // And it outranks it AFTERWARDS too, which is what was missing. The guard
+    // above only holds while the settle timer is armed — a second later it is
+    // gone, and a request the browser issued BEFORE the seek is then treated as
+    // fresh evidence. Field 2026-08-17: a seek to 2083.4 s put both runs at
+    // #373, a request for #371 from before it arrived a second afterwards, and
+    // this repair moved the encoder to #370 — three segments behind the viewer,
+    // who waited for it to come back. A request BEHIND what the viewer
+    // themselves reported cannot be describing where they are.
+    const reportedSeconds = Number(session.viewerReportedSeconds);
+    if (Number.isFinite(reportedSeconds)) {
+      const reportedIndex = this.#segmentIndexForTime(session, reportedSeconds);
+      if (index < reportedIndex) {
+        this.#explainHold(
+          session,
+          session.segmentFormat.segmentFileName(index),
+          `it is behind #${reportedIndex}, where the viewer said they are — answered, not obeyed`
+        );
+        return;
+      }
+    }
     // What separates a request the viewer is waiting for from the player
     // scanning the playlist is not TIME but what else it is asking for. On a
     // seek hls.js fires dozens of DIFFERENT indices within half a second (field
@@ -4370,6 +4390,14 @@ export class HlsSessionManager {
     // The browser holds one session id for the whole file and knows nothing of
     // variants, so a seek it reports means the stream on screen.
     named.viewerPositionSeconds = positionSeconds;
+    // What the viewer SAID, kept apart from what requests imply. A request is
+    // evidence about where the player is reading; a reported seek is the viewer
+    // stating where they are, and after one, requests already in flight
+    // describe a place that no longer exists. Field 2026-08-17: a seek to
+    // 2083.4 s restarted both runs at #373, a request for #371 issued before it
+    // arrived a second later, and the encoder was dragged back to #370 — three
+    // segments behind the viewer, who then waited for it to return.
+    named.viewerReportedSeconds = positionSeconds;
     named.lastAccessedAt = Date.now();
     // The audio the viewer is listening to moves with them. It is a separate
     // encoder on a separate session that the browser cannot name, and nothing
@@ -4415,6 +4443,7 @@ export class HlsSessionManager {
       return false;
     }
     session.viewerPositionSeconds = positionSeconds;
+    session.viewerReportedSeconds = positionSeconds;
     session.lastAccessedAt = Date.now();
     // Every segment request being held right now was made for the position the
     // viewer has just left. Release them: hls.js keeps ONE fragment load
@@ -7021,7 +7050,16 @@ export class HlsSessionManager {
         // read when a quality change has to place the next variant's first
         // encode run. The freshest evidence wins: a seek overwrites this, and
         // the first request after the seek overwrites it back.
-        session.viewerPositionSeconds = this.#segmentStartTime(session, requested);
+        // A request refines this only FORWARD of what the viewer reported.
+        // Playback always moves forward from a seek, so nothing legitimate is
+        // lost — while a stale request from before the seek can no longer
+        // rewrite the viewer's own statement, which is what let the repair
+        // below drag the encoder backwards.
+        const requestedStart = this.#segmentStartTime(session, requested);
+        const reported = Number(session.viewerReportedSeconds);
+        if (!Number.isFinite(reported) || requestedStart >= reported) {
+          session.viewerPositionSeconds = requestedStart;
+        }
         // A viewer who has caught up must not wait out the monitor's interval —
         // but only if they HAVE caught up, which is why this re-evaluates the
         // same condition instead of resuming outright.

package/test/stale-request-after-seek.test.js

@@ -0,0 +1,183 @@
+/**
+ * @file A request issued before a seek must not steer the encoder.
+ *
+ * Field 2026-08-17: the viewer seeked to 2083.4 s, both runs restarted at
+ * segment #373, and a request for #371 — issued before the seek and reissued by
+ * the player a second later — moved the encoder to #370. The viewer was at
+ * #374 and waited for the encoder to come back to them.
+ *
+ * The rule pinned here: a reported seek is the viewer STATING where they are; a
+ * segment request is evidence about where the player is reading. Evidence may
+ * refine a statement forward, never contradict it backwards.
+ *
+ * Both cases go through `getFileStream`, the way production reaches the repair,
+ * and the second is the control: without a reported seek the very same traffic
+ * DOES move the encoder, which is what makes the first case a measurement of
+ * the guard rather than of the weather.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { ENCODE_RUN_STATE } from "../services/encode-run-state.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const SEGMENT_SECONDS = 4;
+const RUN_STARTS_AT = 373;
+const BEHIND_INDEX = 371;
+const SESSION_ID = "22222222-3333-4444-5555-666666666666";
+
+/**
+ * A live session whose run begins at #373 and whose directory is empty, so any
+ * segment request is a request for something not yet produced.
+ *
+ * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string }>}
+ */
+async function sessionWithRunAt373() {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "stale-seek-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const boundaries = [];
+  for (let index = 0; index <= 600; index += 1) {
+    boundaries.push(index * SEGMENT_SECONDS);
+  }
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    runState: ENCODE_RUN_STATE.PRODUCING,
+    fileName: "film.mkv",
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    consumers: new Set(),
+    segmentFormat: fmp4Format,
+    usesExplicitCuts: true,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentBoundaries: boundaries,
+    segmentCount: boundaries.length - 1,
+    encodeStartIndex: RUN_STARTS_AT,
+    // A live process: the repair refuses outright when nothing is encoding.
+    ffmpeg: { pid: 1234, killed: false, exitCode: null, signalCode: null, kill() { this.killed = true; } },
+    encodeRunGeneration: 0,
+    runSerial: 1,
+    behindHeadAsks: new Map(),
+    firstWantedAt: new Map(),
+    holdExplainedAt: new Map(),
+    seekSettleTimer: null,
+    seekTarget: null,
+    seekFailureTarget: -1,
+    seekFailureCount: 0,
+    waitEpoch: 0,
+    firstSegmentLogged: true,
+    progress: { processedSeconds: RUN_STARTS_AT * SEGMENT_SECONDS, speed: "1.0x", startPositionSeconds: RUN_STARTS_AT * SEGMENT_SECONDS }
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  return { manager, session, dirPath };
+}
+
+/**
+ * The traffic that dragged the encoder back: the same index asked for twice,
+ * first wanted long enough ago to pass the repair's patience guard.
+ *
+ * @param {object} session
+ */
+function askedTwiceLongEnough(session) {
+  session.firstWantedAt.set(BEHIND_INDEX, Date.now() - 5_000);
+  session.behindHeadAsks.set(BEHIND_INDEX, { count: 3, at: Date.now() });
+}
+
+/**
+ * Put the session down without going through disposal.
+ *
+ * Disposal signals the encoder and waits for it to die, which a stub cannot do
+ * — and none of that is what these tests are about. Clearing the map and any
+ * armed timer leaves nothing running.
+ *
+ * @param {HlsSessionManager} manager
+ * @param {object} session
+ * @param {string} dirPath
+ * @returns {Promise<void>}
+ */
+async function tidy(manager, session, dirPath) {
+  if (session.seekSettleTimer) {
+    clearTimeout(session.seekSettleTimer);
+    session.seekSettleTimer = null;
+  }
+  manager.sessionsById.clear();
+  manager.stop?.();
+  await rm(dirPath, { recursive: true, force: true });
+}
+
+test("a request behind where the viewer said they are does not move the encoder", async (t) => {
+  const { manager, session, dirPath } = await sessionWithRunAt373();
+  t.after(async () => {
+    await tidy(manager, session, dirPath);
+  });
+
+  // The viewer stated their position: 2083.4 s, which is segment #520 here.
+  manager.requestSeek(SESSION_ID, 2083.4);
+  session.encodeStartIndex = RUN_STARTS_AT;
+  askedTwiceLongEnough(session);
+
+  const answer = await manager.getFileStream(
+    SESSION_ID,
+    fmp4Format.segmentFileName(BEHIND_INDEX),
+    { requestSeq: 1 }
+  );
+
+  assert.equal(answer.kind, "warming-up", "the request is answered, not obeyed");
+  // The viewer's own seek legitimately armed a move to #519. What must NOT
+  // happen is the stale request replacing that with #370 — which is exactly
+  // what the field log shows: `seek settle → restart at segment #370`.
+  assert.notEqual(
+    session.seekTarget,
+    BEHIND_INDEX - 1,
+    "a request behind the viewer must not become the encoder's destination"
+  );
+  assert.equal(session.seekTarget, 519, "the viewer's own seek is what the encoder is going to");
+});
+
+test("the same traffic DOES move the encoder when the viewer has said nothing", async (t) => {
+  const { manager, session, dirPath } = await sessionWithRunAt373();
+  t.after(async () => {
+    await tidy(manager, session, dirPath);
+  });
+
+  // No reported seek: a run placed wrongly is exactly what the repair is for,
+  // and this is the case it must keep serving.
+  askedTwiceLongEnough(session);
+
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(BEHIND_INDEX), { requestSeq: 1 });
+
+  assert.equal(
+    session.seekTarget,
+    BEHIND_INDEX - 1,
+    "with nothing said by the viewer, a request stuck behind the head still repairs the run"
+  );
+  assert.notEqual(session.seekSettleTimer, null);
+});
+
+test("a request cannot move the viewer's position backwards", async (t) => {
+  const { manager, session, dirPath } = await sessionWithRunAt373();
+  t.after(async () => {
+    await tidy(manager, session, dirPath);
+  });
+
+  manager.requestSeek(SESSION_ID, 2083.4);
+  await manager.getFileStream(SESSION_ID, fmp4Format.segmentFileName(BEHIND_INDEX), { requestSeq: 1 });
+
+  assert.equal(
+    session.viewerPositionSeconds,
+    2083.4,
+    "a stale request must not rewrite what the viewer reported — that is how the repair came to believe it"
+  );
+});