@torrent-tv/proxy 2.101.24 → 2.101.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.101.24",
+  "version": "2.101.25",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "repository": {

package/routes/api/client-logs/post.js

@@ -63,10 +63,10 @@ function sanitizeLine(value) {
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
- * @param {{ clientLogs: { write: (session: object, lines: string[]) => void } | null }} deps
+ * @param {{ clientLogs: { write: (session: object, lines: string[]) => void } | null, viewerRequests?: object }} deps
  * @returns {Promise<unknown>}
  */
-export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
+export async function handleApiClientLogsPost(req, reply, { clientLogs, viewerRequests }) {
   const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
   const session = {
     sessionId: safeString(body.sessionId, MAX_SID_LEN) || "unknown",
@@ -89,5 +89,18 @@ export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
   if (lines.length > 0) {
     clientLogs?.write(session, lines);
   }
+  for (const row of rows) {
+    const message = row && typeof row.msg === "string" ? row.msg : "";
+    const match = /^\[first-frame-observation\] consumer=([^ ]+) generation=(\d+) waitId=([^ ]+) wait=(\d+) audioReady=(true|false) elapsedMs=([\d.]+)$/.exec(message);
+    if (match) {
+      const elapsedMs = Number(match[6]);
+      if (match[1].length <= 64 && Number.isSafeInteger(Number(match[2])) && match[3].length <= 256 &&
+          Number.isSafeInteger(Number(match[4])) && match[5] === "true" &&
+          Number.isFinite(elapsedMs) && elapsedMs >= 0) {
+        viewerRequests?.noteFirstFrameObservation?.({ consumerId: match[1], generation: Number(match[2]),
+          waitId: match[3], wait: Number(match[4]), elapsedMs });
+      }
+    }
+  }
   return reply.code(204).send();
 }

package/routes/api/sources/files/get.js

@@ -15,14 +15,15 @@ import { logger } from "../../../../utils/logger.js";
  * @param {import("fastify").FastifyReply} reply
  * @param {{
  *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
- *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool
+ *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool,
+ *   viewerRequests?: object
  * }} deps
  * @returns {Promise<void>}
  */
 
 const CANCELLED = Symbol("cancelled");
 
-export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers }) {
+export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers, viewerRequests }) {
   const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
     return reply.code(400).send({ error: "sourceKey is required." });
@@ -72,13 +73,21 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
   }
   const consumerId = typeof req.query?.consumerId === "string" ? req.query.consumerId.trim() : "";
   if (consumerId) viewers?.visibleFiles(consumerId, sourceKey, contents.items.map(item => item.fileIndex));
+  const generationRaw = typeof req.query?.generation === "string" ? req.query.generation : "";
+  const generation = generationRaw !== "" && /^\d+$/.test(generationRaw) ? Number(generationRaw) : null;
+  const files = contents.files().map(file => {
+    if (!consumerId || !Number.isSafeInteger(generation) || file.kind !== "video" || file.excludedReason) return file;
+    const waitEstimate = viewerRequests?.waitEstimateForFile?.({ consumerId, generation, sourceKey,
+      fileIndex: file.fileIndex, fileName: file.relativePath ?? file.name, fileLength: file.length }) ?? null;
+    return waitEstimate ? { ...file, waitEstimate } : file;
+  });
   return reply.send({
     name: torrent.name ?? "",
     infoHash: torrent.infoHash ?? "",
     // In the order a person reads them — by folder, then by name, with runs of
     // digits compared as numbers. A torrent's own order is whatever the tool
     // that made it chose, and it is routinely by size.
-    files: contents.files(),
+    files,
     // The pictures, each with what belongs to it. By index, because the files
     // themselves are in the list above and saying them twice is how two copies
     // of one fact start.

package/routes/api/sources/stats/get.js

@@ -13,11 +13,12 @@ import { logger } from "../../../../utils/logger.js";
  * @param {import("fastify").FastifyReply} reply
  * @param {{
  *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
- *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool
+ *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool,
+ *   viewerRequests?: object
  * }} deps
  * @returns {Promise<void>}
  */
-export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool }) {
+export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool, viewerRequests }) {
   const sourceKey = typeof req.params.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
     return reply.code(400).send({ error: "sourceKey is required." });
@@ -28,6 +29,19 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     return reply.code(404).send({ error: "Source key was not found." });
   }
 
