@torrent-tv/proxy 2.89.15 → 2.89.17

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.89.17
+
+- **Fix**: Every browser log line the proxy keeps names the page's send it came in, as `batch=<n>`, and the server prints the same number. A send that reached neither side, or a batch the proxy took over a connection that could no longer carry its answer back, is now visible by comparing the two (torrent-tv/meta#77).
+
+## 2.89.16
+
+- **Fix**: A proxy started without `--log-file` keeps the browser's log. The page sends its log to the proxy for most of a viewing, and the proxy wrote it only to per-session files beside its own log file; with no log file named, which is every run from npm or Docker other than the Home Assistant addon, the browser's half of every viewing was dropped. It now goes to the console, beside the proxy's lines, each prefixed `client <sessionId>`. `docs/logs.md` states where the log goes for each way of starting the proxy (torrent-tv/meta#96).
+
 ## 2.89.15
 
 - **Fix**: A torrent downloaded whole is no longer removed while something is still reading it. The sweep that writes whole files out and removes the torrent asked only who had stated a need, and a read whose pieces are all here waits for nothing and states nothing. On the stand on 2026-10-04 the torrent was removed under ffmpeg's own read of the film: the read ended with "Piece store is closed" 277 MB in, ffmpeg reported `Stream ends prematurely`, the copied picture lost 2.6 s, and the page refused to start with "Prepared media contains a timestamp gap" (torrent-tv/meta#105). Open reads now count as use.

package/README.md

@@ -303,6 +303,7 @@ npm start -- --server-url http://localhost:3000
 | `--name` | hostname | Display name in registry |
 | `--token` | — | Auth token for register/heartbeat |
 | `--ffmpeg-bin` | bundled | Path to custom ffmpeg binary |
+| `--log-file` | — | Also write the log to this file, and the browser's lines to `client-*.log` beside it; without it everything goes to the console only. See `docs/logs.md` |
 | `--no-transcode-audio` | — | Disable HLS audio transcoding |
 | `--help` | — | Print all options and exit |
 
@@ -313,6 +314,13 @@ docker build -t torrent-tv-proxy .
 docker run torrent-tv-proxy --server-url http://my-server:8080
 ```
 
+Without `--log-file` the log is only in `docker logs`, which recreating the
+container deletes. To keep it, put it on a volume:
+
+```bash
+docker run -v ttv-proxy-logs:/logs torrent-tv-proxy --server-url http://my-server:8080 --log-file /logs/proxy.log
+```
+
 ## Full End-to-End Flow
 
 ```mermaid

package/docs/logs.md

@@ -1,10 +1,37 @@
 # 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
+lands in TWO places depending on the phase of the session — the registry server
+and the proxy — see "Browser logs are in TWO places" below before concluding
 anything from a half-session.
 
