@torrent-tv/proxy 2.107.56 → 2.107.57

package/services/server/MediaReadParams.js

@@ -0,0 +1,134 @@
+/**
+ * @file The parameters of a media read, and the metadata demand of an encode
+ * input, which lasts as long as the signal of its request.
+ */
+
+export class MediaReadParams {
+  #heldFile;
+  #packetMemory;
+  #readProbe;
+  #probePackets;
+  #baseUrl;
+  #observeWait;
+  #reads;
+  #maps;
+  #learnKeyframes;
+  #formatOf;
+  #warn;
+  /** @type {WeakMap<AbortSignal, Map<string, { statements: Set<string>, abort: () => void }>>} */
+  #trackers = new WeakMap();
+
+  constructor({ heldFile, packetMemory, readProbe, probePackets, baseUrl, observeWait, reads, maps,
+    learnKeyframes, formatOf, warn }) {
+    this.#heldFile = heldFile;
+    this.#packetMemory = packetMemory;
+    this.#readProbe = readProbe;
+    this.#probePackets = probePackets;
+    this.#baseUrl = baseUrl;
+    this.#observeWait = observeWait;
+    this.#reads = reads;
+    this.#maps = maps;
+    this.#learnKeyframes = learnKeyframes;
+    this.#formatOf = formatOf;
+    this.#warn = warn;
+  }
+
+  async paramsFor({ sourceKey, fileIndex, requestId, packetInterval, demand, readPriority, signal }) {
+    const file = this.#heldFile(sourceKey, fileIndex);
+    if (!file) {
+      return null;
+    }
+    const metadataTracker = readPriority?.requestId && signal
+      ? this.#trackerFor(signal, sourceKey, fileIndex) : null;
+    const maps = this.#maps;
+    const params = {
+      sourceKey,
+      fileIndex,
+      requestId,
+      signal,
+      packetInterval,
+      readPriority,
+      packetMemory: this.#packetMemory(sourceKey, fileIndex),
+      downloadInterval: demand ? { from: demand.from, to: demand.to } : null,
+      readRange: (start, end) => file.readHeld(start, Math.min(end, file.length - 1)),
+      fileSize: file.length,
+      probe: (statement, onRecord) => this.#readProbe({ sourceKey, fileIndex, statement: `ffprobe:${statement}`,
+        probe: ({ requestId, signal }) => {
+          const url = new URL("/media", this.#baseUrl());
+          url.searchParams.set("sourceKey", sourceKey);
+          url.searchParams.set("fileIndex", String(fileIndex));
+          url.searchParams.set("readId", requestId);
+          return this.#probePackets({ url: url.toString(), statement, signal, onRecord });
+        } }),
+      label: file.name,
+      fileOffset: file.offset,
+      onObserved: fields => {
+        const process = fields.statement === "keyframes" ? "P5"
+          : String(fields.statement).startsWith("ffprobe:") ? "X1" : "P2";
+        const details = { process, fileIndex, requestId, statement: fields.statement, cached: fields.cached,
+          result: fields.result, reason: fields.reason, ranges: fields.ranges,
+          queuedMs: fields.queuedMs, readMs: fields.readMs };
+        this.#observeWait(sourceKey, "process", { ...details, phase: "begin", at: fields.askedAt });
+        this.#observeWait(sourceKey, "process", { ...details, phase: "end", at: fields.endedAt,
+          startedAt: fields.askedAt, endedAt: fields.endedAt });
+      },
+      onTracks: tracks => file.noteVideo(tracks.some(track => track.type === "video")),
+      onReadStart: () => ({ storage: this.#reads.revision(sourceKey, fileIndex), memory: this.#reads.memoryRevision(),
+        demand: maps.epoch(sourceKey, fileIndex) }),
+      onReadResult: async (statement, result, revision) => {
+        if (revision.demand !== maps.epoch(sourceKey, fileIndex)) return;
+        if (demand && !maps.wantsInterval(sourceKey, fileIndex, demand)) return;
+        if (statement === "keyframes" && result.kind === "result") {
+          this.#learnKeyframes(params, { times: result.value?.times ?? null, tolerance: result.value?.tolerance ?? 0,
+            format: this.#formatOf(sourceKey, fileIndex) });
+        }
+        const finished = this.#reads.record(params, statement, result, revision.storage, revision.memory);
+        if (statement === "chapters" && result.passive) await maps.withdrawMetadata(sourceKey, fileIndex, statement);
+        else {
+          const metadataStatement = requestId ? `${statement}:${requestId}` : statement;
+          if (metadataTracker && result.kind === "needs-ranges") metadataTracker.statements.add(metadataStatement);
+          if (metadataTracker && result.kind !== "needs-ranges") metadataTracker.statements.delete(metadataStatement);
+          await maps.metadata({ sourceKey, fileIndex, statement: metadataStatement, result,
+            ...(statement === "chapters" ? { priority: 1, urgent: false, deadlineAt: null } : {}),
+            ...(demand ? { priority: demand.priority, urgent: demand.urgent, deadlineAt: demand.deadlineAt, interval: demand, leadSeconds: demand.leadSeconds ?? 0 } : {}),
+            ...(readPriority?.requestId ? { priority: readPriority.rank, urgent: readPriority.urgent === true,
+              deadlineAt: Number.isFinite(readPriority.deadlineAt) ? readPriority.deadlineAt : Number.POSITIVE_INFINITY,
+              scope: "preparation" } : {}),
+            // Neither a viewer's interval nor an encode input asked for it: the
+            // file read itself, and that read is wanted while the file is.
+            ...(!demand && !readPriority?.requestId ? { owner: "file" } : {}) });
+        }
+        if (finished && result.kind === "result") {
+          void maps.refresh(sourceKey, fileIndex).catch(error =>
+            this.#warn(`download map source=${sourceKey} file=${fileIndex} metadata refresh failed: ${error?.message ?? error}`));
+        }
+      },
+      portionBytes: file.portionBytes
+    };
+    return params;
+  }
+
+  #trackerFor(signal, sourceKey, fileIndex) {
+    const trackerKey = `${sourceKey}:${fileIndex}`;
+    let trackersForSignal = this.#trackers.get(signal);
+    if (!trackersForSignal) this.#trackers.set(signal, trackersForSignal = new Map());
+    let metadataTracker = trackersForSignal.get(trackerKey);
+    if (!metadataTracker) {
+      metadataTracker = { statements: new Set(), abort: null };
+      const tracker = metadataTracker;
+      tracker.abort = () => {
+        for (const statement of tracker.statements) {
+          void this.#maps.withdrawMetadata(sourceKey, fileIndex, statement).catch(error =>
+            this.#warn(`encode input demand withdrawal failed: ${error.message}`));
+        }
+        tracker.statements.clear();
+        trackersForSignal.delete(trackerKey);
+        if (trackersForSignal.size === 0) this.#trackers.delete(signal);
+      };
+      trackersForSignal.set(trackerKey, tracker);
+      if (signal.aborted) tracker.abort();
+      else signal.addEventListener("abort", tracker.abort, { once: true });
+    }
+    return metadataTracker;
+  }
+}

