@torrent-tv/proxy 2.21.1 → 2.23.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2.23.0
+
+- **New**: The encoder run is a transition table, and the table is the specification rather than a description of code written elsewhere. `services/encode-run-state.js` declares eight states, ten events named for what happened, two superstates and the answers each state gives — whether the input is being read, whether the process can be signalled, what a missing segment gets, what the browser is told, whether a restart is allowed. What it buys is not tidiness: five field failures in a row were empty cells — a pair of state and event nobody had considered — and a table makes an empty cell visible before a release. The edges that must NEVER exist are data too, each naming the release it cost: the 2.9.93 sawtooth where any segment request released a suspended encoder, and the 2.9.93 dead-run shortcut where the handle pointed at a corpse and every later seek was waved through as already covered.
+- **New**: Every transition a real run makes is logged as state, event and target (`run-state <id> STARTING --FIRST_SEGMENT--> PRODUCING`), and a pair the table does not declare is logged as a refusal instead of being obeyed. Nothing READS the state yet — the fields it will replace keep their current writes — because whether the model matches reality is a measurement to take in the field, not an assumption to build on. This release exists to take it.
+- **New**: The picture in `docs/encode-run-state.md` is rendered FROM the table (`npm run graph`), and a test regenerates it and compares, so a drawing that disagrees with the code cannot be committed.
+- **Fix**: The ffmpeg a seek kills is no longer handled as the session's own run dying — and this was found by writing the table down, before it shipped. The exit handler decides whether an exit is its own by comparing against `session.ffmpeg`, and during a restart that field still names the process being killed, because the replacement is spawned a few hundred lines later. So every seek and every quality switch ran the failure branch for its predecessor: a spurious `failed` for the moment between the kill and the spawn, which a segment request landing in that window is answered 500 for; a fast-failure tally against a target that never failed; and on any host with a hardware encoder, the runtime safety net firing on each seek — the proxy downgraded itself to libx264 permanently and started an extra run at the OLD index, which took the generation and made the real restart abort. A process is now marked superseded BEFORE it is signalled.
+- **Fix**: Losing the torrent's data no longer condemns a working hardware encoder. The hardware-failure fallback was asked of every non-zero exit, including a run that died because its input went away — which says nothing about the encoder. What an exit means is now classified in one place (`services/encode-exit.js`, tested by its four field cases) and the fallback is asked only of a genuine encoder failure.
+
+- **Fix**: What the torrent costs this machine can actually be measured now. The reading is taken when no encoder is RUNNING, and a SUSPENDED encoder was being counted as one — so on a host with two sessions parked by the look-ahead cap the moment never arrived: measured 2026-08-15, four minutes of `encoders=0 running +2 suspended` in which the price could have been taken and was not. A suspended encoder costs nothing, which is exactly why that moment is the right one.
+
+## 2.22.0
+
+- **Fix**: What a rung is OFFERED on is the startup measurement again, not the figure learned from a live session. The startup one is taken on a quiet machine against known clips and does not move; the learned one moves with whatever else the box was doing that second, and three field sessions in a row show the price of that: decoding learned at 0.87x, then at 1.34-1.57x, against calibration's 2.6x — each reading refusing another rung until the offer held a single height and the quality menu vanished with it.
+- **New**: A live reading keeps the one thing it is authority on — itself. A rung that has actually been seen running below realtime, with the machine to itself, is withdrawn on that evidence whatever any prediction says. A rung nobody has run is judged by the startup measurement like any other, because a measurement of one rung is not a prediction about the rest.
+
 ## 2.21.1
 
 - **Fix**: A cost is learned only from an encoder that had the machine to itself. Beside another encoder a reading already contains that other work, and the budget then ADDS the same work again when it predicts — so the price of a file grew with every reading. Measured in the field 2026-08-15: copying, whose truth is 7.9x, was learned as 2.03x; decoding, whose calibration clips say 2.6x, as 0.87x. Every re-encoded rung was then refused (`not offering 720p=0.56x … 240p=0.66x`), the offer collapsed to the one copied height, and the viewer lost the quality menu entirely.

package/docs/encode-run-state.md

