@torrent-tv/proxy 2.75.0 → 2.76.0

package/services/controllers/SubtitleController.js

@@ -1,128 +1,128 @@
-/**
- * @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.
- */
-
-import { subtitleOrchestrator } from "../orchestrators/SubtitleOrchestrator.js";
-import { SubtitleFileContainer } from "../container/SubtitleFileContainer.js";
-import { TextSubtitleTrack } from "../tracks/TextSubtitleTrack.js";
-import { detectLanguage } from "../language-detect.js";
-
-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 {
-  constructor({ sourceRegistry, torrentPool }) {
-    this.sourceRegistry = sourceRegistry;
-    this.torrentPool = torrentPool;
-    this.orchestrator = subtitleOrchestrator;
-  }
-
-  /**
-   * 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();
-      const release = this.torrentPool.acquireFile(torrent, fileIndex);
-      try {
-        const bytes = await readFileFully(file, EXTERNAL_MAX_BYTES);
-        const text = SubtitleFileContainer.decodeBytes(bytes);
-        const vtt = SubtitleFileContainer.toVtt(text, ext);
-        if (!vtt) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
-        // The language is read from the CONVERTED document, not from the file.
-        // The conversion has already dropped everything that is not the words —
-        // and on an ASS file that is half of it, in Latin letters, which is what
-        // made a Russian track answer `en` (field 2026-09-01, and the whole of
-        // `research/subtitle-language-ass-markup-2026-09-01.md`).
-        return { vtt, language: TextSubtitleTrack.detectLanguageFromVtt(vtt), headers: {} };
-      } catch (e) {
-        return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
-      } finally {
-        release();
-      }
-    }
-
-    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(this.torrentPool, 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 = TextSubtitleTrack.cuesToVtt(fresh, codecId);
-      // Two things this reads, and each of them was wrong before 2.68.1.
-      //
-      // It reads the cues through `finalizeCues`, so what reaches the detector
-      // is the words and not ASS's `{\…}` override groups, which are Latin on a
-      // Russian track. (The dialogue row's own fields are gone earlier now, in
-      // the container that framed them — before 2.72.1 they were not gone at
-      // all, and the detector was reading them too.)
-      //
-      // And it reads EVERY cue held so far, not the `fresh` subset that is
-      // being sent. A re-subscription after a reconnect asks only for what this
-      // page missed, which can be three lines, and three lines are not a sample
-      // of a language.
-      const language = detectLanguage(
-        TextSubtitleTrack.finalizeCues(held.cues, codecId).map((cue) => cue.text).join("\n")
-      );
-      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.
+ */
+
+import { subtitleOrchestrator } from "../orchestrators/SubtitleOrchestrator.js";
+import { SubtitleFileContainer } from "../container/SubtitleFileContainer.js";
+import { TextSubtitleTrack } from "../tracks/TextSubtitleTrack.js";
+import { detectLanguage } from "../tracks/language-detect.js";
+
+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 {
+  constructor({ sourceRegistry, torrentPool }) {
+    this.sourceRegistry = sourceRegistry;
+    this.torrentPool = torrentPool;
+    this.orchestrator = subtitleOrchestrator;
+  }
+
+  /**
+   * 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();
+      const release = this.torrentPool.acquireFile(torrent, fileIndex);
+      try {
+        const bytes = await readFileFully(file, EXTERNAL_MAX_BYTES);
+        const text = SubtitleFileContainer.decodeBytes(bytes);
+        const vtt = SubtitleFileContainer.toVtt(text, ext);
+        if (!vtt) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
+        // The language is read from the CONVERTED document, not from the file.
+        // The conversion has already dropped everything that is not the words —
+        // and on an ASS file that is half of it, in Latin letters, which is what
+        // made a Russian track answer `en` (field 2026-09-01, and the whole of
+        // `research/subtitle-language-ass-markup-2026-09-01.md`).
+        return { vtt, language: TextSubtitleTrack.detectLanguageFromVtt(vtt), headers: {} };
+      } catch (e) {
+        return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
+      } finally {
+        release();
+      }
+    }
+
+    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(this.torrentPool, 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 = TextSubtitleTrack.cuesToVtt(fresh, codecId);
+      // Two things this reads, and each of them was wrong before 2.68.1.
+      //
+      // It reads the cues through `finalizeCues`, so what reaches the detector
+      // is the words and not ASS's `{\…}` override groups, which are Latin on a
+      // Russian track. (The dialogue row's own fields are gone earlier now, in
+      // the container that framed them — before 2.72.1 they were not gone at
+      // all, and the detector was reading them too.)
+      //
+      // And it reads EVERY cue held so far, not the `fresh` subset that is
+      // being sent. A re-subscription after a reconnect asks only for what this
+      // page missed, which can be three lines, and three lines are not a sample
+      // of a language.
+      const language = detectLanguage(
+        TextSubtitleTrack.finalizeCues(held.cues, codecId).map((cue) => cue.text).join("\n")
+      );
+      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);
+  }
+}

package/services/demand/index.js

@@ -1,11 +1,8 @@
+// Only what is imported through this file. `unionOf`, `mayDisplaceSlowPeer`,
+// `URGENCY_ORDER`, `nearestFirst`, `piecesNeededFor` and `piecesWithin` were
+// re-exported here and taken by nobody; each is still where it is declared, and
+// still used there.
 export { DemandRegister } from "./DemandRegister.js";
-export { unionOf, Window } from "./Window.js";
-export {
-  isConditional,
-  mayDisplaceSlowPeer,
-  selectionPriority,
-  Urgency,
-  URGENCY_ORDER,
-  urgencyName
-} from "./Urgency.js";
-export { bytesOf, nearestFirst, piecesNeededFor, piecesOf, piecesWithin } from "./pieces.js";
+export { Window } from "./Window.js";
+export { isConditional, selectionPriority, Urgency, urgencyName } from "./Urgency.js";
+export { bytesOf, piecesOf } from "./pieces.js";

package/services/download/registry.js

@@ -80,17 +80,3 @@ export function reconcileAll() {
   }
   return { torrents: entries.length, speculativeAllowed, stated, withdrawn };
 }
-
-/**
- * Whether anybody, on any torrent, is still waiting for something urgent.
- *
- * @returns {boolean}
- */
-export function anythingUrgentIsMissing() {
-  return [...live].some((entry) => entry.selection.hasUrgentMissing());
-}
-
-/** Every live register and selection, for the periodic reconcile. */
-export function liveDemand() {
-  return [...live];
-}

package/services/encode/CoverageMap.js

@@ -0,0 +1,281 @@
+/**
+ * @file What has been made of one output, what is being made right now, and by
+ * whom.
+ *
+ * One map per set of output parameters — never per session, never per viewer.
+ * Every segment number is in exactly one of three states:
+ *
+ * 1. **ready** — a file that is closed and can be served to anybody;
+ * 2. **being made** — claimed by a named live run, which has been given that
+ *    stretch and is working forward through it;
+ * 3. **free** — nobody has made it and nobody is making it.
+ *
+ * Two questions are asked of it constantly and both have to be cheap, because
+ * one of them is on the path that answers a viewer:
+ *
+ * 1. is segment N ready — a set lookup;
+ * 2. where is the first gap at or after N — a walk over numbers, never over the
+ *    disk. The walk it replaces listed every run directory of a session on the
+ *    thread carrying the data channel, 1350 files for a 90-minute film, on
+ *    every segment request.
+ *
+ * **Claims are intervals, not heads.** A run says which stretch it was given,
+ * so two runs on one output cannot be sent to the same numbers: the gap finder
+ * skips what another run will reach. A run that only announced its current
+ * position would leave the question "will anybody make #400" unanswerable
+ * without guessing at its speed.
+ *
+ * **Nothing here touches a disk, a process or a clock**, so every decision it
+ * makes can be exercised with numbers alone.
+ */
+
+/** @typedef {"ready" | "making" | "free"} SegmentState */
+
+export class CoverageMap {
+  /** Numbers whose file is closed and servable. @type {Set<number>} */
+  #ready = new Set();
+
+  /** Run id → the stretch it was given, both ends inclusive. @type {Map<string, {from: number, to: number}>} */
+  #claims = new Map();
+
+  /** How many segments this output has in total. @type {number} */
+  #segmentCount;
+
+  /**
+   * @param {object} [params]
+   * @param {number} [params.segmentCount=0] - The length of the output, in
+   *   segments. Zero means it is not known yet, and then a gap search has to be
+   *   given its own bound by the caller.
+   */
+  constructor({ segmentCount = 0 } = {}) {
+    this.#segmentCount = Number.isInteger(segmentCount) && segmentCount > 0 ? segmentCount : 0;
+  }
+
+  /**
+   * The length of the output, once the playlist is known.
+   *
+   * @param {number} count
+   */
+  setSegmentCount(count) {
+    if (Number.isInteger(count) && count > 0) {
+      this.#segmentCount = count;
+    }
+  }
+
+  /** @returns {number} */
+  get segmentCount() {
+    return this.#segmentCount;
+  }
+
+  /**
+   * Record that a segment is closed and can be served.
+   *
+   * Idempotent, and deliberately independent of who made it: a segment made by
+   * a run that has since died is as good as one made by a run still going, and
+   * a segment left by a previous life of this process is as good as either.
+   *
+   * @param {number} index
+   */
+  markReady(index) {
+    if (Number.isInteger(index) && index >= 0) {
+      this.#ready.add(index);
+    }
+  }
+
+  /**
+   * @param {Iterable<number>} indexes
+   */
+  markReadyAll(indexes) {
+    for (const index of indexes) {
+      this.markReady(index);
+    }
+  }
+
+  /**
+   * Forget a segment: its file has gone, or was never closed.
+   *
+   * @param {number} index
+   */
+  markGone(index) {
+    this.#ready.delete(index);
+  }
+
+  /**
+   * A run has been given a stretch to fill.
+   *
+   * Replaces whatever that run claimed before, because a run has one stretch at
+   * a time: moved forward past ready material, it states the new one.
+   *
+   * @param {object} run - The run itself. A run has no name and needs none:
+   *   what identifies it here is that it IS itself, and what identifies it in a
+   *   log line is the stretch it was given, which no other live run of this
+   *   output can hold.
+   * @param {number} from - First segment number, inclusive.
+   * @param {number} to - Last segment number, inclusive. May be
+   *   `Number.POSITIVE_INFINITY` for a run with no end yet, which is what every
+   *   run was before ends existed.
+   */
+  claim(run, from, to) {
+    if (!run || !Number.isInteger(from) || from < 0) {
+      return;
+    }
+    const end = Number.isFinite(to) ? Math.max(from, Math.trunc(to)) : Number.POSITIVE_INFINITY;
+    this.#claims.set(run, { from, to: end });
+  }
+
+  /**
+   * A run has ended. Whatever it did not finish goes back to free.
+   *
+   * Nothing is un-marked: what it DID finish stays ready, because a closed file
+   * is closed whoever made it and whatever became of them afterwards.
+   *
+   * @param {object} run
+   */
+  release(run) {
+    this.#claims.delete(run);
+  }
+
+  /**
+   * @param {number} index
+   * @returns {boolean}
+   */
+  isReady(index) {
+    return this.#ready.has(index);
+  }
+
+  /**
+   * The run that was given this number, if any.
+   *
+   * @param {number} index
+   * @returns {object | null}
+   */
+  makerOf(index) {
+    for (const [run, span] of this.#claims) {
+      if (index >= span.from && index <= span.to) {
+        return run;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * @param {number} index
+   * @returns {SegmentState}
+   */
+  stateOf(index) {
+    if (this.#ready.has(index)) {
+      return "ready";
+    }
+    return this.makerOf(index) === null ? "free" : "making";
+  }
+
+  /**
+   * The first number at or after `index` that nobody has made and nobody is
+   * making — where a new run belongs.
+   *
+   * @param {number} index
+   * @param {number} [bound] - Search no further than this number, inclusive.
+   *   Defaults to the last segment of the output; required while the length is
+   *   unknown.
+   * @param {object} [exceptRun] - The run asking. Its own claim does not make
+   *   a number taken as far as it is concerned: a run looking for where to move
+   *   would otherwise be blocked by the very stretch it is trying to leave, and
+   *   a run that had claimed the rest of the film could never move at all.
+   * @returns {number | null} Null when there is no gap in range, which is what
+   *   "everything ahead is already covered" looks like.
+   */
+  firstGapFrom(index, bound = undefined, exceptRun = null) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    const last = Number.isInteger(bound) ? bound : this.#segmentCount - 1;
+    if (!Number.isInteger(last) || last < start) {
+      return null;
+    }
+    for (let at = start; at <= last; at += 1) {
+      if (this.#ready.has(at)) {
+        continue;
+      }
+      const maker = this.makerOf(at);
+      if (maker === null || maker === exceptRun) {
+        return at;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * How many numbers from `index` onwards are already covered — ready, or
+   * claimed by a run other than `exceptRun`.
+   *
+   * This is what prices a decision: a run that has arrived at covered material
+   * either drives through it, paying its own encode time for every one of these
+   * numbers, or is moved to the gap beyond them, paying one restart. Both terms
+   * are measured elsewhere; this is the length.
+   *
+   * @param {number} index
+   * @param {object} [exceptRun] - The run asking. Its own claim does not
+   *   count as somebody else's coverage.
+   * @returns {number}
+   */
+  coveredRunFrom(index, exceptRun = null) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    const last = this.#segmentCount > 0 ? this.#segmentCount - 1 : Number.MAX_SAFE_INTEGER;
+    let at = start;
+    while (at <= last) {
+      if (this.#ready.has(at)) {
+        at += 1;
+        continue;
+      }
+      const maker = this.makerOf(at);
+      if (maker !== null && maker !== exceptRun) {
+        at += 1;
+        continue;
+      }
+      break;
+    }
+    return at - start;
+  }
+
+  /**
+   * How many numbers from `index` onwards are free — nobody has made them and
+   * nobody is making them.
+   *
+   * This is what gives a run its END. A run handed the whole rest of the film
+   * would drive straight through the next stretch somebody else is making; a
+   * run handed exactly the free stretch stops where the covered material
+   * begins, which is also where it would have been moved to anyway.
+   *
+   * @param {number} index
+   * @param {object} [exceptRun] - The run asking, whose own claim does not
+   *   make a number unfree for it.
+   * @returns {number} Zero when `index` itself is not free.
+   */
+  freeRunFrom(index, exceptRun = null) {
+    const start = Number.isInteger(index) && index > 0 ? index : 0;
+    const last = this.#segmentCount > 0 ? this.#segmentCount - 1 : Number.MAX_SAFE_INTEGER;
+    let at = start;
+    while (at <= last) {
+      if (this.#ready.has(at)) {
+        break;
+      }
+      const maker = this.makerOf(at);
+      if (maker !== null && maker !== exceptRun) {
+        break;
+      }
+      at += 1;
+    }
+    return at - start;
+  }
+
+  /**
+   * What this map holds, for a log line.
+   *
+   * @returns {{ ready: number, claims: number, segmentCount: number }}
+   */
+  stats() {
+    return {
+      ready: this.#ready.size,
+      claims: this.#claims.size,
+      segmentCount: this.#segmentCount
+    };
+  }
+}