package/services/server/PreparationReads.js

@@ -0,0 +1,175 @@
+/**
+ * @file The reads a source preparation makes: its `inspect` port, and the
+ * publication of the native source map that follows a read.
+ *
+ * Moved out of `server.js` verbatim (torrent-tv/meta#280): every free variable
+ * is a port, and the preparation it reports to is passed with each call, since
+ * it is built after this owner.
+ */
+
+export class PreparationReads {
+  #paramsFor;
+  #containers;
+  #subtitles;
+  #fileLengthOf;
+  #viewersOf;
+  #segmentSeconds;
+  #preparationInterval;
+  #segmentInputs;
+  #nativeMaps;
+  #maps;
+  #record;
+  #planEncodersSoon;
+
+  /**
+   * @param {object} ports
+   * @param {(work: object) => Promise<object | null>} ports.paramsFor - MediaReadParams#paramsFor.
+   * @param {{ inspect: Function, containerFor: Function }} ports.containers
+   * @param {{ inspectFile: Function, inspectPackets: Function }} ports.subtitles
+   * @param {(sourceKey: string, fileIndex: number) => number | undefined} ports.fileLengthOf
+   * @param {(sourceKey: string) => object[]} ports.viewersOf - Viewers#forSource.
+   * @param {number} ports.segmentSeconds
+   * @param {(role: string, from: number, segmentSeconds: number) => object} ports.preparationInterval
+   * @param {(input: { index: object, tracks: object[] }) => { forInterval: Function }} ports.segmentInputs
+   * @param {{ packets: Function, original: Function }} ports.nativeMaps
+   * @param {{ metadata: Function, native: Function }} ports.maps
+   * @param {(params: object, statement: string, result: object, storage: unknown, memory: unknown) => boolean} ports.record
+   * @param {() => void} ports.planEncodersSoon
+   */
+  constructor({ paramsFor, containers, subtitles, fileLengthOf, viewersOf, segmentSeconds, preparationInterval,
+    segmentInputs, nativeMaps, maps, record, planEncodersSoon }) {
+    this.#paramsFor = paramsFor;
+    this.#containers = containers;
+    this.#subtitles = subtitles;
+    this.#fileLengthOf = fileLengthOf;
+    this.#viewersOf = viewersOf;
+    this.#segmentSeconds = segmentSeconds;
+    this.#preparationInterval = preparationInterval;
+    this.#segmentInputs = segmentInputs;
+    this.#nativeMaps = nativeMaps;
+    this.#maps = maps;
+    this.#record = record;
+    this.#planEncodersSoon = planEncodersSoon;
+  }
+
+  /**
+   * The native source map of a work whose input has been read.
+   *
+   * @param {object} work
+   * @param {object} preparation - `{ accepts, urgentReadyFor, ... }`, the source preparation.
+   */
+  async publishNative(work, preparation) {
+    if (!work.nativeInput || !preparation.accepts(work)) return Promise.resolve();
+    const watching = this.#viewersOf(work.sourceKey)
+      .filter(viewer => viewer.source.selectedFileIndex === work.fileIndex && viewer.outputs.size === 0);
+    const convert = work.nativeInput.container ? this.#nativeMaps.original : this.#nativeMaps.packets;
+    const zones = await convert({ ...work.nativeInput, viewers: watching,
+      allowanceSeconds: this.#segmentSeconds,
+      urgentReadyFor: viewer => preparation.urgentReadyFor(viewer) });
+    if (!preparation.accepts(work)) return;
+    return this.#maps.native({ sourceKey: work.sourceKey, fileIndex: work.fileIndex, zones });
+  }
+
+  /**
+   * Reads what the work asks for, and publishes what each read finds.
+   *
+   * @param {object} work
+   * @param {object} preparation
+   * @returns {Promise<object>} The answer the source preparation takes.
+   */
+  async inspect(work, preparation) {
+    const params = await this.#paramsFor(work);
+    if (!params) return { kind: "needs-source" };
+    params.isCurrent = () => preparation.accepts(work);
+    const originalContainer = work.statement === "packets" ? await this.#containers.containerFor(params) : null;
+    const navigation = work.statement === "packets" && work.role !== "subtitle-embedded"
+      ? await this.#containers.inspect(params, "source-navigation") : { kind: "result", value: false };
+    if (navigation.kind !== "result") return navigation;
+    const originalRanges = navigation.value;
+    if (!originalRanges && work.statement === "packets" && work.role === "source-rest" && preparation.accepts(work)) {
+      const length = this.#fileLengthOf(work.sourceKey, work.fileIndex);
+      if (length > 0) {
+        const statement = `${work.statement}:${work.requestId}:input`;
+        await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex, statement,
+          result: { kind: "needs-ranges", ranges: [[0, length - 1]], requestId: statement },
+          scope: "preparation", ...preparation.demandFor(work) });
+      }
+    }
+    if ((work.statement === "packets" && (work.role !== "source-rest" || originalRanges)) || work.role === "subtitle-embedded" && work.statement === "subtitle-cues") {
+      const info = await this.#containers.inspect({ ...params, onReadResult: undefined }, "media-info");
+      if (info.kind !== "result") return info;
+      const positions = this.#viewersOf(work.sourceKey)
+        .filter(viewer => viewer.source.selectedFileIndex === work.fileIndex &&
+          (work.ownerId === undefined || viewer.id === work.ownerId))
+        .map(viewer => viewer.positionSeconds() ?? 0);
+      const from = (positions.length ? Math.min(...positions) : 0) + (Number(info.value?.startTimeSeconds) || 0);
+      params.packetInterval = this.#preparationInterval(work.role, from, this.#segmentSeconds);
+      if (work.role === "subtitle-embedded") {
+        const tracks = await this.#containers.containerFor(params).then(container => container.readTracks());
+        const track = tracks.find(track => track.type === "subtitle" && track.declaredIndex === work.trackIndex);
+        if (!track || track.isTextBased?.() !== true) return { kind: "terminal", reason: "subtitle-track-not-supported" };
+        params.packetInterval.trackIds = [track.trackNumber];
+        params.subtitleTrackIndex = work.trackIndex;
+      }
+    }
+    params.onReadResult = async (statement, result, revision) => {
+      if (!preparation.accepts(work)) return;
+      this.#record(params, statement, result, revision.storage, revision.memory);
+      const inputStatement = `${work.statement}:${work.requestId}:input`;
+      if (statement === "source-ranges" && result.kind === "result") {
+        if (work.selected) work.inputRanges = result.value.ranges;
+        if (work.role === "source-rest") {
+          const info = await this.#containers.inspect({ ...params, onReadResult: undefined }, "media-info");
+          if (!preparation.accepts(work)) return;
+          if (info.kind === "result") {
+            work.nativeInput = { container: originalContainer, durationSeconds: info.value.durationSeconds,
+              startTimeSeconds: info.value.startTimeSeconds ?? 0 };
+            await this.publishNative(work, preparation);
+          }
+        } else {
+          await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex,
+            statement: inputStatement, result: { kind: "needs-ranges", ranges: result.value.ranges, requestId: inputStatement },
+            scope: "preparation", ...preparation.demandFor(work) });
+          if (work.selected) await preparation.bytesChanged(work.sourceKey, work.fileIndex);
+        }
+      }
+      if (statement === "packets" && work.role === "source-rest" && result.kind === "result") {
+        const tracks = await this.#containers.containerFor(params).then(container => container.readTracks());
+        const info = await this.#containers.inspect({ ...params, onReadResult: undefined }, "media-info");
+        if (!preparation.accepts(work)) return;
+        if (info.kind === "result") {
+          work.nativeInput = { index: result.value, tracks, durationSeconds: info.value.durationSeconds,
+            startTimeSeconds: info.value.startTimeSeconds ?? 0 };
+          await this.publishNative(work, preparation);
+        }
+      }
+      if (statement === "packets" && work.role !== "source-rest" && result.kind === "result" && (work.selected || work.ownerFileIndex !== undefined)) {
+        const tracks = await this.#containers.containerFor(params).then(container => container.readTracks());
+        if (!preparation.accepts(work)) return;
+        const bounds = tracks.filter(track => ["video", "audio"].includes(track.type))
+          .map(track => result.value.boundsOf(track.trackNumber)).filter(Boolean);
+        const interval = params.packetInterval ?? (bounds.length ? {
+          from: Math.max(0, Math.min(...bounds.map(bound => bound.start))), to: Math.max(...bounds.map(bound => bound.end))
+        } : null);
+        if (interval && interval.to > interval.from) {
+          const input = work.role === "subtitle-embedded"
+            ? result.value.inputFor({ trackId: params.packetInterval.trackIds[0], ...interval })
+            : this.#segmentInputs({ index: result.value, tracks }).forInterval(interval);
+          if (work.selected) work.inputRanges = input.kind === "result" ? input.ranges : null;
+          await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex,
+            statement: inputStatement, result: input.kind === "result" ? { kind: "needs-ranges", ranges: input.ranges, requestId: inputStatement } : input,
+            scope: "preparation", ...preparation.demandFor(work) });
+          if (work.selected) await preparation.bytesChanged(work.sourceKey, work.fileIndex);
+        }
+      }
+      if (!preparation.accepts(work)) return;
+      await this.#maps.metadata({ sourceKey: work.sourceKey, fileIndex: work.fileIndex,
+        statement: `${work.statement}:${work.requestId}`, result, scope: "preparation", ...preparation.demandFor(work) });
+      preparation.result(work, result);
+      if (["subtitle-file", "subtitle-cues"].includes(statement)) this.#planEncodersSoon();
+    };
+    return work.statement === "subtitle-file"
+      ? this.#subtitles.inspectFile(params) : work.statement === "subtitle-cues"
+        ? this.#subtitles.inspectPackets(params) : this.#containers.inspect(params, originalRanges ? "source-ranges" : work.statement);
+  }
+}