@@ -0,0 +1,96 @@
+<!-- GENERATED from services/encode-run-state.js by scripts/render-run-graph.js.
+     Do not edit by hand: change the table and run `npm run graph`. -->
+
+# The encoder run — states and transitions
+
+One run of one ffmpeg inside one transcode session. The table this is drawn
+from is executed by `services/hls-session-manager.js`; every transition a real
+run makes is logged as state, event and target, so a run that takes an edge
+absent here is a violation the log names.
+
+```mermaid
+stateDiagram-v2
+    state RUN {
+        [*] --> IDLE
+        state WORKING {
+            state ALIVE {
+                STARTING
+                PRODUCING
+                SUSPENDED
+            }
+            RETRY_WAIT
+        }
+        IDLE
+        STOPPED
+        ENDED_COMPLETE
+        ENDED_FAILED
+    }
+
+    RUN --> STARTING : SPAWNED
+    WORKING --> STOPPED : STOP_ORDERED
+    ALIVE --> SUSPENDED : SUSPEND_ORDERED
+    ALIVE --> ENDED_COMPLETE : EXITED_COMPLETE
+    ALIVE --> ENDED_FAILED : EXITED_SHORT
+    ALIVE --> RETRY_WAIT : EXITED_INPUT_LOST
+    ALIVE --> ENDED_FAILED : EXITED_FAILED
+    STARTING --> PRODUCING : FIRST_SEGMENT
+    SUSPENDED --> PRODUCING : RESUME_ORDERED
+    RETRY_WAIT --> IDLE : RETRY_DUE
+```
+
+## States
+
+| state | means |
+|---|---|
+| `IDLE` | No process, and one is expected — before the first run, or after a retry timer fired. |
+| `STARTING` | Spawned; this run has produced nothing servable yet. |
+| `PRODUCING` | This run has produced at least one servable segment. |
+| `SUSPENDED` | SIGSTOP delivered, process alive — and nothing is reading the input. |
+| `RETRY_WAIT` | The input went away; a restart is timed. Requests are held, not refused. |
+| `STOPPED` | Stopped on purpose with no replacement — a rung the viewer switched away from. |
+| `ENDED_COMPLETE` | Ran through the last segment of the file. Nothing is owed. |
+| `ENDED_FAILED` | Terminal for this target: requests are answered as failures. |
+
+## Events
+
+| event | means |
+|---|---|
+| `SPAWNED` | A process was spawned for this session. |
+| `FIRST_SEGMENT` | The first servable segment of this run was served. |
+| `SUSPEND_ORDERED` | SIGSTOP was delivered. |
+| `RESUME_ORDERED` | SIGCONT was sent. |
+| `STOP_ORDERED` | The run was stopped with no replacement. |
+| `EXITED_COMPLETE` | Exit 0, having produced through the last segment. |
+| `EXITED_SHORT` | Exit 0, short of the last segment — the input dried up. |
+| `EXITED_INPUT_LOST` | Died because the input was not there. Recoverable. |
+| `EXITED_FAILED` | Died for any other reason, or could not be spawned. |
+| `RETRY_DUE` | The input-retry timer fired. |
+
+## What each state answers
+
+Outputs depend on the state alone — computed here by calling the same
+functions the session manager calls.
+
+| state | reads its input | can be signalled | a missing segment | on the wire | may restart |
+|---|---|---|---|---|---|
+| `IDLE` | no | no | hold | `starting` | yes |
+| `STARTING` | yes | yes | hold | `running` | yes |
+| `PRODUCING` | yes | yes | hold | `running` | yes |
+| `SUSPENDED` | no | yes | hold | `running` | yes |
+| `RETRY_WAIT` | no | no | hold | `starting` | yes |
+| `STOPPED` | no | no | hold | `running` | yes |
+| `ENDED_COMPLETE` | no | no | hold | `ready` | no |
+| `ENDED_FAILED` | no | no | fail | `failed` | yes |
+
+## Edges that must never exist
+
+The machine's real content: a near-complete digraph asserts nothing.
+
+| from | event | must not reach | because |
+|---|---|---|---|
+| `SUSPENDED` | `FIRST_SEGMENT` | `PRODUCING` | a segment request must not release a suspended encoder — 2.9.93, where any request did, and the run sawtoothed from 155 s to 922 s ahead of the viewer in three minutes |
+| `ENDED_FAILED` | `FIRST_SEGMENT` | `PRODUCING` | a dead run is not a producing one — 2.9.93, where the handle pointed at a corpse and every later seek was waved through as already covered, so the session answered 500 for ever |
+| `ENDED_FAILED` | `RESUME_ORDERED` | `PRODUCING` | there is no process to continue; only a spawn leads out of a failure |
+| `IDLE` | `FIRST_SEGMENT` | `PRODUCING` | nothing produces before a process exists |
+| `RETRY_WAIT` | `FIRST_SEGMENT` | `PRODUCING` | a run waiting for its input back has no process; only a spawn resumes production |
+| `STOPPED` | `RESUME_ORDERED` | `PRODUCING` | a rung the viewer switched away from must not be revived by its own held requests — the host has one encoder's worth of capacity and the rung on screen needs it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.21.1",
+  "version": "2.23.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -20,6 +20,7 @@
     "start": "node ./bin/cli.js",
     "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
     "test": "npm run lint && node --test",