+  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
+  const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
+  const consumerId = typeof req.query.consumer === "string" ? req.query.consumer : "";
+  const generationRaw = typeof req.query.generation === "string" ? req.query.generation : "";
+  const generation = generationRaw !== "" && /^\d+$/.test(generationRaw) ? Number(generationRaw) : null;
+  const requestedFileName = typeof req.query.fileName === "string" ? req.query.fileName : "";
+  const requestedFileLength = typeof req.query.fileLength === "string" && /^\d+$/.test(req.query.fileLength)
+    ? Number(req.query.fileLength) : null;
+  const initialEstimate = () => consumerId && Number.isSafeInteger(generation) && Number.isSafeInteger(fileIndex)
+    ? viewerRequests?.waitEstimateForFile?.({ consumerId, generation, sourceKey, fileIndex,
+      fileName: requestedFileName, fileLength: requestedFileLength }) ?? null
+    : null;
+
   let torrent;
   try {
     torrent = torrentPool.knownTorrent(sourceKey);
@@ -37,18 +51,18 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     return reply.code(500).send({ error: `Failed to load torrent: ${message}` });
   }
   if (!torrent) {
-    return reply.code(202).send({ pending: true });
+    const waitEstimate = initialEstimate();
+    return reply.code(202).send({ pending: true, ...(waitEstimate ? { waitEstimate } : {}) });
   }
 
-  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
-  const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
-
-
   // Awaited: with the torrent on its own thread this is a round trip, not a
   // local lookup. Without the await the reply was the pending promise itself,
   // which serialises to `{}` — the empty stats seen in the field 2026-08-02.
   const stats = await torrentPool.getFileStats(torrent, fileIndex);
-  if (stats?.pending || !stats) return reply.code(202).send({ pending: true });
+  if (stats?.pending || !stats) {
+    const waitEstimate = initialEstimate();
+    return reply.code(202).send({ pending: true, ...(waitEstimate ? { waitEstimate } : {}) });
+  }
 
   // Diagnostic: surface the real swarm state per poll so a cold-start download
   // stall (0 peers / header not advancing → playback-plan blocks on the codec
@@ -121,5 +135,9 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     `file=${filePct} header=${header}${detail}`
   );
 
-  return reply.send(stats);
+  const waitEstimate = consumerId && Number.isSafeInteger(generation)
+    ? viewerRequests?.waitEstimateForSource?.({ consumerId, generation, sourceKey, fileIndex,
+      fileName: torrent.files?.[fileIndex]?.name ?? requestedFileName, fileLength: requestedFileLength, stats }) ?? null
+    : null;
+  return reply.send(waitEstimate ? { ...stats, waitEstimate } : stats);
 }

package/server.js