package/services/server/forwarded-response-log.js

@@ -0,0 +1,55 @@
+/**
+ * @file The log of a forwarded transcode-session response (the registry's
+ * request, followed from its arrival to its last byte).
+ *
+ * Moved out of `server.js` verbatim (torrent-tv/meta#280). It imports nothing:
+ * the logger and the clock are passed in.
+ */
+
+/**
+ * Registers, on `app`, the hooks that write the `[forecast-http]` and
+ * `[http-response]` lines of a `POST /api/transcode-sessions` carrying
+ * `x-ttv-forwarded-request-id`. Any other request logs nothing.
+ *
+ * @param {import("fastify").FastifyInstance} app
+ * @param {{ log: (line: string) => void, warn: (line: string) => void, now?: () => number }} ports
+ */
+export function installForwardedResponseLog(app, { log, warn, now = () => performance.now() }) {
+  const forwardedSessionResponseStarts = new WeakMap();
+  const logStage = (stage, req) => {
+    const startedAt = forwardedSessionResponseStarts.get(req);
+    const requestId = req.headers["x-ttv-forwarded-request-id"];
+    if (startedAt === undefined || typeof requestId !== "string") return;
+    const at = now();
+    log(`[forecast-http] stage=${stage} requestId=${requestId} atMs=${at.toFixed(3)} ` +
+      `elapsedMs=${(at - startedAt).toFixed(3)}`);
+  };
+  app.addHook("onRequest", async (req, reply) => {
+    const requestId = req.headers["x-ttv-forwarded-request-id"];
+    if (typeof requestId !== "string" || req.method !== "POST" || req.url !== "/api/transcode-sessions") return;
+    const startedAt = now();
+    forwardedSessionResponseStarts.set(req, startedAt);
+    logStage("onRequest", req);
+    reply.raw.once("finish", () => {
+      logStage("finish", req);
+      log(`[http-response] requestId=${requestId} method=${req.method} url=${req.url} ` +
+        `responseMs=${(now() - startedAt).toFixed(1)} status=${reply.statusCode} ` +
+        `contentLength=${reply.raw.getHeader("content-length") ?? "unknown"}`);
+    });
+    reply.raw.once("close", () => {
+      if (!reply.raw.writableFinished) {
+        logStage("close", req);
+        warn(`[http-response] requestId=${requestId} method=${req.method} url=${req.url} ` +
+          `closedMs=${(now() - startedAt).toFixed(1)} status=${reply.statusCode}`);
+      }
+    });
+  });
+  app.addHook("preSerialization", async (req, _reply, payload) => {
+    logStage("preSerialization", req);
+    return payload;
+  });
+  app.addHook("onSend", async (req, _reply, payload) => {
+    logStage("onSend", req);
+    return payload;
+  });
+}