+## Where the proxy writes its log, by how it is started
+
+The proxy is deployment-agnostic: the Home Assistant addon is one way to run it,
+npm and Docker on Linux, macOS or Windows are others. Where its log goes is
+decided by one start parameter, `--log-file <path>`, and nothing else:
+
+- **With `--log-file`**: every line goes to the console AND to that file
+  (appended, rotated to `<path>.1` past 1 GiB), and the browser's lines go to
+  one file per viewing session in the same directory (see "The files on the
+  proxy" below). The directory of the file must exist.
+- **Without it**: everything goes to the console only, the browser's lines
+  included, each prefixed `client <sessionId:8>`. Before torrent-tv/meta#96 the
+  browser's lines were dropped in this case. The console is kept by whatever
+  started the process, and only as long as that keeps it.
+
+| How it is started | Log | Browser lines | Survives |
+|---|---|---|---|
+| Home Assistant addon | `/data/proxy.log` (`run.sh` passes `--log-file /data/proxy.log`) | `/data/client-*.log` | restarts and addon updates |
+| npm / `npx`, any OS, no `--log-file` | the terminal | the terminal | nothing |
+| npm under systemd, no `--log-file` | the unit's journal: `journalctl -u <unit>` | the same journal | restarts, within journald's limits |
+| npm with `--log-file`, e.g. `/var/log/torrent-tv-proxy/proxy.log`, `~/Library/Logs/torrent-tv/proxy.log`, `%LOCALAPPDATA%\torrent-tv\proxy.log` | that file | `client-*.log` beside it | restarts and updates |
+| Docker, no `--log-file` | `docker logs <container>` | the same | only the container's life: recreating it deletes the log |
+| Docker with a volume and `--log-file`, e.g. `-v ttv-proxy-logs:/logs … --log-file /logs/proxy.log` | the file in the volume | `client-*.log` in the volume | recreating the container |
+
+So on any host where the log matters, pass `--log-file` and point it at a
+directory that outlives the process — which is what the addon does.
+
 ## 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`).
@@ -30,15 +57,27 @@ SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh
 
 ## 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:
+- Server is `infra-server-1` (`ghcr.io/torrent-tv/server`) on `do` (`206.189.97.152`).
+- Every container there logs to the host journal, and rsyslog writes one file per
+  source to `/var/log/torrent-tv/`; the files and the journal survive the
+  deployments that recreate the containers (`infra` README, "Logs";
+  torrent-tv/meta#96):
+  - `server.log` — the server's own lines;
+  - `client.log` — browser lines the server received, prefixed
+    `[client <tag> <id> sig=<webrtcSessionId>]`
+    (`server/routes/api/client-logs/post.js`);
+  - `nginx.log`, `doco-cd.log`.
+- Frontend logs reach the droplet only in the phases the proxy cannot be reached
+  in — see "Browser logs are in TWO places" below.
+- Reading:
   ```bash
-  ssh do "docker logs infra-server-1 --tail 200 | cat"
+  ssh do "tail -n 300 /var/log/torrent-tv/client.log"
   # 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'"
+  ssh do "grep 003ed2fd /var/log/torrent-tv/client.log /var/log/torrent-tv/server.log"
+  ssh do "journalctl -t torrent-tv-server --since '-1h' -o short-iso-precise"
   ```
+- `docker logs infra-server-1` shows only the CURRENT container's lines — a
+  deployment gives it a new container. Use the files or `journalctl -t`.
 - 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
@@ -52,13 +91,26 @@ 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`);
+   SERVER (`/var/log/torrent-tv/client.log` on the droplet);
 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.
+5. **A batch nobody took** goes back into the page's queue and leaves with the
+   next send. What the page lost — lines pushed out by its 500-line queue — and
+   every refused send, by route and cause, are written into the log itself as
+   one line, `[client-logger] since <time>: …`, which travels with the next
+   batch that is delivered.
+
+Every line carries the number of the page's send it came in, as `batch=<n>`,
+on both sides: `[Windows/Chrome batch=12]` here, `[client Windows/Chrome
+<sessionId> batch=12]` on the droplet. A number on neither side is a send no
+route took: its lines went out again under a later number, and the report line
+says why. A number on both is a batch the proxy took but whose answer never
+reached the page — a connection wedged in the proxy-to-page direction still
+carries requests the other way — which the page then sent to the server too.
 
 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
@@ -66,8 +118,10 @@ 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:
+When the proxy was started with `--log-file`: 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. Without `--log-file` the same lines are in the
+proxy's console, prefixed `client <sessionId:8>`.
 
 ```
 client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
@@ -86,7 +140,7 @@ Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.j
 
 ## 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`.
+- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `client.log` `[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"`.
 

package/package.json

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

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

@@ -53,7 +53,13 @@ function sanitizeLine(value) {
  * `POST /api/client-logs`
  *
  * Body: `{ sessionId, startedAt, torrentName, infoHash, tag, signalSessionId,
- * lines: [{ level, ts, msg }] }`.
+ * seq, lines: [{ level, ts, msg }] }`.
+ *
+ * `seq` numbers the page's sends and is printed as `batch=<seq>`. The server
+ * prints the same number, so a batch that reached neither side shows as a gap,
+ * and one taken here whose answer never reached the page — a wedged connection
+ * still carries the request — shows on both, because the page then sends it to
+ * the server too.
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
@@ -69,6 +75,7 @@ export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
     infoHash: safeString(body.infoHash, 40)
   };
   const tag = sanitizeLine(safeString(body.tag, MAX_TAG_LEN)) || "Unknown/Unknown";
+  const batch = Number.isSafeInteger(body.seq) && body.seq > 0 ? ` batch=${body.seq}` : "";
   const rows = Array.isArray(body.lines) ? body.lines.slice(0, MAX_LINES) : [];
 
   const lines = rows.map((row) => {
@@ -76,7 +83,7 @@ export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
     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}`;
+    return `[${tag}${batch}] ${at} ${level}: ${message}`;
   });
 
   if (lines.length > 0) {

package/server.js

@@ -25,7 +25,7 @@ import { handleApiSourceWarmPost } from "./routes/api/sources/warm/post.js";
 import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
 import { handleApiPlaybackPlanAudioTracksPost } from "./routes/api/playback-plan/audio-tracks/post.js";
 import { handleApiClientLogsPost } from "./routes/api/client-logs/post.js";
-import { createClientLogFiles } from "./utils/client-log-file.js";
+import { createClientLogConsole, createClientLogFiles } from "./utils/client-log-file.js";
 import { handleApiSubtitlesGet } from "./routes/api/subtitles/get.js";
 import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/post.js";
 import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
@@ -629,9 +629,12 @@ export async function startProxyServer({
       }
     })
   );
