@torrent-tv/proxy 2.30.0 → 2.30.2

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.30.2
+
+- **Fix**: The cut-time shift of 2.28.0 is reverted — the field measured it and it moved the cuts OFF the source's keyframes rather than onto them. Of 75 pieces the picture produced afterwards, only **nine** began at a time the container's own table names, against **70 of 75** for the soundtrack, which the change never touched; the median distance from the playlist went from 0.04 s to 4.33 s. Before it, every piece began exactly on a named keyframe and it was the playlist that disagreed with them — which is the correction path's business, not the cut list's. The reasoning that produced the shift (that the muxer decides its cuts before the output is relabelled) was argued from ffmpeg's semantics rather than measured, and the measurement says otherwise.
+- **Fix**: The steering line compared two different things. `steered onto N of M holders` summed the successes over every attempt of a wait while taking M from the last attempt alone, which is how the log came to read `steered onto 12 of 6 holders`. Both halves are now totals over the same attempts: `steered onto N of M asks (K peers held it)`.
+
+## 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.2",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/hls-session-manager.js

@@ -3567,30 +3567,22 @@ export class HlsSessionManager {
     const gridCutTimes = explicitTimes && (!session.transcodeVideo || session.cutGrid === "keyframe")
       ? segmentCutTimesFrom(session.segmentBoundaries, safeIndex)
       : null;
-    // On the COPY branch the muxer decides its cuts against the source's own
-    // timestamps, not against the labels we ask it to write. That branch keeps
-    // the source's timestamps (`-copyts`) and re-labels the output 0-based with
-    // `-output_ts_offset -sourceStartTime`; the cut list, being applied before
-    // that relabelling, must therefore be stated in the SOURCE's terms.
+    // Cut times are stated on the grid, for both branches.
     //
-    // Measured 2026-08-17, and this is the whole of the trouble: asked to cut
-    // at 808.808 s on the 0-based grid, ffmpeg cut at 806.806 s — exactly
-    // `sourceStartTime` (2.002 s) early, and 806.806 s is itself a keyframe the
-    // container's table names, which is why every "disagreement" landed on
-    // another real keyframe. The soundtrack, which is re-encoded and takes the
-    // other branch, cut where it was asked. The two then told the shared
-    // boundary table different things and corrected each other back and forth
-    // for the whole session (#202: 808.808 → 806.806 → 808.750 → …), so the
-    // playlist and the media drifted apart by a whole segment and the player
-    // refetched what it could not place.
+    // 2.28.0 added `sourceStartTime` to them on the copy branch, reasoning that
+    // the muxer decides its cuts before the output is relabelled. The field
+    // measured it the next session and the reasoning was wrong: of 75 pieces
+    // the picture produced, only NINE began at a time the container's own
+    // keyframe table names (the soundtrack, untouched by the change, scored 70
+    // of 75). Before it, every piece began exactly on a named keyframe and it
+    // was the PLAYLIST that disagreed with them. So the shift moved the cuts
+    // OFF the keyframes rather than onto them, and it is gone.
     //
-    // Nothing here is a guess about ffmpeg's semantics: the shift is the same
-    // one the seek already applies on this branch (`seekSeconds = startSeconds
-    // + sourceStartTime`), and the field measurement above is what says the
-    // cuts needed it too.
-    const cutTimes = gridCutTimes && onKeyframeGridFor(session) && sourceStartTime !== 0
-      ? gridCutTimes.map((time) => Number((time + sourceStartTime).toFixed(6)))
-      : gridCutTimes;
+    // What remains true, and is what that measurement is really about: the
+    // picture cuts where the source's keyframes are, and the playlist must be
+    // built from those same times. That is the correction path's job, not the
+    // cut list's.
+    const cutTimes = gridCutTimes;
 
     // A second chance for a predecessor that survived the escalation above —
     // the first block is the one that does the work. Its exit is ignored
@@ -4263,6 +4255,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 +4382,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 +4435,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 +7042,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/services/torrent-worker/fastest-wires.js

@@ -87,7 +87,7 @@ function speedOf(wire) {
  * @param {object} torrent
  * @param {number} pieceIndex
  * @param {number} [limit] - How many wires to push it onto.
- * @returns {{ asked: number, considered: number, fastestBytesPerSecond: number }}
+ * @returns {{ asked: number, attempted: number, considered: number, fastestBytesPerSecond: number }}
  *   `asked` counts requests the library actually placed: it refuses when a
  *   wire's pipeline is full or when nothing can be reserved even with hotswap,
  *   and that refusal is information — a piece nobody can be asked for is
@@ -95,7 +95,7 @@ function speedOf(wire) {
  */
 export function askFastestWiresFor(torrent, pieceIndex, limit = 3) {
   if (!canPlaceRequests(torrent) || !Number.isInteger(pieceIndex) || pieceIndex < 0) {
-    return { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+    return { asked: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 };
   }
   const candidates = wiresForPiece(torrent, pieceIndex);
   let asked = 0;
@@ -116,6 +116,13 @@ export function askFastestWiresFor(torrent, pieceIndex, limit = 3) {
   return {
     asked,
     considered: candidates.length,
+    // How many of the asks the library placed, against how many it was asked
+    // for. The caller sums these over the whole wait, and summing `asked`
+    // against a `considered` taken from the LAST attempt is how the field log
+    // came to read "steered onto 12 of 6 holders" — a ratio of two different
+    // things. Both halves are returned per attempt so the caller can add each
+    // to its own total.
+    attempted: Math.min(candidates.length, Math.max(1, limit)),
     fastestBytesPerSecond: candidates.length > 0 ? speedOf(candidates[0]) : 0
   };
 }

package/services/torrent-worker/piece-reader.js

@@ -517,12 +517,15 @@ export async function* readFragments({
       // holder delivers — measured 2026-08-17, the swarm had a fivefold surplus
       // of bandwidth and the reader still waited 1.0-4.5 s, 47 times in two
       // minutes, on pieces five peers already had.
-      let pushed = { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+      let pushed = { asked: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 };
       const pushToFastest = () => {
         try {
           const result = askFastestWiresFor(torrent, pieceIndex);
           pushed = {
             asked: pushed.asked + result.asked,
+            // Summed like the successes, so the line compares two totals over
+            // the same attempts instead of a total against a snapshot.
+            attempted: (pushed.attempted ?? 0) + result.attempted,
             considered: result.considered,
             fastestBytesPerSecond: result.fastestBytesPerSecond
           };
@@ -592,7 +595,7 @@ export async function* readFragments({
             // What WE did about it, so the next session says whether steering
             // the piece onto faster holders shortens the tail — by number
             // rather than by impression.
-            `; steered onto ${pushed.asked} of ${pushed.considered} holders` +
+            `; steered onto ${pushed.asked} of ${pushed.attempted} asks (${pushed.considered} peers held it)` +
             (pushed.fastestBytesPerSecond > 0
               ? `, fastest ${Math.round(pushed.fastestBytesPerSecond / 1024)}KB/s`
               : "")

package/test/fastest-wires.test.js

@@ -97,7 +97,7 @@ test("a build without the request entry is reported, not silently skipped", () =
   assert.equal(canPlaceRequests({ wires: [] }), false);
   assert.equal(canPlaceRequests({ wires: [], _request: () => true }), true);
   const result = askFastestWiresFor({ wires: [wire({ speed: 1 })] }, 1);
-  assert.deepEqual(result, { asked: 0, considered: 0, fastestBytesPerSecond: 0 });
+  assert.deepEqual(result, { asked: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 });
 });
 
 test("a wire that cannot say how fast it is ranks last rather than throwing", () => {

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"
+  );
+});