@torrent-tv/proxy 2.89.5 → 2.89.7

package/docs/encode-run-state.md

@@ -1,96 +1,96 @@
-<!-- GENERATED from services/encode/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/encode/EncodeRuns.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 encoding component (`EncodeRuns`) 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 |
+<!-- GENERATED from services/encode/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/encode/EncodeRuns.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 encoding component (`EncodeRuns`) 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/docs/logs.md

@@ -1,97 +1,97 @@
-# Logs — where to look
-
-No browser console copy-paste is needed: the page forwards its own log. But it
-lands in TWO places depending on the phase of the session, and `docker logs` is
-only one of them — see "Browser logs are in TWO places" below before concluding
-anything from a half-session.
-
-## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
-
-Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
-
-- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
-- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
-  A worker thread loads its own instance of every module, so the logger's file
-  handle — set once, on the main thread — was null in the worker for the life of
-  the process. Measured over a whole 49 938-line file: zero lines from the piece
-  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
-  torrent pool, against 52 and 36 of them in `docker logs`, which every release
-  destroys. The worker now sends its lines to the main thread, which is the only
-  writer; a line from there reads `torrent-worker: …`.
-- Via container:
-  ```bash
-  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
-  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
-  ```
-- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
-- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
-
-SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
-
-## DO server (webauth.courses, `infra-server-1`)
-
-- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
-- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
-- Via container:
-  ```bash
-  ssh do "docker logs infra-server-1 --tail 200 | cat"
-  # filter a single viewing:
-  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
-  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
-  ```
-- No need to open eruda or copy the browser console on a phone — it is forwarded.
-
-## Browser logs are in TWO places, split by phase — read both
-
-Until 2026-09-13 the page's whole log went to the droplet's standard output,
-which every release of the server destroys. A viewer reported a desync and a
-frozen picture that day and the analysis ran on half the evidence, so the log
-moved to the proxy — beside the proxy's own, on the same durable directory.
-
-The split is by PHASE, and neither half is the whole session:
-
-1. **Before a transport exists** — the page opening, the proxy being chosen, a
-   connection failing — there is nowhere else to send it, so it goes to the
-   SERVER (`infra-server-1`);
-2. **From the moment the data channel is up**, the page's logger is given a
-   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
-   over that channel. This is the bulk of a viewing;
-3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
-   thing a page that is going away can use, and a data channel is not;
-4. **A batch that cannot reach the proxy** falls back to the server.
-
-So a session that failed while connecting is on the droplet, a session that
-failed while playing is on the addon host, and a complete reading of a long
-failure needs both.
-
-### The files on the proxy
-
-One file per viewing session, in the proxy log's own directory (`/data` on the
-addon host), named so the two halves join without guessing:
-
-```
-client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
-```
-
-A session that has not chosen a torrent yet writes `no-torrent-yet` in that
-last part — the file is keyed by the session id, not by the name, so choosing a
-torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
-
-```bash
-ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
-ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
-```
-
-Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
-
-## Quick triage
-
-- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
-- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
-- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
-
-## Related
-
-- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
-- `docs/container-architecture.md` — what container/track classes log and where.
-- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).
+# Logs — where to look
+
+No browser console copy-paste is needed: the page forwards its own log. But it
+lands in TWO places depending on the phase of the session, and `docker logs` is
+only one of them — see "Browser logs are in TWO places" below before concluding
+anything from a half-session.
+
+## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
+
+Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
+
+- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
+- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
+  A worker thread loads its own instance of every module, so the logger's file
+  handle — set once, on the main thread — was null in the worker for the life of
+  the process. Measured over a whole 49 938-line file: zero lines from the piece
+  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
+  torrent pool, against 52 and 36 of them in `docker logs`, which every release
+  destroys. The worker now sends its lines to the main thread, which is the only
+  writer; a line from there reads `torrent-worker: …`.
+- Via container:
+  ```bash
+  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
+  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
+  ```
+- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
+- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
+
+SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
+
+## DO server (webauth.courses, `infra-server-1`)
+
+- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
+- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
+- Via container:
+  ```bash
+  ssh do "docker logs infra-server-1 --tail 200 | cat"
+  # filter a single viewing:
+  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
+  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
+  ```
+- No need to open eruda or copy the browser console on a phone — it is forwarded.
+
+## Browser logs are in TWO places, split by phase — read both
+
+Until 2026-09-13 the page's whole log went to the droplet's standard output,
+which every release of the server destroys. A viewer reported a desync and a
+frozen picture that day and the analysis ran on half the evidence, so the log
+moved to the proxy — beside the proxy's own, on the same durable directory.
+
+The split is by PHASE, and neither half is the whole session:
+
+1. **Before a transport exists** — the page opening, the proxy being chosen, a
+   connection failing — there is nowhere else to send it, so it goes to the
+   SERVER (`infra-server-1`);
+2. **From the moment the data channel is up**, the page's logger is given a
+   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
+   over that channel. This is the bulk of a viewing;
+3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
+   thing a page that is going away can use, and a data channel is not;
+4. **A batch that cannot reach the proxy** falls back to the server.
+
+So a session that failed while connecting is on the droplet, a session that
+failed while playing is on the addon host, and a complete reading of a long
+failure needs both.
+
+### The files on the proxy
+
+One file per viewing session, in the proxy log's own directory (`/data` on the
+addon host), named so the two halves join without guessing:
+
+```
+client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
+```
+
+A session that has not chosen a torrent yet writes `no-torrent-yet` in that
+last part — the file is keyed by the session id, not by the name, so choosing a
+torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
+
+```bash
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
+```
+
+Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
+
+## Quick triage
+
+- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
+- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
+- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
+
+## Related
+
+- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
+- `docs/container-architecture.md` — what container/track classes log and where.
+- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).

package/docs/playback-start-forecast.md

@@ -86,9 +86,24 @@ Seconds appear again only for rates, schedules and the answer.
 ## A piece is finished when its frames reach its cut
 
 A closed non-final fragment is reusable only if the end of its last frame, on
-every track, reaches its next declared cut less `SEGMENT_CUT_TIME_DELTA_SECONDS`,
+every track, reaches its muxer's cut less `SEGMENT_CUT_TIME_DELTA_SECONDS`,
 the delta the muxer is configured with. That is a fact of production, so no
-browser rule enters it, and the encoding decides it
+browser frame allowance is used to decide completeness. For explicit cuts the
+closure channel is CSV: its reference packet end has not lost the fraction of
+a movie tick that MP4's empty edit loses. The first reference packet's time is
+recovered from that end minus the first piece's exact sample span (the first
+CSV start is zero even after a seek), and is added to the relative cut times
+handed to FFmpeg. Comparisons use integer microseconds, as FFmpeg's segment
+muxer does. A stored piece without this closure reading carries the upper
+uncertainty of its empty edit, read from the movie and track timescales.
+
+The last frame must still reach the cut on every track. No playable media, a
+missing full frame, or a failed rename remains a publication failure. Such a
+failure stops the run, records that cause and releases its claimed interval;
+the existing repeated-start failure limit applies to subsequent attempts. A
+refused file cannot stay claimed while the encoder finishes the whole film.
+
+The encoding decides completeness
 (`encode/piece-completeness.js`): `EncodeRuns` judges a closed file before it is
 published, and judges a stored piece left by an earlier process when the
 forecast asks for it, taking a short one off the disk. The segment store keeps