@torrent-tv/proxy 2.64.1 → 2.64.3

package/CLAUDE.md

@@ -42,6 +42,9 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     `routes/*` are now thin HTTP translators.
   - `container-index/` — legacy readers (ebml-reader, matroska/mp4/avi keyframe and
     subtitle tables) — used internally by `container/*`, deprecated as direct import.
+  - `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.
   - `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/docs/logs.md

@@ -0,0 +1,43 @@
+# 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`).
+- 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`).

package/package.json

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

package/routes/api/sources/stats/get.js

@@ -34,8 +34,13 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`stats: getTorrent failed for ${sourceKey.slice(0, 8)}: ${message} stack=${error instanceof Error ? error.stack?.split("\n")[1]?.trim() ?? "" : ""}`);
     return reply.code(500).send({ error: `Failed to load torrent: ${message}` });
   }
+  if (!torrent) {
+    logger.warn(`stats: torrent missing for ${sourceKey.slice(0, 8)} (getTorrent returned null/undefined)`);
+    return reply.code(500).send({ error: "Torrent instance not found" });
+  }
 
   const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
   const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;

package/services/memory-report.js

@@ -21,6 +21,8 @@
 
 import { readFile, statfs } from "node:fs/promises";
 import os from "node:os";
+import v8 from "node:v8";
+import path from "node:path";
 
 /** How often the reading is taken and written. */
 export const MEMORY_REPORT_INTERVAL_MS = 60_000;
@@ -234,6 +236,7 @@ export function startMemoryReport({
   diskPath = "",
   intervalMs = MEMORY_REPORT_INTERVAL_MS
 }) {
+  let highWaterRss = 0;
   const tick = async () => {
     try {
       let stores = [];
@@ -243,21 +246,37 @@ export function startMemoryReport({
         // silent-ok: a store list that cannot be read must not stop the reading
         // that matters, which is the process's own.
       }
+      const processMemory = readProcessMemory();
       if (scope === "thread") {
-        log(describeMemory({ scope, label, process: readProcessMemory(), stores }));
+        log(describeMemory({ scope, label, process: processMemory, stores }));
         return;
       }
       const { bytes, measured } = await availableMemory();
+      const anonymousBytes = await readAnonymousMemory();
+      const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
       log(describeMemory({
         scope,
         label,
-        process: readProcessMemory(),
+        process: processMemory,
         availableBytes: bytes,
         availableMeasured: measured,
-        anonymousBytes: await readAnonymousMemory(),
-        diskFreeBytes: diskPath ? await readDiskFree(diskPath) : null,
+        anonymousBytes,
+        diskFreeBytes,
         stores
       }));
+      // High-water and heap snapshot on growth — gives a file to open in Chrome DevTools
+      // when the kernel is about to kill the process. One snapshot per high-water.
+      if (processMemory.rss > highWaterRss + 100 * 1024 * 1024 && processMemory.rss > 500 * 1024 * 1024) {
+        highWaterRss = processMemory.rss;
+        try {
+          const snapPath = path.join(os.tmpdir(), `heap-${Date.now()}-${processMemory.rss}.heapsnapshot`);
+          v8.writeHeapSnapshot(snapPath);
+          log(`memory: wrote heap snapshot to ${snapPath} rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${anonymousBytes ? Math.round(anonymousBytes / (1024 * 1024)) : "?"}MB`);
+        } catch {}
+      }
+      if (anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
+        log(`memory: high rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${Math.round(anonymousBytes / (1024 * 1024))}MB heap=${Math.round(processMemory.heapUsed / (1024 * 1024))}MB — watch for OOM`);
+      }
     } catch {
       // silent-ok: a reading that fails is not worth ending the series over.
     }

package/services/torrent-pool.js

@@ -1191,7 +1191,7 @@ export class TorrentPool {
           `(~${(freed / (1024 * 1024)).toFixed(0)} MB)`
       );
       this.#cancelIdleRemoval(torrent);
-      this.#removeTorrent(torrent);
+      this.#removeTorrent(torrent, "disk-cap");
       used -= freed;
     }
   }
@@ -1582,15 +1582,20 @@ export class TorrentPool {
       return;
     }
     this.#cancelIdleRemoval(torrent);
+    const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
+    const ih = String(torrent.infoHash ?? "?").slice(0, 8);
+    logger.info(`torrent-pool: scheduling idle removal for "${name}" [${ih}] in ${TORRENT_IDLE_TTL_MS / 1000}s`);
     const timer = setTimeout(() => {
       this.#idleTimers.delete(torrent);
       // Re-check: a new acquire since scheduling would have cancelled this
       // timer, but guard anyway against a race.
       const usage = this.fileUsageByTorrent.get(torrent);
       if (usage && usage.size > 0) {
+        logger.info(`torrent-pool: idle timer fired for "${name}" [${ih}] but refcount ${usage.size} >0 — keep`);
         return;
       }
-      this.#removeTorrent(torrent);
+      logger.warn(`torrent-pool: idle TTL fired for "${name}" [${ih}] — removing torrent (reason=idle-ttl caller=scheduleIdleRemoval)`);
+      this.#removeTorrent(torrent, "idle-ttl");
     }, TORRENT_IDLE_TTL_MS);
     timer.unref?.();
     this.#idleTimers.set(torrent, timer);
@@ -1615,12 +1620,20 @@ export class TorrentPool {
    * disk while the proxy keeps running. Best-effort.
    *
    * @param {import("webtorrent").Torrent} torrent
+   * @param {string} [reason="unknown"] - Why removal was requested (idle-ttl, disk-cap, evict, api).
    * @returns {void}
    */
-  #removeTorrent(torrent) {
+  #removeTorrent(torrent, reason = "unknown") {
     if (!torrent) {
       return;
     }
+    const infoHash = String(torrent.infoHash ?? "?").slice(0, 8);
+    const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
+    const usage = this.fileUsageByTorrent.get(torrent);
+    const refcount = usage ? usage.size : 0;
+    const hasData = (() => { try { return torrentDownloadedBytes(torrent); } catch { return -1; } })();
+    // Capture caller for diagnostics — not for control flow.
+    const caller = new Error().stack?.split("\n")[2]?.trim() ?? "";
     // Drop it from the source→torrent map so a later request re-adds it.
     for (const [key, value] of this.torrents) {
       if (value === torrent) {
@@ -1631,14 +1644,14 @@ export class TorrentPool {
     this.fileUsageByTorrent.delete(torrent);
     this.#lastAccess.delete(torrent);
     this.#readPositionByTorrent.delete(torrent);
-    const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
+    logger.warn(`torrent-pool: removing torrent "${name}" [${infoHash}] reason=${reason} refcount=${refcount} downloaded=${hasData}B caller=${caller}`);
     try {
       torrent.destroy({ destroyStore: true }, () => {
-        logger.info(`torrent-pool: removed idle torrent "${name}" and its store`);
+        logger.info(`torrent-pool: removed torrent "${name}" [${infoHash}] reason=${reason} and its store`);
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      logger.warn(`torrent-pool: failed to remove idle torrent "${name}": ${message}`);
+      logger.warn(`torrent-pool: failed to remove torrent "${name}" [${infoHash}] reason=${reason}: ${message}`);
     }
   }