@torrent-tv/proxy 2.86.0 → 2.87.0

package/utils/client-log-file.js

@@ -1,151 +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);
-    }
-  };
-}
+/**
+ * @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);
+    }
+  };
+}

package/scripts/read-container-index.mjs

@@ -1,108 +0,0 @@
-/**
- * @file What this proxy would cut a file at, read from a real torrent.
- *
- * The keyframe readers take two short ranged reads, so the index of a 7 GB film
- * can be examined over the swarm in seconds without downloading it. Run against
- * a `.torrent` file to see what the container's own table says, per track, and
- * what the reader hands to the cut list.
- *
- *   node scripts/read-container-index.mjs path/to/film.torrent [more.torrent …]
- *
- * Developer tool: nothing here runs in a session, and no viewer is involved.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import MemoryChunkStore from "memory-chunk-store";
-import WebTorrent from "webtorrent";
-import { readMatroskaKeyframeTimes } from "../services/container-index/matroska.js";
-import { readMp4KeyframeTimes } from "../services/container-index/mp4.js";
-import { readAviKeyframeTimes } from "../services/container-index/avi.js";
-
-const torrents = process.argv.slice(2);
-if (torrents.length === 0) {
-  console.error("usage: node scripts/read-container-index.mjs <file.torrent> [...]");
-  process.exit(1);
-}
-
-/**
- * Collect one byte range of a torrent file.
- *
- * @param {import("webtorrent").TorrentFile} file
- * @param {number} start
- * @param {number} end - Inclusive.
- * @returns {Promise<Buffer>}
- */
-function readRangeOf(file, start, end) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    const stream = file.createReadStream({ start, end });
-    stream.on("data", (chunk) => chunks.push(chunk));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
-
-/**
- * Say what a set of times looks like: how many, where it starts, how far apart.
- *
- * @param {string} label
- * @param {number[] | null} times
- * @returns {void}
- */
-function describe(label, times) {
-  if (!times || times.length === 0) {
-    console.log(`${label}: no index`);
-    return;
-  }
-  const gaps = times.slice(1).map((time, index) => time - times[index]).sort((left, right) => left - right);
-  const median = gaps.length > 0 ? gaps[Math.floor(gaps.length / 2)] : 0;
-  console.log(
-    `${label}: ${times.length} times, first ${times.slice(0, 4).map((time) => time.toFixed(3)).join(" ")}, ` +
-    `median gap ${median.toFixed(3)}s, last ${times[times.length - 1].toFixed(3)}`
-  );
-}
-
-for (const torrentPath of torrents) {
-  // uTP is off: binding its socket needs a permission this does not have on
-  // every developer machine, and TCP peers are enough to read an index.
-  const client = new WebTorrent({ utp: false });
-  console.log(`\n=== ${path.basename(torrentPath)} ===`);
-  await new Promise((resolve) => {
-    // In memory, deliberately. The file store creates the whole file on disk at
-    // its full length before a byte of it is wanted — reading the index of four
-    // films that way filled 34 GB and then failed with the disk full. Only two
-    // short ranges are ever read here, so they can simply be held.
-    client.add(fs.readFileSync(torrentPath), { store: MemoryChunkStore }, async (torrent) => {
-      try {
-        // Nothing is wanted up front; the ranged reads below select what they need.
-        torrent.deselect(0, torrent.pieces.length - 1, 0);
-        const file = torrent.files
-          .filter((candidate) => /\.(mkv|mp4|avi)$/i.test(candidate.name))
-          .sort((left, right) => right.length - left.length)[0];
-        if (!file) {
-          console.log("no video file in this torrent");
-          return resolve();
-        }
-        console.log(`file: ${file.name} (${(file.length / 1e9).toFixed(2)} GB)`);
-        const readRange = async (start, end) => {
-          const last = Math.min(end, file.length - 1);
-          return start > last ? null : readRangeOf(file, start, last);
-        };
-        if (/\.mkv$/i.test(file.name)) {
-          describe("matroska", await readMatroskaKeyframeTimes(readRange, file.length));
-        } else if (/\.mp4$/i.test(file.name)) {
-          describe("mp4", await readMp4KeyframeTimes(readRange, file.length));
-        } else {
-          describe("avi", await readAviKeyframeTimes(readRange, file.length));
-        }
-      } catch (error) {
-        console.log(`failed: ${error?.message ?? error}`);
-      } finally {
-        resolve();
-      }
-    });
-  });
-  await new Promise((done) => client.destroy(done));
-}
-process.exit(0);

package/services/container/ContainerFactory.js