package/services/server/start-playback.js

@@ -0,0 +1,34 @@
+/**
+ * @file Where playback starts: viewer changes reach the source preparation and
+ * the download maps, and what an earlier process left behind is adopted.
+ *
+ * The subscription is made before the adoption, so whatever the adoption or
+ * anything after it changes about viewers reaches the maps. This is the seam
+ * the start order is tested through, since `server.js` cannot run in a test.
+ */
+
+/**
+ * @param {object} graph
+ * @param {{ viewerChanges: import("node:events").EventEmitter,
+ *           lifecycle: { adoptSegmentsLeftBehind(): object } }} graph.outputParts
+ * @param {{ viewersChanged(): Promise<unknown> }} graph.downloadMaps
+ * @param {() => { refresh(): unknown }} graph.preparation   - read when a change comes, never at the call
+ * @param {() => void} graph.onStateChanged
+ * @param {(line: string) => void} graph.warn
+ * @returns {object} what `adoptSegmentsLeftBehind` returned
+ */
+export function startPlayback({ outputParts, downloadMaps, preparation, onStateChanged, warn }) {
+  outputParts.viewerChanges.on("change", () => {
+    void preparation().refresh();
+    void downloadMaps.viewersChanged().catch(error => warn(`download maps after a viewer change: ${error.message}`));
+    onStateChanged();
+  });
+  // What the last life of this process left on the disk. The kernel kills this
+  // one often enough for that to be an ordinary state rather than an odd one —
+  // twice in a single viewing on 2026-09-02 — and when it does, no exit handler
+  // runs and nothing is cleared up. So this is both the cleanup and the only
+  // record that those encoders ended at all: it says what it found before it
+  // decides anything, keeps the segments whose closure is proven, and removes
+  // the one piece per output that was being written when the process died.
+  return outputParts.lifecycle.adoptSegmentsLeftBehind();
+}

