@torrent-tv/proxy 2.83.7 → 2.83.8

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.83.7",
+  "version": "2.83.8",
   "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();
+}

package/server.js

@@ -22,6 +22,8 @@ import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
 import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
 import { handleApiSourceWarmPost } from "./routes/api/sources/warm/post.js";
 import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
+import { handleApiClientLogsPost } from "./routes/api/client-logs/post.js";
+import { 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";
@@ -84,7 +86,11 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  */
 export async function startProxyServer({
   host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat, stateDir, onSubtitleCues,
-  deliverySink = false
+  deliverySink = false,
+  // Where the proxy writes its own log. Its DIRECTORY is what matters here:
+  // the browser's half of every session is written beside it, so the two are
+  // on one durable disk and join by name.
+  logFile = ""
 }) {
   const app = Fastify({
     // No practical body-size limit — the proxy server is localhost-only and
@@ -346,6 +352,12 @@ export async function startProxyServer({
   app.post("/api/sources/:sourceKey/warm", async (req, reply) =>
     handleApiSourceWarmPost(req, reply, { sourceRegistry, torrentPool })
   );
+  // 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;
+  app.post("/api/client-logs", async (req, reply) =>
+    handleApiClientLogsPost(req, reply, { clientLogs })
+  );
   app.post("/api/playback-plan", async (req, reply) =>
     handleApiPlaybackPlanPost(req, reply, { playbackPlanner })
   );

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

@@ -0,0 +1,110 @@
+/**
+ * @file The browser's log, written beside the proxy's.
+ *
+ * What these hold is the naming, because the name is the whole point: the two
+ * halves of a session have to join without guessing, and a torrent name is
+ * arbitrary bytes chosen by a stranger that is about to become a path.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+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";
+
+/** A directory with a proxy log in it, which is what the sink is given. */
+function aDirectory() {
+  const dir = mkdtempSync(join(tmpdir(), "ttv-client-log-"));
+  return { dir, proxyLog: join(dir, "proxy.log") };
+}
+
+const aSession = (over = {}) => ({
+  sessionId: "abcd1234",
+  startedAt: "2026-09-13T16:05:24.123Z",
+  torrentName: "Reacher.S04E07.1080p.rus.LostFilm.TV.mkv",
+  infoHash: "94dda59fdf252447d6ca5a8775dab2d11a832da5",
+  ...over
+});
+
+test("the file lands beside the proxy log, named by when it started and what is watched", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession(), ["first line"]);
+  await logs.close();
+
+  const [name] = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.ok(name, "a client log file was written");
+  // The stamp is UTC and sorts; the session id joins it to the proxy's lines;
+  // the film says which one it is without opening the file.
+  assert.match(name, /^client-20260913-160524-abcd1234-Reacher\.S04E07\.1080p\.rus\.LostFilm\.TV\.mkv-94dda59f\.log$/);
+  assert.equal(readFileSync(join(dir, name), "utf8"), "first line\n");
+});
+
+test("lines from one session go on appending to the one file", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession(), ["one", "two"]);
+  logs.write(aSession(), ["three"]);
+  await logs.close();
+
+  const names = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.equal(names.length, 1);
+  assert.equal(readFileSync(join(dir, names[0]), "utf8"), "one\ntwo\nthree\n");
+});
+
+test("a session that has not chosen a film yet still gets its own file", async () => {
+  // The page opening, a proxy being chosen, a connection failing — all before
+  // any torrent exists, and all worth keeping.
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ torrentName: "", infoHash: "" }), ["before any film"]);
+  await logs.close();
+
+  const [name] = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.match(name, /-no-torrent-yet\.log$/);
+});
+
+test("the file keeps its name when the film arrives mid-session", async () => {
+  // Keyed by the session, not by the name: the earlier lines belong to the same
+  // viewing and must not start a second file.
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ torrentName: "", infoHash: "" }), ["before"]);
+  logs.write(aSession(), ["after"]);
+  await logs.close();
+
+  const names = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.equal(names.length, 1);
+  assert.match(names[0], /-no-torrent-yet\.log$/);
+  assert.equal(readFileSync(join(dir, names[0]), "utf8"), "before\nafter\n");
+});
+
+test("a hostile torrent name cannot escape the directory", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ torrentName: "../../etc/passwd" }), ["x"]);
+  await logs.close();
+
+  const names = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.equal(names.length, 1);
+  assert.ok(!names[0].includes(".."), `no traversal in ${names[0]}`);
+  assert.ok(!names[0].includes("/"), `no separator in ${names[0]}`);
+});
+
+test("two sessions of one film are two files", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ sessionId: "aaaa1111" }), ["one viewer"]);
+  logs.write(aSession({ sessionId: "bbbb2222", startedAt: "2026-09-13T16:07:11.000Z" }), ["another"]);
+  await logs.close();
+
+  assert.equal(readdirSync(dir).filter((f) => f.startsWith("client-")).length, 2);
+});
+
+test("no proxy log path means nothing is written and nothing throws", async () => {
+  const logs = createClientLogFiles("");
+  logs.write(aSession(), ["dropped"]);
+  await logs.close();
+});

package/utils/client-log-file.js

