@torrent-tv/proxy 2.87.20 → 2.88.0

package/services/server/WaitLedger.js

@@ -1,142 +1,142 @@
-/**
- * @file How well the priority map is being served, measured where somebody waits.
- *
- * The map says what matters most. Nothing said whether what mattered most was
- * actually delivered first — so "is the prioritisation any good" had no answer
- * of any kind, for either of the two things that read the map.
- *
- * The measure is the same for both, and it is a wait recorded against the rank
- * the map gave the thing waited for AT THE MOMENT it was asked for. Read that
- * way it says which part is wrong rather than whether the whole scheme is:
- *
- * - long waits at the TOP rank mean the urgent zone is not being served first,
- *   which is a fault in whoever acts on the map;
- * - long waits further down with none at the top mean the zones are the wrong
- *   width — the urgent one too narrow, so the viewer reaches material that was
- *   only ever ranked "soon";
- * - a rank with no waits at all is not a good sign or a bad one, it is silence,
- *   and it is reported as such rather than as a zero.
- *
- * There is nothing in here about encoders, torrents, sessions or viewers: it is
- * given a rank and a number of milliseconds.
- */
-
-/** How many waits to keep per rank. A median wants a sample, not a history. */
-const HISTORY = 200;
-
-/**
- * Ranks are collapsed into bands before they are counted.
- *
- * The map's ranks are as many as the film needs — 100 down to 1 on a long file
- * — and a table with a hundred rows says nothing a reader can hold. What is
- * being asked is coarse: was the thing waited for what the viewer needs NOW,
- * what they reach shortly, or the rest of the film. So the top rank is its own
- * band, the next few are the second, and everything below is the third.
- *
- * @param {number} rank
- * @param {number} topRank - The highest rank the map currently states.
- * @returns {"now" | "soon" | "later"}
- */
-export function bandOf(rank, topRank) {
-  if (!Number.isFinite(rank) || rank <= 0) {
-    return "later";
-  }
-  const top = Number.isFinite(topRank) && topRank > 0 ? topRank : rank;
-  if (rank >= top) {
-    return "now";
-  }
-  // Within a tenth of the top: what a viewer reaches while watching what they
-  // hold. A tenth is the map's own shape — its zones widen geometrically — and
-  // not a threshold chosen for this table.
-  return rank >= top - Math.max(1, Math.round(top / 10)) ? "soon" : "later";
-}
-
-export class WaitLedger {
-  /** @type {Map<string, Map<string, number[]>>} */
-  #waits = new Map();
-
-  /** @type {Map<string, Map<string, number>>} */
-  #counts = new Map();
-
-  /**
-   * Somebody waited this long for something the map ranked this highly.
-   *
-   * @param {string} key - What the waits belong to: an output, or a file.
-   * @param {number} waitedMs
-   * @param {number} rank - The map's rank for the thing waited for.
-   * @param {number} topRank - The highest rank the map states, so the rank can
-   *   be read as a position rather than as an absolute number.
-   */
-  note(key, waitedMs, rank, topRank) {
-    if (!key || !Number.isFinite(waitedMs) || waitedMs < 0) {
-      return;
-    }
-    const band = bandOf(rank, topRank);
-    let byBand = this.#waits.get(key);
-    if (!byBand) {
-      byBand = new Map();
-      this.#waits.set(key, byBand);
-    }
-    const held = byBand.get(band) ?? [];
-    held.push(waitedMs);
-    while (held.length > HISTORY) {
-      held.shift();
-    }
-    byBand.set(band, held);
-
-    let counts = this.#counts.get(key);
-    if (!counts) {
-      counts = new Map();
-      this.#counts.set(key, counts);
-    }
-    counts.set(band, (counts.get(band) ?? 0) + 1);
-  }
-
-  /**
-   * What the waits say, in one line, or null while nothing has waited.
-   *
-   * The count is the whole run and the median and worst are the recent sample,
-   * because those answer different questions: how often, and how badly.
-   *
-   * @param {string} key
-   * @returns {string | null}
-   */
-  describe(key) {
-    const byBand = this.#waits.get(key);
-    if (!byBand || byBand.size === 0) {
-      return null;
-    }
-    const counts = this.#counts.get(key) ?? new Map();
-    const parts = [];
-    for (const band of ["now", "soon", "later"]) {
-      const held = byBand.get(band);
-      if (!held || held.length === 0) {
-        // Said out loud, because an absent band and a band that never waited
-        // are the same silence and neither is a zero.
-        parts.push(`${band} none`);
-        continue;
-      }
-      const sorted = [...held].sort((a, b) => a - b);
-      const median = sorted[Math.floor(sorted.length / 2)];
-      parts.push(
-        `${band} ${counts.get(band) ?? held.length} wait(s) median ${Math.round(median)}ms ` +
-        `worst ${Math.round(sorted[sorted.length - 1])}ms`
-      );
-    }
-    return parts.join(", ");
-  }
-
-  /**
-   * @param {string} key
-   */
-  forget(key) {
-    this.#waits.delete(key);
-    this.#counts.delete(key);
-  }
-}
-
-/**
- * One ledger for the process, because the question is asked in two layers and
- * the answer is comparable only if the scale is the same.
- */
-export const waits = new WaitLedger();
+/**
+ * @file How well the priority map is being served, measured where somebody waits.
+ *
+ * The map says what matters most. Nothing said whether what mattered most was
+ * actually delivered first — so "is the prioritisation any good" had no answer
+ * of any kind, for either of the two things that read the map.
+ *
+ * The measure is the same for both, and it is a wait recorded against the rank
+ * the map gave the thing waited for AT THE MOMENT it was asked for. Read that
+ * way it says which part is wrong rather than whether the whole scheme is:
+ *
+ * - long waits at the TOP rank mean the urgent zone is not being served first,
+ *   which is a fault in whoever acts on the map;
+ * - long waits further down with none at the top mean the zones are the wrong
+ *   width — the urgent one too narrow, so the viewer reaches material that was
+ *   only ever ranked "soon";
+ * - a rank with no waits at all is not a good sign or a bad one, it is silence,
+ *   and it is reported as such rather than as a zero.
+ *
+ * There is nothing in here about encoders, torrents, sessions or viewers: it is
+ * given a rank and a number of milliseconds.
+ */
+
+/** How many waits to keep per rank. A median wants a sample, not a history. */
+const HISTORY = 200;
+
+/**
+ * Ranks are collapsed into bands before they are counted.
+ *
+ * The map's ranks are as many as the film needs — 100 down to 1 on a long file
+ * — and a table with a hundred rows says nothing a reader can hold. What is
+ * being asked is coarse: was the thing waited for what the viewer needs NOW,
+ * what they reach shortly, or the rest of the film. So the top rank is its own
+ * band, the next few are the second, and everything below is the third.
+ *
+ * @param {number} rank
+ * @param {number} topRank - The highest rank the map currently states.
+ * @returns {"now" | "soon" | "later"}
+ */
+export function bandOf(rank, topRank) {
+  if (!Number.isFinite(rank) || rank <= 0) {
+    return "later";
+  }
+  const top = Number.isFinite(topRank) && topRank > 0 ? topRank : rank;
+  if (rank >= top) {
+    return "now";
+  }
+  // Within a tenth of the top: what a viewer reaches while watching what they
+  // hold. A tenth is the map's own shape — its zones widen geometrically — and
+  // not a threshold chosen for this table.
+  return rank >= top - Math.max(1, Math.round(top / 10)) ? "soon" : "later";
+}
+
+export class WaitLedger {
+  /** @type {Map<string, Map<string, number[]>>} */
+  #waits = new Map();
+
+  /** @type {Map<string, Map<string, number>>} */
+  #counts = new Map();
+
+  /**
+   * Somebody waited this long for something the map ranked this highly.
+   *
+   * @param {string} key - What the waits belong to: an output, or a file.
+   * @param {number} waitedMs
+   * @param {number} rank - The map's rank for the thing waited for.
+   * @param {number} topRank - The highest rank the map states, so the rank can
+   *   be read as a position rather than as an absolute number.
+   */
+  note(key, waitedMs, rank, topRank) {
+    if (!key || !Number.isFinite(waitedMs) || waitedMs < 0) {
+      return;
+    }
+    const band = bandOf(rank, topRank);
+    let byBand = this.#waits.get(key);
+    if (!byBand) {
+      byBand = new Map();
+      this.#waits.set(key, byBand);
+    }
+    const held = byBand.get(band) ?? [];
+    held.push(waitedMs);
+    while (held.length > HISTORY) {
+      held.shift();
+    }
+    byBand.set(band, held);
+
+    let counts = this.#counts.get(key);
+    if (!counts) {
+      counts = new Map();
+      this.#counts.set(key, counts);
+    }
+    counts.set(band, (counts.get(band) ?? 0) + 1);
+  }
+
+  /**
+   * What the waits say, in one line, or null while nothing has waited.
+   *
+   * The count is the whole run and the median and worst are the recent sample,
+   * because those answer different questions: how often, and how badly.
+   *
+   * @param {string} key
+   * @returns {string | null}
+   */
+  describe(key) {
+    const byBand = this.#waits.get(key);
+    if (!byBand || byBand.size === 0) {
+      return null;
+    }
+    const counts = this.#counts.get(key) ?? new Map();
+    const parts = [];
+    for (const band of ["now", "soon", "later"]) {
+      const held = byBand.get(band);
+      if (!held || held.length === 0) {
+        // Said out loud, because an absent band and a band that never waited
+        // are the same silence and neither is a zero.
+        parts.push(`${band} none`);
+        continue;
+      }
+      const sorted = [...held].sort((a, b) => a - b);
+      const median = sorted[Math.floor(sorted.length / 2)];
+      parts.push(
+        `${band} ${counts.get(band) ?? held.length} wait(s) median ${Math.round(median)}ms ` +
+        `worst ${Math.round(sorted[sorted.length - 1])}ms`
+      );
+    }
+    return parts.join(", ");
+  }
+
+  /**
+   * @param {string} key
+   */
+  forget(key) {
+    this.#waits.delete(key);
+    this.#counts.delete(key);
+  }
+}
+
+/**
+ * One ledger for the process, because the question is asked in two layers and
+ * the answer is comparable only if the scale is the same.
+ */
+export const waits = new WaitLedger();