@@ -1406,10 +1406,11 @@ export async function startProxyServer({
     return handleApiSourcesPost(req, reply, { sourceRegistry, viewers: outputParts.viewers });
   });
   app.get("/api/sources/:sourceKey/stats", async (req, reply) =>
-    handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool })
+    handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool, viewerRequests: outputParts.viewerRequests })
   );
   app.get("/api/sources/:sourceKey/files", async (req, reply) =>
-    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers: outputParts.viewers })
+    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers: outputParts.viewers,
+      viewerRequests: outputParts.viewerRequests })
   );
   app.get("/api/sources/:sourceKey/files/:fileIndex/fingerprint", async (req, reply) =>
     handleApiSourceFingerprintGet(req, reply, {
@@ -1463,7 +1464,7 @@ export async function startProxyServer({
     ? createClientLogFiles(logFile)
     : createClientLogConsole((message) => logger.info(message));
   app.post("/api/client-logs", async (req, reply) =>
-    handleApiClientLogsPost(req, reply, { clientLogs })
+    handleApiClientLogsPost(req, reply, { clientLogs, viewerRequests: outputParts.viewerRequests })
   );
   app.post("/api/playback-plan", async (req, reply) =>
     handleApiPlaybackPlanPost(req, reply, { playbackPlanner, viewers: outputParts.viewers })

package/services/encode/LocalObservations.js

@@ -85,8 +85,11 @@ export class LocalObservations {
   /** @type {() => number} */
   #now;
 
-  /** @type {{ speed: Record<string, object[]>, rates: Record<string, object[]>, preparation: Record<string, object[]> }} */
-  #entries = { speed: {}, rates: {}, preparation: {} };
+  /** @type {Set<string>} */
+  #configurations = new Set();
+
+  /** @type {{ speed: Record<string, object[]>, rates: Record<string, object[]>, preparation: Record<string, object[]>, firstFrame: Record<string, object[]> }} */
+  #entries = { speed: {}, rates: {}, preparation: {}, firstFrame: {} };
 
   /**
    * @param {object} params
@@ -152,6 +155,7 @@ export class LocalObservations {
    * @returns {void}
    */
   load(currentConfigurations) {
+    this.#configurations = new Set(currentConfigurations);
     if (!this.#filePath) {
       return;
     }
@@ -168,11 +172,14 @@ export class LocalObservations {
     const allowed = new Set(currentConfigurations);
     let kept = 0;
     let dropped = 0;
-    for (const kind of ["speed", "rates", "preparation"]) {
+    const firstFrameKey = this.#firstFrameKey();
+    for (const kind of ["speed", "rates", "preparation", "firstFrame"]) {
       const section = raw.entries[kind] && typeof raw.entries[kind] === "object" ? raw.entries[kind] : {};
       for (const [key, readings] of Object.entries(section)) {
-        const configuration = key.split("|")[0];
-        if (!allowed.has(configuration) || !Array.isArray(readings)) {
+        const matches = kind === "firstFrame"
+          ? key === firstFrameKey
+          : allowed.has(key.split("|")[0]);
+        if (!matches || !Array.isArray(readings)) {
           dropped += 1;
           continue;
         }
@@ -256,6 +263,75 @@ export class LocalObservations {
     this.#save();
   }
 
+  /**
+   * Keep a browser-measured wait outcome with the source and link readings
+   * visible before the container was inspected. These readings are useful
+   * only on the encoder configurations present on this host.
+   *
+   * @param {{ seconds: number, features: object }} params
+   * @returns {void}
+   */
+  noteFirstFrame({ seconds, features }) {
+    if (!Number.isFinite(seconds) || seconds < 0 || !features || typeof features !== "object") return;
+    const key = this.#firstFrameKey();
+    const readings = [...(this.#entries.firstFrame[key] ?? []), {
+      seconds,
+      extension: typeof features.extension === "string" ? features.extension : "",
+      fileLength: positive(features.fileLength),
+      downloadSpeed: nonNegative(features.downloadSpeed),
+      linkMbps: nonNegative(features.linkMbps),
+      headerRemaining: nonNegative(features.headerRemaining),
+      peers: nonNegative(features.peers),
+      at: this.#now()
+    }].slice(-READINGS_KEPT);
+    this.#entries.firstFrame[key] = readings;
+    this.#save();
+  }
+
+  /**
+   * Predict this host's first-frame wait from the closest measured start with
+   * the same media suffix. Distance is the sum of squared log-ratios for the
+   * independent measured inputs; it does not mix bytes, bit rates and peers
+   * in their raw units.
+   *
+   * @param {object} features
+   * @returns {number | null}
+   */
+  firstFrameSeconds(features) {
+    if (!features || typeof features !== "object") return null;
+    const readings = this.#entries.firstFrame[this.#firstFrameKey()] ?? [];
+    const candidates = readings.filter(reading => reading.extension === (features.extension ?? ""));
+    if (candidates.length === 0) return null;
+    const dimensions = ["fileLength", "downloadSpeed", "linkMbps", "headerRemaining", "peers"];
+    const scales = new Map(dimensions.map(key => [key, median(candidates
+      .map(reading => nonNegative(reading[key]))
+      .filter(value => value !== null && value > 0))]));
+    let best = null;
+    for (const reading of candidates) {
+      let distance = 0;
+      let used = 0;
+      for (const key of dimensions) {
+        const scale = scales.get(key);
+        const current = nonNegative(features[key]);
+        const previous = nonNegative(reading[key]);
+        if (scale === null || current === null || previous === null) continue;
+        const difference = Math.log1p(current / scale) - Math.log1p(previous / scale);
+        distance += difference * difference;
+        used += 1;
+      }
+      if (used === 0) continue;
+      distance /= used;
+      if (!best || distance < best.distance || (distance === best.distance && reading.at > best.reading.at)) {
+        best = { distance, reading };
+      }
+    }
+    return best?.reading.seconds ?? null;
+  }
+
+  #firstFrameKey() {
+    return `firstFrame:${[...this.#configurations].sort().join("||")}`;
+  }
+
   /**
    * The slowest this mode has been seen running alone on comparable material,
    * or null where nothing comparable has been seen.
@@ -349,6 +425,27 @@ export class LocalObservations {
   }
 }
 
+/** @param {unknown} value @returns {number | null} */
+function positive(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : null;
+}
+
+/** @param {unknown} value @returns {number | null} */
+function nonNegative(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+/** @param {number[]} values @returns {number | null} */
+function median(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+}
+
 /**
  * What an observation of an encode is filed as having been made FROM.
  *

package/services/server/ViewerRequests.js

@@ -60,6 +60,8 @@ export class ViewerRequests {
   #host;
   /** @type {WeakMap<object, Map<string, object>>} */
   #rateStateBySession = new WeakMap();
+  /** @type {Map<string, { consumerId: string, generation: number, fileIndex: number | null, waitId: string, features: object, updatedAt: number, revision: number, observedWaits: Set<number> }>} */
+  #earlyWaits = new Map();
   /**
    * What the start forecasts cost, said once a minute: how many there were,
    * their time on the main thread, and for each track whether the times of its
@@ -97,6 +99,131 @@ export class ViewerRequests {
     this.#host = host;
   }
 
+  /**
+   * Attach a host-matched estimate to the file list before the viewer chooses
+   * a file, so the original action need not wait for a torrent-worker round trip.
+   *
+   * @param {{ consumerId: string, generation: number, sourceKey: string, fileIndex: number, fileName: string, fileLength: number }} params
+   * @returns {object | null}
+   */
+  waitEstimateForFile({ consumerId, generation, sourceKey, fileIndex, fileName, fileLength }) {
+    if (!consumerId || !Number.isSafeInteger(generation) || typeof sourceKey !== "string" ||
+        !Number.isSafeInteger(fileIndex) || fileIndex < 0) return null;
+    const waitId = `${sourceKey}:${fileIndex}:${generation}`;
+    const key = `${consumerId}:${waitId}`;
+    const extension = typeof fileName === "string" ? fileName.split(".").at(-1)?.toLowerCase() ?? "" : "";
+    const features = {
+      extension,
+      fileLength,
+      downloadSpeed: null,
+      linkMbps: this.#host.viewers.get(consumerId)?.linkReading()?.linkMbps,
+      headerRemaining: null,
+      peers: null
+    };
+    const current = this.#earlyWaits.get(key);
+    if (current?.waitId === waitId && current.hasSourceObservation) {
+      const seconds = this.#host.firstFrameSecondsOf?.(current.features) ?? null;
+      if (!Number.isFinite(seconds) || seconds < 0) return null;
+      return { version: 1, waitId, revision: current.revision, remainingSeconds: seconds, ageMs: 0 };
+    }
+    const sameWait = current?.waitId === waitId;
+    const revision = sameWait ? current.revision : 0;
+    const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current });
+    const changed = this.#recordEarlyWaitSnapshot(context, features);
+    if (sameWait && changed) context.revision += 1;
+    this.#pruneEarlyWaits();
+    const seconds = this.#host.firstFrameSecondsOf?.(features) ?? null;
+    if (!Number.isFinite(seconds) || seconds < 0) return null;
+    return { version: 1, waitId, revision, remainingSeconds: seconds, ageMs: 0 };
+  }
+
+  /**
+   * Keep the measurements available before the container is inspected and
+   * predict the complete first-frame wait from this host's earlier outcomes.
+   *
+   * @param {{ consumerId: string, generation: number, sourceKey: string, fileIndex: number | null, fileName?: string, fileLength?: number | null, stats?: object }} params
+   * @returns {object | null}
+   */
+  waitEstimateForSource({ consumerId, generation, sourceKey, fileIndex, fileName = "", fileLength = null, stats = {} }) {
+    if (!consumerId || !Number.isSafeInteger(generation) || typeof sourceKey !== "string") return null;
+    const waitId = `${sourceKey}:${fileIndex ?? "all"}:${generation}`;
+    const key = `${consumerId}:${waitId}`;
+    const extension = typeof fileName === "string" ? fileName.split(".").at(-1)?.toLowerCase() ?? "" : "";
+    const features = {
+      extension,
+      fileLength: Number.isFinite(stats?.fileLength) && stats.fileLength > 0
+        ? stats.fileLength : fileLength,
+      downloadSpeed: stats?.downloadSpeed,
+      linkMbps: this.#host.viewers.get(consumerId)?.linkReading()?.linkMbps,
+      headerRemaining: Number.isFinite(stats?.headerBytes) && Number.isFinite(stats?.headerDownloadedBytes)
+        ? Math.max(0, stats.headerBytes - stats.headerDownloadedBytes) : null,
+      peers: stats?.connectedPeers ?? stats?.numPeers
+    };
+    const current = this.#earlyWaits.get(key);
+    const revision = current?.waitId === waitId ? current.revision + 1 : 0;
+    const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current,
+      sourceObserved: true });
+    this.#recordEarlyWaitSnapshot(context, features);
+    this.#pruneEarlyWaits();
+    const seconds = this.#host.firstFrameSecondsOf?.(features) ?? null;
+    if (!Number.isFinite(seconds) || seconds < 0) return null;
+    return { version: 1, waitId, revision, remainingSeconds: seconds, ageMs: 0 };
+  }
+
+  /**
+   * Learn from the browser's presented-frame measurement for the current
+   * viewing. The saved source and link readings are the ones available at
+   * selection time, before the full track plan existed.
+   *
+   * @param {{ consumerId: string, generation: number, waitId: string, wait: number, elapsedMs: number }} params
+   * @returns {void}
+   */
+  noteFirstFrameObservation({ consumerId, generation, waitId, wait, elapsedMs }) {
+    const key = `${consumerId}:${waitId}`;
+    const early = this.#earlyWaits.get(key);
+    if (!early || early.generation !== generation || !Number.isSafeInteger(wait) || wait < 0 || early.observedWaits.has(wait) ||
+        !Number.isFinite(elapsedMs) || elapsedMs < 0) return;
+    for (const snapshot of early.snapshots) {
+      this.#host.noteFirstFrame?.({ seconds: elapsedMs / 1000, features: snapshot });
+    }
+    early.observedWaits.add(wait);
+    early.updatedAt = Date.now();
+  }
+
+  #setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current, sourceObserved = false }) {
+    const sameWait = current?.waitId === waitId;
+    const context = sameWait ? current : {
+      consumerId,
+      generation,
+      fileIndex,
+      waitId,
+      snapshots: [],
+      hasSourceObservation: false,
+      observedWaits: new Set()
+    };
+    Object.assign(context, { consumerId, generation, fileIndex, waitId, features, updatedAt: Date.now(), revision,
+      hasSourceObservation: context.hasSourceObservation || sourceObserved });
+    this.#earlyWaits.set(`${consumerId}:${waitId}`, context);
+    return context;
+  }
+
+  #recordEarlyWaitSnapshot(context, features) {
+    const previous = context.snapshots.at(-1);
+    if (previous && JSON.stringify(previous) === JSON.stringify(features)) return false;
+    const snapshot = { ...features };
+    if (context.snapshots.length < 2) context.snapshots.push(snapshot);
+    else context.snapshots[1] = snapshot;
+    return true;
+  }
+
+  #pruneEarlyWaits() {
+    const cutoff = Date.now() - 30 * 60_000;
+    for (const [key, value] of this.#earlyWaits) {
+      if (value.updatedAt < cutoff) this.#earlyWaits.delete(key);
+    }
+    while (this.#earlyWaits.size > 1000) this.#earlyWaits.delete(this.#earlyWaits.keys().next().value);
+  }
+
   /**
    * Open an output of a file for this viewer and put them on it.
    *

package/services/server/wire-outputs.js

@@ -650,6 +650,8 @@ export function wireOutputs({
       const predicted = Number(qualityStateOf(output).predictedSpeedWhenOffered);
       return Number.isFinite(predicted) && predicted > 0 ? predicted : null;
     },
+    firstFrameSecondsOf: (features) => parts.localObservations?.firstFrameSeconds(features) ?? null,
+    noteFirstFrame: (observation) => parts.localObservations?.noteFirstFrame(observation),
     audioDescriptionOf,
     openSecondsOf: (output) => runStartSecondsOf(output),
     processingStartupSecondsOf: (output) => runStartSecondsOf(output),