@torrent-tv/proxy 2.89.14 → 2.89.16

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
+
 ## 2.89.14
 
 - **Fix**: A failed run counts only the source's own streams. The planner probes with an output, so ffmpeg's banner goes on to list the streams it maps and writes, and those were counted too: a file with one picture, one soundtrack, one subtitle and one font read as `2 video, 2 audio, 1 subtitle, 3 other` in the field — enough to make a second soundtrack look present when it is not.

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,7 +91,7 @@ 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;
@@ -66,8 +105,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 +127,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.14",
+  "version": "2.89.16",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "repository": {

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/services/torrent/worker/files-in-use.js

@@ -0,0 +1,35 @@
+/**
+ * @file Which files of a torrent somebody is using, for the sweep that writes
+ * whole files out and removes a torrent that has nothing left to fetch.
+ *
+ * Two facts, and both are needed. A file somebody has stated a need for is in
+ * use. So is a file being read: a read whose pieces are all here waits for
+ * nothing, and so states nothing in the demand register. Field 2026-10-04: a
+ * torrent was removed under such a read, ffmpeg's input ended with "Piece store
+ * is closed" 277 MB in, and the copied picture lost 2.6 s that the readiness
+ * forecast then refused as a timestamp gap (torrent-tv/meta#105).
+ */
+
+/** Claimants that keep pieces coming without anybody reading. */
+const NOT_A_READER = ["file-edges:", "torrent-fill:", "background-fill:"];
+
+/**
+ * @param {object} options
+ * @param {object} options.torrent
+ * @param {Array<{ claimant: unknown, fileIndex: number }>} options.windows - The demand register's windows.
+ * @param {Iterable<{ torrent: object, fileIndex: number }>} options.openReads - Reads in flight.
+ * @returns {Set<number>} File indices in use.
+ */
+export function filesInUse({ torrent, windows, openReads }) {
+  const used = new Set(
+    windows
+      .filter((window) => !NOT_A_READER.some((prefix) => String(window.claimant).startsWith(prefix)))
+      .map((window) => window.fileIndex)
+  );
+  for (const read of openReads) {
+    if (read.torrent === torrent) {
+      used.add(read.fileIndex);
+    }
+  }
+  return used;
+}

package/services/torrent/worker/worker.js

@@ -34,6 +34,7 @@ import { heldRangesOf, ownsItsMemory, readHeldBytes } from "./held-bytes.js";
 import { CompletedFiles, completedFilesRoot } from "../../storage/files/CompletedFiles.js";
 import { pieceFromWholeFiles, pieceIsInWholeFiles } from "../../storage/files/piece-from-whole-file.js";
 import { Command, Event } from "./protocol.js";
+import { filesInUse } from "./files-in-use.js";
 import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../../storage/memory-report.js";
 import { forwardLogsTo, logger } from "../../../utils/logger.js";
 
@@ -94,6 +95,14 @@ const torrentsByKey = new Map();
 const sourceRecipes = new Map();
 /** In-flight reads, so a cancel can stop one mid-body. */
 const readsById = new Map();
+/**
+ * What each in-flight read is reading. A read whose pieces are all here waits
+ * for nothing and so states nothing in the demand register; this is how the
+ * thread knows it is still open.
+ *
+ * @type {Map<number, { torrent: object, fileIndex: number }>}
+ */
+const openReads = new Map();
 
 /**
  * Shorthand for this file. The same path as `logger.info` anywhere else in the
@@ -257,6 +266,7 @@ async function streamRange({ id, sourceKey, fileIndex, start, end, windowBytes }
 
   const sender = createSendStream({ port: parentPort, requestId: id });
   readsById.set(id, sender);
+  openReads.set(id, { torrent, fileIndex });
 
   const rangeStart = start ?? 0;
   const rangeEnd = end ?? file.length - 1;
@@ -295,6 +305,7 @@ async function streamRange({ id, sourceKey, fileIndex, start, end, windowBytes }
     throw error;
   } finally {
     readsById.delete(id);
+    openReads.delete(id);
     // Any fragment still awaiting confirmation will never get one now; settling
     // it here releases its pin rather than leaking a held slot.
     settleFragment(id);
@@ -947,18 +958,12 @@ async function keepWholeFiles() {
     if (!infoHash || !Array.isArray(torrent.files)) {
       continue;
     }
-    // What anybody wants of this torrent. A file something is stated for is a
-    // file somebody may be reading, and this is the same list the reader counts
-    // used to give.
-    const wanted = new Set(
-      demandFor(torrent).register.windows()
-        .filter((window) =>
-          !String(window.claimant).startsWith("file-edges:") &&
-          !String(window.claimant).startsWith("torrent-fill:") &&
-          !String(window.claimant).startsWith("background-fill:")
-        )
-        .map((window) => window.fileIndex)
-    );
+    // What anybody wants of this torrent or is reading from it now.
+    const wanted = filesInUse({
+      torrent,
+      windows: demandFor(torrent).register.windows(),
+      openReads: openReads.values()
+    });
     for (const [fileIndex, file] of torrent.files.entries()) {
       const key = `${infoHash}/${fileIndex}`;
       if (file?.done !== true || completedFiles.find(infoHash, fileIndex) || beingKept.has(key)) {

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/files-in-use.test.js

@@ -0,0 +1,34 @@
+/**
+ * @file Which files of a torrent are in use for the whole-file sweep. Pure:
+ * no torrent is started (see services/torrent/worker/files-in-use.js).
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { filesInUse } from "../services/torrent/worker/files-in-use.js";
+
+test("a file being read is in use though nobody states a need for it", () => {
+  // Field 2026-10-04: every piece was here, so the read waited for nothing and
+  // stated nothing, and the torrent was removed under it.
+  const torrent = {};
+  const used = filesInUse({ torrent, windows: [], openReads: [{ torrent, fileIndex: 0 }] });
+  assert.deepEqual([...used], [0]);
+});
+
+test("a read of another torrent does not count", () => {
+  const used = filesInUse({ torrent: {}, windows: [], openReads: [{ torrent: {}, fileIndex: 0 }] });
+  assert.equal(used.size, 0);
+});
+
+test("stated needs count, and the fills that read nothing do not", () => {
+  const used = filesInUse({
+    torrent: {},
+    windows: [
+      { claimant: "reader:7", fileIndex: 2 },
+      { claimant: "file-edges:1", fileIndex: 1 },
+      { claimant: "torrent-fill:x", fileIndex: 3 },
+      { claimant: "background-fill:x", fileIndex: 4 }
+    ],
+    openReads: []
+  });
+  assert.deepEqual([...used], [2]);
+});

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;