package/services/server/controllers/PlaybackController.js

@@ -1,40 +1,40 @@
-/**
- * @file Playback controller — interface layer over playback planning.
- *
- * Thin adapter between HTTP/routes and the playback plan. Parses nothing
- * itself. Exists so routes depend on a controller contract, not on service
- * internals.
- *
- * It used to hold a `ContainerOrchestrator` as well, and that was the main
- * thread's own instance of a module singleton the torrent worker also loads —
- * so it held no container, was asked nothing, and made it look as though a
- * container could be consulted here. It cannot: the file's bytes are in the
- * worker, and an object with methods does not cross a thread. What crosses is a
- * message.
- */
-
-export class PlaybackController {
-  /**
-   * @param {object} deps
-   * @param {import("../../torrent/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("../../media/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;
-  }
-
-  async getPlan(params) {
-    return this.playbackPlanner.getPlan(params);
-  }
-
-  async refreshAudioTracks(params) {
-    return this.playbackPlanner.refreshAudioTracks(params);
-  }
-}
+/**
+ * @file Playback controller — interface layer over playback planning.
+ *
+ * Thin adapter between HTTP/routes and the playback plan. Parses nothing
+ * itself. Exists so routes depend on a controller contract, not on service
+ * internals.
+ *
+ * It used to hold a `ContainerOrchestrator` as well, and that was the main
+ * thread's own instance of a module singleton the torrent worker also loads —
+ * so it held no container, was asked nothing, and made it look as though a
+ * container could be consulted here. It cannot: the file's bytes are in the
+ * worker, and an object with methods does not cross a thread. What crosses is a
+ * message.
+ */
+
+export class PlaybackController {
+  /**
+   * @param {object} deps
+   * @param {import("../../torrent/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("../../media/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;
+  }
+
+  async getPlan(params) {
+    return this.playbackPlanner.getPlan(params);
+  }
+
+  async refreshAudioTracks(params) {
+    return this.playbackPlanner.refreshAudioTracks(params);
+  }
+}

package/services/server/controllers/SubtitleController.js

@@ -1,109 +1,109 @@
-/**
- * @file Subtitle controller — interface layer over SubtitleOrchestrator.
- *
- * Routes (HTTP or data-channel) call this, not the domain module directly.
- * Handles external files vs embedded tracks branching, header setting, and
- * cursor/covered-cluster bookkeeping. Domain work (cluster walk, conversion,
- * language detection) stays in orchestrator/domain.
- */
-
-const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
-
-function readFileFully(file, maxBytes) {
-  return new Promise((resolve, reject) => {
-    const stream = file.createReadStream();
-    const chunks = [];
-    let total = 0;
-    stream.on("data", (chunk) => {
-      total += chunk.length;
-      if (total > maxBytes) { stream.destroy(); reject(new Error("subtitle file exceeds size cap")); return; }
-      chunks.push(chunk);
-    });
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
-
-export class SubtitleController {
-  /**
-   * @param {object} deps
-   * @param {object} deps.sourceRegistry
-   * @param {object} deps.torrentPool
-   * @param {import("../../media/SubtitleOrchestrator.js").SubtitleOrchestrator} deps.subtitles -
-   *   HANDED IN rather than built here. A controller translates a request for
-   *   an orchestrator and reaches every layer below it THROUGH that one; putting
-   *   the media layer and the torrent's cue reading together is composition, and
-   *   composition belongs to the one place that already knows about both.
-   */
-  constructor({ sourceRegistry, torrentPool, subtitles }) {
-    this.sourceRegistry = sourceRegistry;
-    this.torrentPool = torrentPool;
-    this.orchestrator = subtitles;
-  }
-
-  /**
-   * Serve external subtitle file or embedded track.
-   * Returns { vtt, language, headers } or { error, status }.
-   */
-  async getSubtitle({ sourceKey, fileIndex, trackIndex, since, after }) {
-    const rec = this.sourceRegistry.get(sourceKey);
-    if (!rec) return { error: "Source key was not found.", status: 404 };
-    const torrent = await this.torrentPool.getTorrent(rec.sourceType, rec.source);
-    const file = torrent.files[fileIndex];
-    if (!file) return { error: "File index was not found in torrent.", status: 404 };
-
-    const hasTrack = trackIndex !== undefined && trackIndex !== "" && Number.isFinite(Number(trackIndex));
-    if (!hasTrack) {
-      const name = file.name ?? "";
-      const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
-      try {
-        const bytes = await readFileFully(file, EXTERNAL_MAX_BYTES);
-        const converted = this.orchestrator.fileAsVtt(bytes, ext);
-        if (!converted) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
-        return { ...converted, headers: {} };
-      } catch (e) {
-        return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
-      }
-    }
-
-    const idx = Number(trackIndex);
-    if (!Number.isInteger(idx) || idx < 0) return { error: "trackIndex must be a non-negative integer.", status: 400 };
-
-    // Resolve via orchestrator (domain: cluster walk or MP4 sample ranges)
-    const tracks = await this.orchestrator.getTracks(torrent, fileIndex, sourceKey);
-    const track = Array.isArray(tracks) ? tracks.find((c) => c.declaredIndex === idx) ?? null : null;
-    // Also try domain's declaredIndex-agnostic lookup via getCues path — keep compat with existing subtitle-cues declaredIndex
-    let held = null;
-    try {
-      // Need trackNumber for domain call — find via declared workspace
-      const domainTracks = await this.orchestrator.getDeclaredTracks(torrent, fileIndex, sourceKey);
-      // If not found, fall back to direct cuesHeldFor via trackNumber from tracks list
-      const target = track ?? domainTracks.find((t) => t.declaredIndex === idx) ?? null;
-      const trackNumber = target?.trackNumber ?? track?.trackNumber;
-      if (trackNumber != null) {
-        held = await this.orchestrator.getCues(torrent, fileIndex, sourceKey, trackNumber);
-      }
-    } catch {}
-    if (held && Array.isArray(held.cues)) {
-      const cursor = held.cues.reduce((h, c) => Math.max(h, Number(c.seq) || 0), 0);
-      const fresh = Number.isInteger(since) ? held.cues.filter((c) => (Number(c.seq) || 0) > since)
-        : Number.isFinite(after) ? held.cues.filter((c) => c.startSeconds > after) : held.cues;
-      const codecId = held.track?.codecId ?? track?.codecId ?? "";
-      const { vtt, language } = this.orchestrator.cuesAsVtt(fresh, held.cues, codecId);
-      return {
-        vtt,
-        language,
-        headers: {
-          "X-Subtitle-Covered-Clusters": String(held.coveredClusters ?? 0),
-          "X-Subtitle-Indexed-Clusters": String(held.indexedClusters ?? 0),
-          "X-Subtitle-Cursor": String(cursor)
-        }
-      };
-    }
-    return { pending: true, status: 202 };
-  }
-
-  async warm(torrent, fileIndex, sourceKey) {
-    return this.orchestrator.warm(torrent, fileIndex, sourceKey);
-  }
-}
+/**
+ * @file Subtitle controller — interface layer over SubtitleOrchestrator.
+ *
+ * Routes (HTTP or data-channel) call this, not the domain module directly.
+ * Handles external files vs embedded tracks branching, header setting, and
+ * cursor/covered-cluster bookkeeping. Domain work (cluster walk, conversion,
+ * language detection) stays in orchestrator/domain.
+ */
+
+const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
+
+function readFileFully(file, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const stream = file.createReadStream();
+    const chunks = [];
+    let total = 0;
+    stream.on("data", (chunk) => {
+      total += chunk.length;
+      if (total > maxBytes) { stream.destroy(); reject(new Error("subtitle file exceeds size cap")); return; }
+      chunks.push(chunk);
+    });
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+
+export class SubtitleController {
+  /**
+   * @param {object} deps
+   * @param {object} deps.sourceRegistry
+   * @param {object} deps.torrentPool
+   * @param {import("../../media/SubtitleOrchestrator.js").SubtitleOrchestrator} deps.subtitles -
+   *   HANDED IN rather than built here. A controller translates a request for
+   *   an orchestrator and reaches every layer below it THROUGH that one; putting
+   *   the media layer and the torrent's cue reading together is composition, and
+   *   composition belongs to the one place that already knows about both.
+   */
+  constructor({ sourceRegistry, torrentPool, subtitles }) {
+    this.sourceRegistry = sourceRegistry;
+    this.torrentPool = torrentPool;
+    this.orchestrator = subtitles;
+  }
+
+  /**
+   * Serve external subtitle file or embedded track.
+   * Returns { vtt, language, headers } or { error, status }.
+   */
+  async getSubtitle({ sourceKey, fileIndex, trackIndex, since, after }) {
+    const rec = this.sourceRegistry.get(sourceKey);
+    if (!rec) return { error: "Source key was not found.", status: 404 };
+    const torrent = await this.torrentPool.getTorrent(rec.sourceType, rec.source);
+    const file = torrent.files[fileIndex];
+    if (!file) return { error: "File index was not found in torrent.", status: 404 };
+
+    const hasTrack = trackIndex !== undefined && trackIndex !== "" && Number.isFinite(Number(trackIndex));
+    if (!hasTrack) {
+      const name = file.name ?? "";
+      const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+      try {
+        const bytes = await readFileFully(file, EXTERNAL_MAX_BYTES);
+        const converted = this.orchestrator.fileAsVtt(bytes, ext);
+        if (!converted) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
+        return { ...converted, headers: {} };
+      } catch (e) {
+        return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
+      }
+    }
+
+    const idx = Number(trackIndex);
+    if (!Number.isInteger(idx) || idx < 0) return { error: "trackIndex must be a non-negative integer.", status: 400 };
+
+    // Resolve via orchestrator (domain: cluster walk or MP4 sample ranges)
+    const tracks = await this.orchestrator.getTracks(torrent, fileIndex, sourceKey);
+    const track = Array.isArray(tracks) ? tracks.find((c) => c.declaredIndex === idx) ?? null : null;
+    // Also try domain's declaredIndex-agnostic lookup via getCues path — keep compat with existing subtitle-cues declaredIndex
+    let held = null;
+    try {
+      // Need trackNumber for domain call — find via declared workspace
+      const domainTracks = await this.orchestrator.getDeclaredTracks(torrent, fileIndex, sourceKey);
+      // If not found, fall back to direct cuesHeldFor via trackNumber from tracks list
+      const target = track ?? domainTracks.find((t) => t.declaredIndex === idx) ?? null;
+      const trackNumber = target?.trackNumber ?? track?.trackNumber;
+      if (trackNumber != null) {
+        held = await this.orchestrator.getCues(torrent, fileIndex, sourceKey, trackNumber);
+      }
+    } catch {}
+    if (held && Array.isArray(held.cues)) {
+      const cursor = held.cues.reduce((h, c) => Math.max(h, Number(c.seq) || 0), 0);
+      const fresh = Number.isInteger(since) ? held.cues.filter((c) => (Number(c.seq) || 0) > since)
+        : Number.isFinite(after) ? held.cues.filter((c) => c.startSeconds > after) : held.cues;
+      const codecId = held.track?.codecId ?? track?.codecId ?? "";
+      const { vtt, language } = this.orchestrator.cuesAsVtt(fresh, held.cues, codecId);
+      return {
+        vtt,
+        language,
+        headers: {
+          "X-Subtitle-Covered-Clusters": String(held.coveredClusters ?? 0),
+          "X-Subtitle-Indexed-Clusters": String(held.indexedClusters ?? 0),
+          "X-Subtitle-Cursor": String(cursor)
+        }
+      };
+    }
+    return { pending: true, status: 202 };
+  }
+
+  async warm(torrent, fileIndex, sourceKey) {
+    return this.orchestrator.warm(torrent, fileIndex, sourceKey);
+  }
+}