@torrent-tv/proxy 2.64.0 → 2.64.2

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.0",
+  "version": "2.64.2",
   "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/container/MatroskaContainer.js

@@ -136,9 +136,9 @@ export class MatroskaContainer extends Container {
           case ID_LANGUAGE_BCP47: languageBcp47 = readString(head, f); break;
           case ID_NAME: name = readString(head, f); break;
           case ID_FLAG_ENABLED: isEnabled = f.size === 0 || readUint(head, f.dataOffset, f.size) !== 0; break;
-          case ID_FLAG_DEFAULT: isDefault = readUint(head, f.dataOffset, f.size) === 1; declaresDefault = true; break;
+          case ID_FLAG_DEFAULT: isDefault = f.size === 0 || readUint(head, f.dataOffset, f.size) === 1; declaresDefault = true; break;
           case ID_FLAG_FORCED: isForced = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
-            case ID_FLAG_HEARING: isHearing = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
+          case ID_FLAG_HEARING: isHearing = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
           case ID_FLAG_VISUAL: isVisual = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
           case ID_FLAG_TEXT_DESCR: break;
           case ID_FLAG_ORIGINAL: isOriginal = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;

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}`);
     }
   }
 

package/services/tracks/TextSubtitleTrack.js

@@ -1,14 +1,14 @@
 /**
  * @file Text subtitle track — convertible to WebVTT.
  *
- * Matroska: S_TEXT/UTF8, S_TEXT/ASS, S_TEXT/SSA
+ * Matroska: S_TEXT/UTF8, S_TEXT/ASS, S_TEXT/SSA, S_TEXT/WEBVTT (RFC 9559)
  * MP4: tx3g, text, wvtt (stpp/TTML is NOT text for this pipeline — excluded)
  * External files: .srt .ass .ssa .vtt — modelled as TextSubtitleTrack with no container backing.
  */
 
 import { SubtitleTrack } from "./SubtitleTrack.js";
 
-const TEXT_CODECS_MATROSKA = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA"]);
+const TEXT_CODECS_MATROSKA = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA", "S_TEXT/WEBVTT"]);
 const TEXT_FORMATS_MP4 = new Set(["tx3g", "text", "wvtt"]);
 
 export class TextSubtitleTrack extends SubtitleTrack {