-  // The browser's own log, kept beside the proxy's. See the route's own file
-  // for why it is here and not only on the registry server.
-  const clientLogs = logFile ? createClientLogFiles(logFile) : null;
+  // The browser's own log, kept beside the proxy's: a file per session when
+  // the proxy writes its log to a file, its console otherwise. See the route's
+  // own file for why it is here and not only on the registry server.
+  const clientLogs = logFile
+    ? createClientLogFiles(logFile)
+    : createClientLogConsole((message) => logger.info(message));
   app.post("/api/client-logs", async (req, reply) =>
     handleApiClientLogsPost(req, reply, { clientLogs })
   );

package/test/client-log-file.test.js

@@ -12,7 +12,7 @@ import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createClientLogFiles } from "../utils/client-log-file.js";
+import { createClientLogConsole, createClientLogFiles } from "../utils/client-log-file.js";
 
 /** A directory with a proxy log in it, which is what the sink is given. */
 function aDirectory() {
@@ -108,3 +108,19 @@ test("no proxy log path means nothing is written and nothing throws", async () =
   logs.write(aSession(), ["dropped"]);
   await logs.close();
 });
+
+test("without a log file the lines go to the console, each naming its session", async () => {
+  // A proxy started from npm or Docker names no file; the browser's half of
+  // the viewing must still reach the output the host keeps.
+  const printed = [];
+  const logs = createClientLogConsole((message) => printed.push(message));
+  logs.write(aSession(), ["first line", "second line"]);
+  logs.write(aSession({ sessionId: "" }), ["no id"]);
+  await logs.close();
+
+  assert.deepEqual(printed, [
+    "client abcd1234 first line",
+    "client abcd1234 second line",
+    "client unknown no id"
+  ]);
+});

package/test/client-logs-route.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { handleApiClientLogsPost } from "../routes/api/client-logs/post.js";
+
+/**
+ * Post one body and return the lines the route wrote.
+ *
+ * @param {object} body
+ * @returns {Promise<string[]>}
+ */
+async function linesWrittenFor(body) {
+  /** @type {string[]} */
+  const written = [];
+  const reply = { code: () => reply, send: () => reply };
+  await handleApiClientLogsPost({ body }, reply, {
+    clientLogs: { write: (_session, lines) => written.push(...lines) }
+  });
+  return written;
+}
+
+const line = { level: "info", ts: "12:00:00.000", msg: "hello" };
+
+test("each line names the page's send it came in, so the two receivers can be compared", async () => {
+  assert.deepEqual(await linesWrittenFor({ tag: "Windows/Chrome", seq: 12, lines: [line] }), [
+    "[Windows/Chrome batch=12] 12:00:00.000 info: hello"
+  ]);
+});
+
+test("a page that numbers nothing is written as before", async () => {
+  assert.deepEqual(await linesWrittenFor({ tag: "Windows/Chrome", seq: "12", lines: [line] }), [
+    "[Windows/Chrome] 12:00:00.000 info: hello"
+  ]);
+});

package/utils/client-log-file.js

@@ -16,6 +16,32 @@
 import { createWriteStream, mkdirSync, renameSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+/**
+ * Where a browser's lines go when the proxy was started without `--log-file`.
+ *
+ * The proxy runs as the Home Assistant addon, from npm, in Docker, on Linux,
+ * macOS or Windows; only the addon names a file. Without one these lines were
+ * dropped, so on every other host the browser's half of a viewing existed
+ * nowhere at all. They go to the proxy's own console instead, beside the
+ * proxy's lines, and reach whatever keeps that output on the host: `docker
+ * logs`, the journal of a systemd unit, a terminal. Each line carries the
+ * session id, which is what the file name carries when there is a file.
+ *
+ * @param {(message: string) => void} log - The proxy's logger.
+ * @returns {{ write: (session: object, lines: string[]) => void, close: () => Promise<void> }}
+ */
+export function createClientLogConsole(log) {
+  return {
+    write(session, lines) {
+      const id = safeName(session?.sessionId, 8) || "unknown";
+      for (const line of lines) {
+        log(`client ${id} ${line}`);
+      }
+    },
+    async close() {}
+  };
+}
+
 /** One file may reach this before it is rotated. */
 const MAX_BYTES = 16 * 1024 * 1024;