+    "graph": "node scripts/render-run-graph.js",
     "lint": "biome lint ."
   },
   "dependencies": {

package/scripts/render-run-graph.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * @file Render the encoder-run table as a document, FROM the table.
+ *
+ * The picture is not drawn beside the code — it is produced from the same data
+ * the code executes, so it cannot describe a machine that no longer exists. A
+ * test regenerates it and compares, which is what makes "the table is the
+ * single source" enforceable rather than a promise.
+ *
+ * Run it with `npm run graph`.
+ */
+
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  ABSENT_EDGE_INVARIANTS,
+  ENCODE_RUN_EVENT,
+  ENCODE_RUN_STATE,
+  EVENT_MEANING,
+  INITIAL_RUN_STATE,
+  STATE_MEANING,
+  answerForMissingSegment,
+  declaredContainment,
+  declaredEdges,
+  isInputBeingRead,
+  mayRestart,
+  processCanBeSignalled,
+  wireState
+} from "../services/encode-run-state.js";
+
+/** Where the rendered document lives. */
+export const GRAPH_DOC_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "docs",
+  "encode-run-state.md"
+);
+
+const ALL_STATES = Object.values(ENCODE_RUN_STATE);
+const ALL_EVENTS = Object.values(ENCODE_RUN_EVENT);
+
+/**
+ * Children of each node of the containment tree, in declaration order.
+ *
+ * @returns {{ root: string, childrenOf: Map<string, string[]> }}
+ */
+function containmentTree() {
+  const childrenOf = new Map();
+  let root = null;
+  for (const { state, parent } of declaredContainment()) {
+    if (parent === null) {
+      root = state;
+      continue;
+    }
+    if (!childrenOf.has(parent)) {
+      childrenOf.set(parent, []);
+    }
+    childrenOf.get(parent).push(state);
+  }
+  return { root, childrenOf };
+}
+
+/**
+ * One composite block, and everything nested inside it.
+ *
+ * @param {string} node
+ * @param {Map<string, string[]>} childrenOf
+ * @param {number} depth
+ * @returns {string[]} Lines, already indented.
+ */
+function renderBlock(node, childrenOf, depth) {
+  const pad = "    ".repeat(depth);
+  const children = childrenOf.get(node) ?? [];
+  if (children.length === 0) {
+    return [`${pad}${node}`];
+  }
+  const lines = [`${pad}state ${node} {`];
+  if (children.includes(INITIAL_RUN_STATE)) {
+    lines.push(`${pad}    [*] --> ${INITIAL_RUN_STATE}`);
+  }
+  for (const child of children) {
+    lines.push(...renderBlock(child, childrenOf, depth + 1));
+  }
+  lines.push(`${pad}}`);
+  return lines;
+}
+
+/**
+ * The whole document.
+ *
+ * @returns {string}
+ */
+export function renderRunGraphMarkdown() {
+  const { root, childrenOf } = containmentTree();
+  const lines = [];
+
+  lines.push(
+    "<!-- GENERATED from services/encode-run-state.js by scripts/render-run-graph.js.",
+    "     Do not edit by hand: change the table and run `npm run graph`. -->",
+    "",
+    "# The encoder run — states and transitions",
+    "",
+    "One run of one ffmpeg inside one transcode session. The table this is drawn",
+    "from is executed by `services/hls-session-manager.js`; every transition a real",
+    "run makes is logged as state, event and target, so a run that takes an edge",
+    "absent here is a violation the log names.",
+    "",
+    "```mermaid",
+    "stateDiagram-v2"
+  );
+  lines.push(...renderBlock(root, childrenOf, 1));
+  lines.push("");
+  for (const edge of declaredEdges()) {
+    lines.push(`    ${edge.from} --> ${edge.to} : ${edge.event}`);
+  }
+  lines.push("```", "");
+
+  lines.push("## States", "", "| state | means |", "|---|---|");
+  for (const state of ALL_STATES) {
+    lines.push(`| \`${state}\` | ${STATE_MEANING[state]} |`);
+  }
+  lines.push("");
+
+  lines.push("## Events", "", "| event | means |", "|---|---|");
+  for (const event of ALL_EVENTS) {
+    lines.push(`| \`${event}\` | ${EVENT_MEANING[event]} |`);
+  }
+  lines.push("");
+
+  lines.push(
+    "## What each state answers",
+    "",
+    "Outputs depend on the state alone — computed here by calling the same",
+    "functions the session manager calls.",
+    "",
+    "| state | reads its input | can be signalled | a missing segment | on the wire | may restart |",
+    "|---|---|---|---|---|---|"
+  );
+  for (const state of ALL_STATES) {
+    lines.push(
+      `| \`${state}\` | ${isInputBeingRead(state) ? "yes" : "no"} | ` +
+        `${processCanBeSignalled(state) ? "yes" : "no"} | ${answerForMissingSegment(state)} | ` +
+        `\`${wireState(state)}\` | ${mayRestart(state) ? "yes" : "no"} |`
+    );
+  }
+  lines.push("");
+
+  lines.push(
+    "## Edges that must never exist",
+    "",
+    "The machine's real content: a near-complete digraph asserts nothing.",
+    "",
+    "| from | event | must not reach | because |",
+    "|---|---|---|---|"
+  );
+  for (const invariant of ABSENT_EDGE_INVARIANTS) {
+    lines.push(
+      `| \`${invariant.from}\` | \`${invariant.event}\` | \`${invariant.mustNotReach}\` | ${invariant.because} |`
+    );
+  }
+  lines.push("");
+
+  return `${lines.join("\n")}`;
+}
+
+// Written only when this file is the program being run, so importing it from a
+// test cannot rewrite the very file the test is about to compare against.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  writeFileSync(GRAPH_DOC_PATH, renderRunGraphMarkdown(), "utf8");
+  process.stdout.write(`wrote ${GRAPH_DOC_PATH}\n`);
+}

