@torrent-tv/proxy 2.83.7 → 2.84.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 2.84.0
+
+- **Fix**: WHERE A VIEWER IS HAS ONE WRITER AND IS A FUNCTION OF TIME. It had two: a seek wrote `position.seeked`, a segment request overwrote `position.seconds`, and the reading preferred whichever was set — so the two took turns and the priority map jumped backwards and forwards several times a second. Field 2026-09-13, one output over one second: `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, with the second viewer stopped dead at 1673.6 s throughout. Encoder placement follows the map, as it must, so the machine spent six minutes on **77 starts and 141 stops against one normal end**, produced almost nothing, and both browsers sat frozen with empty buffers while the swarm delivered 3 MB/s from 129 peers. A segment request now says only that the viewer is still here; where they are is what they state, and between statements it is carried forward by the clock at the rate the film moves — `position(now) = stated + (playing ? 1 : 0) × (now − statedAt)`. Continuous and monotone by construction, so nothing derived from it can dither.
+- **Fix**: A picture starved of data is no longer reported as moving. `paused` is false while an element waits for bytes, so a frozen player told the proxy it was playing and the position walked away from where the viewer actually stood — the exact case a frozen player is in. It is `readyState >= HAVE_FUTURE_DATA` as well now, and `waiting` joins `pause`/`playing`/`ended` in the events that report at once rather than waiting out the ten-second interval.
+- **Fix**: PRESENCE IS THE CONNECTION AND ONLY THE CONNECTION. Silence longer than "any silence a watching viewer can produce" used to end it, and there is no such interval: a paused viewer, a hidden tab whose timers the browser has throttled, and one holding two minutes of cushion all say nothing and are all still watching. A viewer is here until something says otherwise — the browser releasing the session, or the connection closing. `presenceStaleAfterMs` and every threshold it fed are gone.
+- **Fix**: A soundtrack begins where the earliest viewer of the picture stands, with nothing subtracted. What that replaced was an apparatus for turning a request edge back into a playhead: three position sources ranked by priority, a second function naming which had answered, a subtraction of the deepest reported buffer, and a special case for a session nobody had asked anything of yet. Each repaired a quantity that meant two things. Field 2026-08-31, what it cost: a page opened at 588 s started its sound at 460 s — 131 seconds of film nobody would hear, and the segment the viewer needed took 38.8 s against the picture's 8.4 s.
+- **Chore**: `resolveViewerPosition`, `viewerPositionSource`, `#viewerPositionSourceOf`, `#consumerPositionOf`, `#noteConsumerHead`, `session.lastRequestedSegment`, `session.furthestViewerSeconds` and `headsOf` are deleted. Where a viewer is now lives in the viewer's own layer (`viewer/positions.js`), and the session manager is 250 lines shorter for it.
+- **Chore**: The flag that pins a rung's size is `exactSize`, not `manualQuality`, and the key it writes reads `enc:1280x720:exact` rather than `:manual`. It says nothing about who asked — every rung of a master sets it, whether the viewer picked that rung or the player moved itself onto one — and the old name was read as "the viewer did this" four times in a few weeks, in field logs where the viewer had touched nothing. The log line says `size=exact` for the same reason. Requires server 0.27.14 or newer in the page.
+- **New**: `test/plan-is-steady.test.js` — five checks that the placement does not move while the facts do not, over the whole chain from what a viewer states to what the plan answers, with the field's own two positions. Confirmed to go red on the reading this release replaced.
+
+## 2.83.8
+
+- **New**: THE BROWSER'S OWN LOG IS KEPT BESIDE THE PROXY'S, ON A DISK THAT SURVIVES. Explaining any failure here needs both halves — what the proxy did and what the page saw — and the second half went to the registry server's standard output on the droplet, which every release of it destroys. On 2026-09-13 a viewer reported a desync and a frozen picture and the analysis ran on half the evidence for exactly that reason. `POST /api/client-logs` on the proxy writes them into the same directory as its own log (`/data` on the addon host), one file per viewing session: `client-<start>-<session>-<film>-<infohash>.log`. The start time and the session id are what join the two halves without guessing, and the film says which one it is without opening the file. Seven checks over the writer, one confirmed to go red.
+- **New**: A session that has not chosen a film yet still gets its file (`-no-torrent-yet`), because the page opening, a proxy being chosen and a connection failing all happen before any torrent exists and are worth keeping. The file is keyed by the SESSION, so the film arriving mid-session does not start a second one.
+- **Chore**: A torrent name is arbitrary bytes chosen by a stranger and here it becomes a path, so it is reduced to letters, digits, dot, dash and underscore and truncated; a check holds that `../../etc/passwd` cannot escape the directory. Closing the sink is awaitable: a write stream flushes asynchronously, and a process that ends without waiting loses the last lines of every session — the ones a crash is explained by.
+
 ## 2.83.7
 - **Fix**: A SUBTITLE SUBSCRIPTION BELONGS TO THE VIEWER, NOT TO THE CHANNEL. It was a `Set<DataChannel>` inside the transport, so a seamless reconnect lost subtitles for the rest of the session (recorded 2026-08-26 and never fixed), and a transport that rotates its association on purpose — which is what the delivery wedge now requires — would lose them at every rotation. It is held against the viewer now (`Viewers.wantsCues` / `wantingCues`), registered by the request that turns subtitles on, which is the only place that knows both the person and the file. Whatever channel that person is reachable on next, they are still subscribed. Eight checks over the registry, three of which go red if the file index stops being part of the key.
 - **Chore**: The transport no longer sniffs `/api/subtitles` out of the request path, no longer derives a torrent source key, and no longer takes `sourceRegistry` at all — 41 lines of application routing and torrent identity out of the layer whose job is carrying bytes. It is given one plain function returning opaque ids (`viewersWantingCues`) and keeps only "this name is reachable on this channel", which is its own fact. Requires server 0.27.11 or newer in the page: an older page sends no `consumerId`, and then nothing subscribes.