@@ -0,0 +1,151 @@
+/**
+ * @file Where a browser's own log lands: a file beside the proxy's, per session.
+ *
+ * WHY THIS EXISTS. Both halves of every failure this project investigates live
+ * in two places at once — what the proxy did, and what the page saw — and until
+ * now the second half went to the SERVER's standard output on the droplet.
+ * Every release recreates that container and destroys it. On 2026-09-13 a
+ * viewer reported a desync and a frozen picture, and the analysis ran on half
+ * the evidence for exactly this reason.
+ *
+ * Written here instead, next to the proxy's own log, on the same durable
+ * directory (`/data` on the addon host). One file per viewing session, named so
+ * the two halves join without guessing: the session's start, then the torrent.
+ */
+
+import { createWriteStream, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** One file may reach this before it is rotated. */
+const MAX_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Make a name safe for a file and short enough to read in a directory listing.
+ *
+ * Deliberately strict: a torrent name is arbitrary bytes chosen by a stranger,
+ * and it is about to become a path.
+ *
+ * @param {string} value
+ * @param {number} max
+ * @returns {string}
+ */
+function safeName(value, max) {
+  const cleaned = String(value ?? "")
+    .replace(/[^\p{L}\p{N}._-]+/gu, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-.]+|[-.]+$/g, "");
+  return cleaned.slice(0, max);
+}
+
+/**
+ * `2026-09-13T16:05:24.123Z` → `20260913-160524`, which sorts and reads.
+ *
+ * @param {string} iso
+ * @returns {string}
+ */
+function stamp(iso) {
+  const when = new Date(iso);
+  const at = Number.isNaN(when.getTime()) ? new Date() : when;
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${at.getUTCFullYear()}${pad(at.getUTCMonth() + 1)}${pad(at.getUTCDate())}` +
+    `-${pad(at.getUTCHours())}${pad(at.getUTCMinutes())}${pad(at.getUTCSeconds())}`;
+}
+
+/**
+ * A sink that writes one session's browser lines to its own file.
+ *
+ * @param {string} proxyLogPath - The proxy's own log file; its directory is
+ *   used, so the two halves are always side by side.
+ * @returns {{ write: (session: object, lines: string[]) => void, close: () => void }}
+ */
+export function createClientLogFiles(proxyLogPath) {
+  const directory = typeof proxyLogPath === "string" && proxyLogPath.length > 0
+    ? dirname(proxyLogPath)
+    : "";
+  /** @type {Map<string, { stream: import("node:fs").WriteStream, path: string, bytes: number }>} */
+  const open = new Map();
+
+  /**
+   * The file for this session, opened on first use.
+   *
+   * Keyed by the session's own id rather than by the name, because the name
+   * gains the torrent the moment one is chosen and the earlier lines — the
+   * page opening, the proxy being chosen, a connection failing — belong to the
+   * same session and must not start a second file.
+   *
+   * @param {{ sessionId: string, startedAt: string, torrentName: string, infoHash: string }} session
+   * @returns {{ stream: import("node:fs").WriteStream, path: string, bytes: number } | null}
+   */
+  function fileFor(session) {
+    if (!directory) return null;
+    const key = session.sessionId;
+    const existing = open.get(key);
+    if (existing) return existing;
+    const film = session.torrentName
+      ? `${safeName(session.torrentName, 60)}-${safeName(session.infoHash, 8)}`
+      : "no-torrent-yet";
+    const path = join(directory, `client-${stamp(session.startedAt)}-${safeName(session.sessionId, 8)}-${film}.log`);
+    try {
+      mkdirSync(directory, { recursive: true });
+      const record = {
+        stream: createWriteStream(path, { flags: "a" }),
+        path,
+        bytes: statSync(path, { throwIfNoEntry: false })?.size ?? 0
+      };
+      // A file that stops being writable must not take the proxy down with it,
+      // and must not be retried on every line.
+      record.stream.on("error", () => open.delete(key));
+      open.set(key, record);
+      return record;
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    write(session, lines) {
+      const record = fileFor(session);
+      if (!record) return;
+      for (const line of lines) {
+        const text = `${line}\n`;
+        record.bytes += Buffer.byteLength(text);
+        record.stream.write(text);
+      }
+      if (record.bytes >= MAX_BYTES) {
+        try {
+          record.stream.end(() => {
+            try {
+              renameSync(record.path, `${record.path}.1`);
+            } catch {
+              // Renaming a file that has gone leaves nothing to do.
+            }
+          });
+        } catch {
+          // A rotation that cannot happen leaves the file growing, which is
+          // better than losing the session's log to an exception.
+        }
+        open.delete(session.sessionId);
+      }
+    },
+    /**
+     * Finish every open file.
+     *
+     * Awaitable, and that is not a convenience: a write stream opens and
+     * flushes asynchronously, so a process that ends without waiting loses the
+     * last lines of every session — which are the ones a crash is explained by.
+     *
+     * @returns {Promise<void>}
+     */
+    async close() {
+      const ending = [...open.values()].map((record) => new Promise((resolve) => {
+        try {
+          record.stream.end(resolve);
+        } catch {
+          resolve(undefined);
+        }
+      }));
+      open.clear();
+      await Promise.all(ending);
+    }
+  };
+}