package/services/encode-exit.js

@@ -0,0 +1,80 @@
+/**
+ * @file What an ffmpeg exit MEANS — as a pure classification, so the four
+ * possibilities can be exercised without spawning anything.
+ *
+ * The exit handler is where two of this project's most expensive failures
+ * lived, and both were classification faults rather than logic faults:
+ *
+ *   - 2.9.104: ffmpeg exits 0 when it reaches the end of the file AND when its
+ *     input simply stops delivering bytes — over HTTP the two look identical to
+ *     it. A run that had made 188 segments of 624 reported itself complete, the
+ *     player consumed what was on disk and froze on the first segment nobody
+ *     was making. The difference is not in the exit code; it is in how far the
+ *     run got against the playlist we published.
+ *   - The predecessor a seek kills exits with a signal and used to be handled
+ *     as the session's own run dying. Which is why "was this process already
+ *     replaced" is the FIRST question here rather than a check somewhere in the
+ *     caller: an exit that belongs to a superseded run means nothing at all,
+ *     and reading it as a failure downgraded a hardware encoder for good.
+ *
+ * Nothing here touches a session, a process or a clock. The caller decides what
+ * to DO about each answer.
+ */
+
+/**
+ * What this exit says about the run.
+ *
+ * @readonly
+ */
+export const ENCODE_EXIT = Object.freeze({
+  /** The process was already replaced or the session is gone: it says nothing. */
+  IGNORED: "ignored",
+  /** Reached the end of the file. */
+  COMPLETE: "complete",
+  /** Claimed success, stopped short of the last segment — the input dried up. */
+  SHORT: "short",
+  /** The input was not there. Recoverable: the data can come back. */
+  INPUT_LOST: "input-lost",
+  /** Anything else. Terminal for this target until something restarts it. */
+  FAILED: "failed"
+});
+
+/**
+ * Classify one exit.
+ *
+ * `inputUnavailable` is decided by the caller from ffmpeg's own message, and it
+ * is asked BEFORE the hardware-encoder question deliberately: a run that died
+ * because its torrent data went away says nothing whatever about the encoder,
+ * and treating it as an encoder failure is how a host with NVENC came to
+ * downgrade itself to software over a missing piece.
+ *
+ * @param {object} facts
+ * @param {boolean} [facts.superseded] - This process was replaced or the
+ *   session disposed before the exit arrived.
+ * @param {number | null} [facts.code] - Exit code, null when killed by a signal.
+ * @param {number | null} [facts.producedThrough] - Highest segment index this
+ *   session has on disk, or null when that could not be read.
+ * @param {number | null} [facts.lastSegmentIndex] - Index of the file's last
+ *   segment according to the published playlist, or null when unknown.
+ * @param {boolean} [facts.inputUnavailable] - The error names a missing input.
+ * @returns {string} One of {@link ENCODE_EXIT}.
+ */
+export function classifyEncodeExit({
+  superseded = false,
+  code = null,
+  producedThrough = null,
+  lastSegmentIndex = null,
+  inputUnavailable = false
+} = {}) {
+  if (superseded) {
+    return ENCODE_EXIT.IGNORED;
+  }
+  if (code === 0) {
+    const stoppedShort =
+      lastSegmentIndex !== null &&
+      producedThrough !== null &&
+      producedThrough < lastSegmentIndex;
+    return stoppedShort ? ENCODE_EXIT.SHORT : ENCODE_EXIT.COMPLETE;
+  }
+  return inputUnavailable ? ENCODE_EXIT.INPUT_LOST : ENCODE_EXIT.FAILED;
+}