package/services/server/torrent-pool-ports.js

@@ -0,0 +1,105 @@
+/**
+ * @file The torrent-pool adapters of the output graph: what the encoders and
+ * the machine budget ask of the torrent thread, as plain functions.
+ *
+ * Moved out of the `wireOutputs` call in `server.js` verbatim
+ * (torrent-tv/meta#280). It imports nothing: the pool and the registry are
+ * passed in.
+ */
+
+/**
+ * @param {object} ports
+ * @param {object} ports.torrentPool
+ * @param {{ get: (sourceKey: string) => { sourceType: string, source: unknown } | undefined }} ports.sourceRegistry
+ * @param {string} ports.wholeFilesRoot - Where whole files are kept (`completedFilesRoot()`).
+ */
+export function torrentPoolPorts({ torrentPool, sourceRegistry, wholeFilesRoot }) {
+  return {
+    readEncodeRanges: async (source, ranges, maxBytes) => {
+      const torrent = torrentPool.knownTorrent(source.sourceKey);
+      return torrent ? torrentPool.readHeldRangesOf(torrent, source.fileIndex, ranges, maxBytes) : null;
+    },
+    openEncodeWholeFile: source => torrentPool.acquireWholeFile(source),
+    // Which bytes of a file are downloaded whole now — what an original
+    // input's stretch may extend over. A snapshot: the copy that follows
+    // holds the pieces it reads, and refuses where one has gone since.
+    readEncodeHeldRanges: async (source) => {
+      const torrent = torrentPool.knownTorrent(source.sourceKey);
+      return torrent ? torrentPool.heldRangesOf(torrent, source.fileIndex) : [];
+    },
+    // What the spilled pieces weigh on the torrent thread, and how to tell them
+    // their share of the disk. The owner of the disk is on this side, where the
+    // segments are; the pieces are on the other.
+    spillDisk: typeof torrentPool.allowSpillBytes === "function"
+      ? {
+          held: () => torrentPool.spilledBytes ?? 0,
+          allow: (bytes) => torrentPool.allowSpillBytes(bytes)
+        }
+      : null,
+    // Files downloaded whole, kept as files. They live on the torrent thread
+    // too, and until 2026-09-14 they had no bound of any kind — a 2.8 GB film
+    // on a host whose disk is often a 32 GB card.
+    wholeFiles: typeof torrentPool.allowWholeFileBytes === "function"
+      ? {
+          held: () => torrentPool.wholeFileBytes ?? 0,
+          required: () => torrentPool.wholeFileRequiredBytes ?? 0,
+          allow: (bytes) => torrentPool.allowWholeFileBytes(bytes),
+          root: wholeFilesRoot
+        }
+      : null,
+    // The pieces held IN memory, on the torrent thread. Told their share by the
+    // same owner that divides the disk: what does not fit here is spilled
+    // there, so the two cannot be divided apart.
+    memoryClaimant: typeof torrentPool.allowMemoryBytes === "function"
+      ? {
+          held: () => torrentPool.memoryClaim?.held ?? 0,
+          wanted: () => torrentPool.memoryClaim?.wanted ?? 0,
+          allow: (bytes) => torrentPool.allowMemoryBytes(bytes)
+        }
+      : null,
+    getTorrentTotals: async () => {
+      if (typeof torrentPool.getTorrentTotals !== "function") {
+        return null;
+      }
+      return torrentPool.getTorrentTotals();
+    },
+    setDownloadRate: (bytesPerSecond, because) => torrentPool.setDownloadRate?.(bytesPerSecond, because),
+    setSpeculativeHold: (held, because) => torrentPool.setSpeculativeHold?.(held, because),
+    getSourceStats: async (sourceKey, fileIndex, options) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return null;
+      }
+      try {
+        const torrent = torrentPool.knownTorrent(sourceKey);
+        if (!torrent) return null;
+        // Awaited for the same reason as the stats route: this now crosses a
+        // thread boundary and returns a promise.
+        return await torrentPool.getFileStats(torrent, Number.isInteger(fileIndex) ? fileIndex : null, options);
+      } catch {
+        return null;
+      }
+    },
+    // Pull one whole file onto the disk. Used for a soundtrack that ships beside
+    // the picture, once the encoder is as far ahead of the viewer as it is
+    // allowed to get — the one moment the swarm's capacity is demonstrably
+    // spare. A bounded read of the file's whole length, NOT `file.select()`:
+    // selecting a file alongside the readers' own windows is what made a seek
+    // wait 93 s while the swarm fetched 2.47 GB in file order (see
+    // `#syncSelections` in `torrent/torrent-pool.js`).
+    fetchWholeFile: async ({ sourceKey, fileIndex }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return;
+      }
+      const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+      // The same background fill the warm-up starts when a file is chosen, not a
+      // second way of doing it. It is guarded against running twice on one file,
+      // so the two triggers converge instead of putting two readers on the same
+      // soundtrack — and only one of them would have stood aside for the
+      // picture. This trigger remains for the session that never had a warm-up
+      // before it.
+      await torrentPool.fillFileInBackground?.(torrent, fileIndex);
+    }
+  };
+}