@@ -1,122 +0,0 @@
-/**
- * @file Container factory — detects format and returns the precise Container subclass.
- *
- * Sniffs first 16 bytes (same as container-index/index.js) and instantiates
- * MatroskaContainer / Mp4Container / AviContainer. Falls back to null (unknown).
- * Orchestrators depend on this, not on concrete constructors.
- */
-
-import { MatroskaContainer } from "./MatroskaContainer.js";
-import { Mp4Container } from "./Mp4Container.js";
-import { AviContainer } from "./AviContainer.js";
-import { logger } from "../../utils/logger.js";
-
-const SNIFF_BYTES = 16;
-
-export class ContainerFactory {
-  /**
-   * The container these bytes are, built over them.
-   *
-   * `params` is passed through whole, so a caller with a torrent's two readers
-   * gets a container that has both — see {@link Container}'s constructor.
-   *
-   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string, readHeld?: Function, isHeld?: Function }} params
-   * @returns {Promise<import("./Container.js").Container|null>}
-   */
-  static async create(params) {
-    const { readRange, fileSize } = params;
-    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
-    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
-    if (!head) return null;
-    if (MatroskaContainer.detect(head)) return new MatroskaContainer(params);
-    if (Mp4Container.detect(head)) return new Mp4Container(params);
-    if (AviContainer.detect(head)) return new AviContainer(params);
-    return null;
-  }
-
-  /**
-   * The container a file NAME suggests, for the moment the bytes cannot be
-   * sniffed.
-   *
-   * The head of a file nobody has opened is not downloaded, and the cue walk
-   * asks the swarm for nothing — so on that one path the name is all there is.
-   * It is a fallback and never a preference: the bytes decide wherever they can
-   * be read, because a name is what somebody typed and a header is what the
-   * muxer wrote.
-   *
-   * @param {string} name
-   * @returns {typeof MatroskaContainer | typeof Mp4Container | null}
-   */
-
-  /**
-   * Where a file's real keyframes are, read from the container's own tables
-   * rather than by scanning the media.
-   *
-   * The problem it solves: on the video-COPY path ffmpeg can only cut segments
-   * at the source's existing keyframes. A playlist declaring an even grid
-   * instead is false, and players punish it — either walking the whole file to
-   * rebuild the timeline, or presenting audio with no picture because a segment
-   * begins with nothing decodable (both seen in the field 2026-08-02; the file
-   * measured had 10.43 s keyframe spacing against our declared 4 s).
-   *
-   * Scanning is not an option: the file is served from a torrent, and a full
-   * packet scan of 5.5 GB found 77 keyframes in 45 s without finishing.
-   * Containers already store the table, and a couple of point reads get it —
-   * 16 KB and 0.8 s for 570 keyframes on that same file.
-   *
-   * This is the sniff plus the container's own reading, which is why it lives
-   * on the factory: doing it anywhere else meant a third place that decided
-   * what a file is.
-   *
-   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string }} params
-   * @returns {Promise<{ times: number[] | null, format: string, tolerance: number }>}
-   *   Ascending seconds, or null times where this file has no readable index —
-   *   the caller must then not claim to know the grid. The format is which
-   *   container answered, reported whether or not it produced anything: how
-   *   often an index disagrees with its own file is a question about the
-   *   CONTAINER, and a measurement that does not say which one cannot answer it.
-   */
-  static async readKeyframeIndex({ readRange, fileSize, label = "" }) {
-    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) {
-      return { times: null, format: "unknown", tolerance: 0 };
-    }
-    const startedAt = Date.now();
-    let container = null;
-    try {
-      container = await ContainerFactory.create({ readRange, fileSize, label });
-    } catch (error) {
-      logger.warn(`container-index: failed to read "${label}": ${error?.message ?? error}`);
-      return { times: null, format: "unrecognised", tolerance: 0 };
-    }
-    if (!container) {
-      return { times: null, format: "unrecognised", tolerance: 0 };
-    }
-    const format = container.formatName;
-    let index = null;
-    try {
-      index = await container.readKeyframeIndex();
-    } catch (error) {
-      // A malformed or partly-downloaded index must never take playback down —
-      // it only means the grid is unknown, which the caller already handles.
-      logger.warn(`container-index: failed to read index for "${label}": ${error?.message ?? error}`);
-      return { times: null, format, tolerance: 0 };
-    }
-    const elapsedMs = Date.now() - startedAt;
-    const times = index && Array.isArray(index.times) ? index.times : null;
-    if (times) {
-      logger.info(
-        `container-index: ${times.length} keyframes from the ${format} index in ${elapsedMs}ms for "${label}"`
-      );
-    } else {
-      logger.info(`container-index: no usable index for "${label}" (${format}, ${elapsedMs}ms)`);
-    }
-    return { times, format, tolerance: Number.isFinite(index?.tolerance) ? index.tolerance : 0 };
-  }
-
-  static byName(name) {
-    const text = String(name ?? "");
-    if (/\.(mp4|m4v|m4a)$/i.test(text)) return Mp4Container;
-    if (/\.(mkv|mka|webm)$/i.test(text)) return MatroskaContainer;
-    return null;
-  }
-}

package/services/controllers/PlaybackController.js

@@ -1,33 +0,0 @@
-/**
- * @file Playback controller — interface layer over playback planning.
- *
- * Thin adapter between HTTP/routes and the application orchestrators.
- * Does not parse containers itself — delegates to containerOrchestrator and
- * the existing playback-planner service. Exists so routes depend on a
- * controller contract, not on service internals.
- */
-
-import { containerOrchestrator } from "../orchestrators/ContainerOrchestrator.js";
-
-export class PlaybackController {
-  /**
-   * @param {object} deps
-   * @param {import("../torrent-pool.js").TorrentPool} deps.torrentPool
-   * @param {ReturnType<import("../../store/source-registry.js").createSourceRegistry>} deps.sourceRegistry
-   * @param {string} deps.ffmpegBin
-   * @param {string} deps.localBaseUrl
-   * @param {ReturnType<import("../playback-planner.js").createPlaybackPlanner>} deps.playbackPlanner
-   */
-  constructor({ torrentPool, sourceRegistry, ffmpegBin, localBaseUrl, playbackPlanner }) {
-    this.torrentPool = torrentPool;
-    this.sourceRegistry = sourceRegistry;
-    this.ffmpegBin = ffmpegBin;
-    this.localBaseUrl = localBaseUrl;
-    this.playbackPlanner = playbackPlanner;
-    this.containers = containerOrchestrator;
-  }
-
-  async getPlan(params) {
-    return this.playbackPlanner.getPlan(params);
-  }
-}