package/CLAUDE.md

@@ -89,9 +89,11 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     why the priority map is read at two scopes (per FILE for the swarm, per
     OUTPUT for the encoders), and what each of the eight other places that used
     to place or kill an encoder now states instead.
-  - `docs/logs.md` — where to find logs (HA `docker logs` + `/data/proxy.log`, DO
-    `infra-server-1` with forwarded frontend `POST /api/client-logs`). Browser
-    console not needed.
+  - `docs/logs.md` — where to find logs, and the fact that the BROWSER's own log
+    is in TWO places split by phase: on the droplet while a transport is being
+    acquired and at unload, on THIS proxy for the whole of a viewing
+    (`/data/client-<start>-<session>-<torrent>.log`, one file per session).
+    Read both before concluding anything from a half-session.
   - `playback-planner.js` — single ffmpeg probe returns audioCodec, videoCodec,
     container, durationSeconds. `mode` is advisory; the browser decides.
   - `hls-session-manager.js` — one ffmpeg per (source, file, settings). Serves a

package/bin/cli.js

@@ -323,6 +323,7 @@ try {
     memoryBytes,
     segmentFormat: options.segmentFormat,
     stateDir: options.stateDir,
+    logFile: options.logFile ?? "",
     deliverySink: options.deliverySink === true,
     // Late-bound the same way `webRtcManager` is below: the torrent pool is
     // built inside `startProxyServer`, before `dataChannelHandler` — the

package/docs/encode-architecture.md

@@ -28,12 +28,37 @@ It decides from four things and no others:
 name a consumer id, or hold a person. What crosses is a priority map: zones of
 segment numbers with a rank and a real time, and nobody's name on it.
 
+## Where a viewer is, and how it reaches the encoders
+
+A viewer's position has ONE writer — the viewer — and is a function of time:
+
+```
+position(now) = stated + (playing ? 1 : 0) × (now − statedAt)
+```
+
+A viewer whose picture moves covers a second of film every second, so between
+the moments they speak their position is known exactly; one whose picture is
+stopped covers nothing. Nothing else writes it, and in particular a request for
+a segment does not: a request says the viewer is still here, and the segment
+either exists and is served or does not and is waited for.
+
+Held as a stored number instead it was a staircase, flat for the ten seconds
+between reports and then a jump — and with two writers filling it in turn the
+steps went backwards as often as forwards. Field 2026-09-13, one output over one
+second: `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, while
+the second viewer sat frozen at 1673.6 s. The placement follows the map, so the
+machine spent six minutes on 77 encoder starts and 141 stops.
+
+PRESENCE IS A SEPARATE FACT and it is the connection: a viewer is here until
+something says otherwise. Silence never says it — a pause, a hidden tab whose
+timers are throttled, and a full cushion are all silent and all still watching.
+
 ## Viewers become a map, and that is the whole crossing
 
 ```mermaid
 flowchart TB
   subgraph V["services/viewer — where people are"]
-    VW[Viewer<br/>position, playing, buffered, chosen track]
+    VW[Viewer<br/>position as a function of time, playing, buffered, chosen track]
     VS[Viewers<br/>the relation, indexed from both ends]
   end
 

package/docs/logs.md

@@ -1,51 +1,97 @@
-# Logs — where to look
-
-All logs are visible via container `docker logs`, no browser console copy-paste needed.
-
-## 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 are forwarded: browser batches `{sessionId, tag, signalSessionId, lines: [{level,ts,msg}]}` and `POST`s to `https://webauth.courses/api/client-logs` (`server/routes/api/client-logs/post.js:56`), server does `console.log` with prefix `[client <tag> <id> sig=<webrtcSessionId>]`. They appear together with backend logs in the same container.
-- 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 browser console on phone — it is already in `infra-server-1` logs.
-
-## 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.
-- `server/routes/api/client-logs/post.js:1` — sanitization (control chars → space, `MAX_LINES 50`, `MAX_MSG_LEN 2000`).
+# 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/package.json

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

package/routes/api/client-logs/post.js

@@ -0,0 +1,86 @@
+/**
+ * @file Take the browser's own log and keep it beside the proxy's.
+ *
+ * The page has always forwarded its console somewhere; until now that was the
+ * SERVER's standard output on the droplet, which every release destroys. Both
+ * halves of a failure are needed to explain one — what the proxy did and what
+ * the page saw — and on 2026-09-13 an investigation ran on half of them for
+ * exactly that reason.
+ *
+ * Here the two land in one directory, on the host's durable disk, in files
+ * named so they join without guessing.
+ *
+ * The server's route stays and is not replaced: a page that has no proxy yet,
+ * or whose connection to one just failed, still has something to say, and those
+ * are the moments that matter most.
+ */
+
+const MAX_LINES = 50;
+const MAX_MSG_LEN = 2000;
+const MAX_TAG_LEN = 40;
+const MAX_SID_LEN = 16;
+const MAX_NAME_LEN = 200;
+
+/**
+ * @param {unknown} value
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function safeString(value, maxLen) {
+  return (typeof value === "string" ? value : "").slice(0, maxLen);
+}
+
+/**
+ * Replace every control character with a space.
+ *
+ * These lines are written by a stranger's browser into a file a person will
+ * later read in a terminal: a newline would forge a log entry and an escape
+ * sequence would drive the terminal.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function sanitizeLine(value) {
+  let out = "";
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    out += code < 0x20 || code === 0x7f ? " " : character;
+  }
+  return out;
+}
+
+/**
+ * `POST /api/client-logs`
+ *
+ * Body: `{ sessionId, startedAt, torrentName, infoHash, tag, signalSessionId,
+ * lines: [{ level, ts, msg }] }`.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ clientLogs: { write: (session: object, lines: string[]) => void } | null }} deps
+ * @returns {Promise<unknown>}
+ */
+export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  const session = {
+    sessionId: safeString(body.sessionId, MAX_SID_LEN) || "unknown",
+    startedAt: safeString(body.startedAt, 30),
+    torrentName: sanitizeLine(safeString(body.torrentName, MAX_NAME_LEN)),
+    infoHash: safeString(body.infoHash, 40)
+  };
+  const tag = sanitizeLine(safeString(body.tag, MAX_TAG_LEN)) || "Unknown/Unknown";
+  const rows = Array.isArray(body.lines) ? body.lines.slice(0, MAX_LINES) : [];
+
+  const lines = rows.map((row) => {
+    const entry = row && typeof row === "object" ? row : {};
+    const level = safeString(entry.level, 8) || "log";
+    const at = sanitizeLine(safeString(entry.ts, 16));
+    const message = sanitizeLine(safeString(entry.msg, MAX_MSG_LEN));
+    return `[${tag}] ${at} ${level}: ${message}`;
+  });
+
+  if (lines.length > 0) {
+    clientLogs?.write(session, lines);
+  }
+  return reply.code(204).send();
+}