@torrent-tv/proxy 2.30.1 → 2.31.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.31.0
+
+- **Chore**: The encoder run's two status strings are gone; both are now outputs of the state table shipped in 2.23.0. `session.progress.state` was maintained by hand at seven sites and `session.state` at nine, and neither could answer on its own — the warm-up test had to read both under an `||`, because one said "starting" from the first spawn until something overwrote it while the other said it again on its own schedule. What the browser is told is computed where it is sent (`wireState(runState)`), and `session.state` is reduced to the session's own lifetime: it exists, or it has been disposed. That deletes the line in the spawn path that read `state === "disposed" ? "disposed" : "starting"` — two lifetimes in one variable, which is what it was there to paper over. Verified before the change that nothing in the browser reads the wire string, so the value set is unchanged and unobserved either way; the four values it can take are the same four as before.
+
+## 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.

package/package.json

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

package/services/hls-session-manager.js

@@ -25,7 +25,8 @@ import {
   ENCODE_RUN_STATE,
   INITIAL_RUN_STATE,
   nextState,
-  processCanBeSignalled
+  processCanBeSignalled,
+  wireState
 } from "./encode-run-state.js";
 import { ENCODE_EXIT, classifyEncodeExit } from "./encode-exit.js";
 
@@ -1854,17 +1855,23 @@ export class HlsSessionManager {
       sourceMapKey,
       fileName: logName,
       dirPath: sessionDir,
-      state: "starting",
+      // The SESSION's own lifetime, and nothing else: it exists, or it has been
+      // disposed. It used to carry the encoder run's status as well, which is
+      // why one line in the spawn path read `state === "disposed" ? "disposed"
+      // : "starting"` — two lifetimes in one variable. The run's status lives
+      // in `runState`.
+      state: "live",
       startedAt: Date.now(),
       lastAccessedAt: Date.now(),
       ffmpeg: null,
       encodeRunGeneration: 0,
       // What the ENCODER RUN is doing, as one control state from the table in
-      // `encode-run-state.js`. Written at every event today and read by nothing
-      // yet: a refused pair in the log is the model disagreeing with reality,
-      // and that disagreement is the measurement this release exists to take.
-      // The fields it replaces — `state`, `progress.state`
-      // and the repeated liveness checks — keep their current writes meanwhile.
+      // `encode-run-state.js`. Every question about the run is now answered
+      // from here: whether a process can be signalled, whether anything is
+      // reading the input, what a missing segment is answered with, and what
+      // the browser is told. The three representations it replaced — a status
+      // string, a second status string on the wire, and a child-process handle
+      // consulted at ten sites — could disagree with each other, and did.
       runState: INITIAL_RUN_STATE,
       lastError: "",
       // Cold-start timing: entry timestamp + a once-guard so the first servable
@@ -2007,7 +2014,10 @@ export class HlsSessionManager {
       seekFailureTarget: -1,
       seekFailureCount: 0,
       progress: {
-        state: "starting",
+        // No `state` here. What the browser is told is `wireState(runState)`,
+        // computed where it is sent — a Moore output rather than a field
+        // maintained by hand at seven sites, which is how it came to be read
+        // together with `session.state` under an `||`.
         processedSeconds: 0,
         startPositionSeconds: 0,
         totalSeconds: hasDuration ? durationSeconds : null,
@@ -2099,7 +2109,7 @@ export class HlsSessionManager {
       await this.waitUntilReady(session);
       return session;
     } catch (error) {
-      if (session.state === "failed") {
+      if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
         await this.disposeSession(session.id);
         throw error;
       }
@@ -3253,7 +3263,7 @@ export class HlsSessionManager {
       if (
         !session ||
         session.state === "disposed" ||
-        session.state === "failed" ||
+        session.runState === ENCODE_RUN_STATE.ENDED_FAILED ||
         !session.transcodeVideo ||
         // Nothing is encoding, so there is no speed to judge. A variant the
         // viewer has switched away from is left in exactly this state, and its
@@ -3567,30 +3577,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
@@ -3820,8 +3822,6 @@ export class HlsSessionManager {
     session.encodeStartIndex = safeIndex;
     session.pendingRestartIndex = -1;
     session.lastRestartAt = Date.now();
-    session.state = session.state === "disposed" ? "disposed" : "starting";
-    session.progress.state = "running";
     session.progress.processedSeconds = startSeconds;
     session.progress.startPositionSeconds = startSeconds;
     session.progress.updatedAt = Date.now();
@@ -3920,7 +3920,6 @@ export class HlsSessionManager {
         } else if (key === "speed") {
           session.progress.speed = value;
         } else if (key === "progress") {
-          session.progress.state = value === "end" ? "ready" : "running";
         }
         const metrics = computeProgressMetrics(
           session.progress.processedSeconds,
@@ -3956,9 +3955,7 @@ export class HlsSessionManager {
       if (!this.#isCurrentRun(session, ffmpeg)) {
         return;
       }
-      session.state = "failed";
       session.lastError = error instanceof Error ? error.message : String(error);
-      session.progress.state = "failed";
       session.progress.updatedAt = Date.now();
       this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_FAILED);
       logger.error(`ffmpeg ${session.id} process error: ${session.lastError}`);
@@ -3997,9 +3994,7 @@ export class HlsSessionManager {
         // segment nobody was making. So the claim is checked against the
         // playlist we published, and a run that stopped short is a FAILURE that
         // can be restarted, not a finished file.
-        session.state = "failed";
-        session.progress.state = "failed";
-        session.progress.updatedAt = Date.now();
+            session.progress.updatedAt = Date.now();
         session.lastError =
           `input ended after segment #${producedThrough} of ${expectedLast} — ` +
           "the source stopped delivering data";
@@ -4011,8 +4006,6 @@ export class HlsSessionManager {
         return;
       }
       if (outcome === ENCODE_EXIT.COMPLETE) {
-        session.state = "ready";
-        session.progress.state = "ready";
         session.progress.updatedAt = Date.now();
         this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_COMPLETE);
         logger.info(`transcode ${session.id} encode-run complete "${session.fileName}"`);
@@ -4074,11 +4067,9 @@ export class HlsSessionManager {
       // stays for what it was built for, a target that genuinely cannot be
       // encoded; it must not condemn a session whose data merely went away.
       if (outcome === ENCODE_EXIT.INPUT_LOST) {
-        session.state = "recovering";
         // On the wire it is simply "not ready yet" — a state the browser has
         // always known how to wait through. Only the proxy needs the
         // distinction between waiting for data and having given up.
-        session.progress.state = "starting";
         session.progress.updatedAt = Date.now();
         this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_INPUT_LOST);
         session.inputRetryCount = (session.inputRetryCount ?? 0) + 1;
@@ -4093,7 +4084,7 @@ export class HlsSessionManager {
         );
         session.inputRetryTimer = setTimeout(() => {
           session.inputRetryTimer = null;
-          if (session.state !== "recovering") {
+          if (session.runState !== ENCODE_RUN_STATE.RETRY_WAIT) {
             return;
           }
           this.#transitionRun(session, ENCODE_RUN_EVENT.RETRY_DUE);
@@ -4105,8 +4096,6 @@ export class HlsSessionManager {
         session.inputRetryTimer.unref?.();
         return;
       }
-      session.state = "failed";
-      session.progress.state = "failed";
       session.progress.updatedAt = Date.now();
       this.#transitionRun(session, ENCODE_RUN_EVENT.EXITED_FAILED);
       logger.error(
@@ -4587,10 +4576,9 @@ export class HlsSessionManager {
     // Individual segments are long-polled by the segment route as ffmpeg
     // produces them.
     if (session.useSyntheticPlaylist) {
-      if (session.state === "failed") {
+      if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
         throw new Error(session.lastError || "ffmpeg failed to start HLS session.");
       }
-      session.state = "ready";
       return;
     }
 
@@ -4598,15 +4586,14 @@ export class HlsSessionManager {
     const deadline = Date.now() + this.startupWaitMs;
 
     while (Date.now() < deadline) {
-      if (session.state === "failed") {
+      if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
         throw new Error(session.lastError || "ffmpeg failed to start HLS session.");
       }
       try {
         await access(playlistPath);
         const text = await readFile(playlistPath, "utf8");
         if (text.includes("#EXTM3U")) {
-          session.state = "ready";
-          return;
+            return;
         }
       } catch (_error) {
         // Playlist is not ready yet.
@@ -5122,7 +5109,14 @@ export class HlsSessionManager {
     const median = deviations.length > 0 ? deviations[Math.floor(deviations.length / 2)] : 0;
     const landed = check.landedOnAnotherKeyframe ?? 0;
     logger.info(
-      `keyframe-index ${session.containerFormat || "unknown"} "${session.fileName}": ` +
+      // The session id, because without it this line cannot be attributed. A
+      // family produces one summary per member — the picture and each
+      // soundtrack — and on 2026-08-17 the picture's was read as the sound's,
+      // from a neighbouring log line, and a roadmap item was written against
+      // the wrong half of the stream. The id is the only thing that says whose
+      // reading this is.
+      `keyframe-index ${session.id.slice(0, 8)} ${session.audioOnly === true ? "sound" : "picture"} ` +
+      `${session.containerFormat || "unknown"} "${session.fileName}": ` +
       `${check.disagreed} of ${check.checked} produced segments started away from the playlist, ` +
       `median ${median.toFixed(3)}s worst ${check.maxDeviationSec.toFixed(3)}s` +
       (check.firstDisagreementIndex >= 0 ? ` (first at #${check.firstDisagreementIndex})` : "") +
@@ -5382,7 +5376,7 @@ export class HlsSessionManager {
     if (
       !session ||
       session.state === "disposed" ||
-      session.state === "failed" ||
+      session.runState === ENCODE_RUN_STATE.ENDED_FAILED ||
       !session.ffmpeg ||
       session.runState === ENCODE_RUN_STATE.SUSPENDED
     ) {
@@ -6931,13 +6925,13 @@ export class HlsSessionManager {
     if (!session || !isSafeFileName(fileName, session.segmentFormat)) {
       return { kind: "not-found" };
     }
-    if (session.state === "recovering") {
+    if (session.runState === ENCODE_RUN_STATE.RETRY_WAIT) {
       // The data went away and is being fetched again. Holding the request is
       // the truthful answer: nothing is broken and there is nothing for the
       // viewer to retry.
       return { kind: "warming-up" };
     }
-    if (session.state === "failed") {
+    if (session.runState === ENCODE_RUN_STATE.ENDED_FAILED) {
       return {
         kind: "failed",
         message: session.lastError || "ffmpeg failed for this transcode session."
@@ -7504,7 +7498,11 @@ export class HlsSessionManager {
     session.lastAccessedAt = Date.now();
     const warmupTotalSeconds = this.startupWaitMs / 1000;
     const warmupElapsedSeconds = Math.max(0, (Date.now() - session.startedAt) / 1000);
-    const isWarmupPhase = session.state === "starting" || session.progress.state === "starting";
+    // One question, one answer. This used to read BOTH strings with `||`
+    // because neither could answer alone: `session.state` said "starting" from
+    // the first spawn until something else overwrote it, and `progress.state`
+    // said it again on its own schedule.
+    const isWarmupPhase = wireState(session.runState) === "starting";
     const warmupPercent = isWarmupPhase
       ? Math.max(0, Math.min(100, (warmupElapsedSeconds / warmupTotalSeconds) * 100))
       : null;
@@ -7522,7 +7520,7 @@ export class HlsSessionManager {
       // The id the caller asked about, not the variant it was answered from —
       // the browser tracks its sessions by the id it was given.
       sessionId: named.id,
-      state: session.progress.state,
+      state: wireState(session.runState),
       processedSeconds: session.progress.processedSeconds,
       startPositionSeconds: session.progress.startPositionSeconds ?? 0,
       totalSeconds: session.progress.totalSeconds,
@@ -7562,7 +7560,7 @@ export class HlsSessionManager {
       expectedSessionCreateMs: this.expectedSessionCreateMs(),
       expectedFirstSegmentMs: this.expectedFirstSegmentMs(),
       updatedAt: session.progress.updatedAt,
-      error: session.state === "failed" ? session.lastError : ""
+      error: session.runState === ENCODE_RUN_STATE.ENDED_FAILED ? session.lastError : ""
     };
   }
 

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", () => {