@torrent-tv/proxy 2.103.0 → 2.104.1

package/package.json

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

package/services/torrent/torrent-pool.js

@@ -27,6 +27,7 @@ import { noteTorrentDestroyed } from "./destroyed-torrents.js";
 import { PieceTimings, describePieceTiming } from "./piece-timing.js";
 import { TailRepeat } from "./worker/tail-repeat.js";
 import { tracePieceStorePut } from "./worker/trace-piece-store-put.js";
+import { beginSwarmLifecycleTrace, noteSwarmDiscovery, noteSwarmMetadata, noteSwarmPeer } from "./worker/trace-swarm-lifecycle.js";
 
 /**
  * The second-peer requests for the last blocks of a piece somebody waits for,
@@ -967,7 +968,8 @@ export class TorrentPool {
   /**
    * When each torrent was added, and when its first peer connected.
    *
-   * @type {WeakMap<import("webtorrent").Torrent, { addedAt: number, firstPeerAt: number | null }>}
+   * @type {WeakMap<import("webtorrent").Torrent, { addedAt: number, addedAtMonotonic: number, firstPeerAt: number | null,
+   *   firstPeerAtMonotonic: number | null, metadataWaitStartedAt: number | null }>}
    */
   #swarmTimingByTorrent = new WeakMap();
   #waitTraceByTorrent = new WeakMap();
@@ -1509,10 +1511,16 @@ export class TorrentPool {
     if (waitTrace?.trace === true && typeof waitTrace.sourceKey === "string") {
       this.#waitTraceByTorrent.set(torrent, waitTrace);
     }
+    const alreadyTracked = this.#swarmTimingByTorrent.has(torrent);
+    if (!alreadyTracked) {
+      this.#swarmTimingByTorrent.set(torrent, { addedAt: Date.now(), addedAtMonotonic: performance.now(),
+        firstPeerAt: null, firstPeerAtMonotonic: null, peerWaitStartedAt: null, metadataWaitStartedAt: null });
+    }
     const trace = (process, phase, fields = {}) => {
       const context = this.#waitTraceByTorrent.get(torrent);
       if (context?.trace === true) context.emitWaitTrace?.(context.sourceKey, process, phase, fields);
     };
+    const pool = this;
     const wrap = (method, process) => {
       const original = torrent[method];
       if (typeof original !== "function") return;
@@ -1521,20 +1529,32 @@ export class TorrentPool {
         trace(process, "begin", { startedAt });
         try {
           const result = original.apply(this, args);
+          const noteDiscoveryEnd = () => {
+            if (process === "W2" && result !== false) {
+              const timing = pool.#swarmTimingByTorrent.get(torrent);
+              if (timing) noteSwarmDiscovery(timing, trace, performance.now());
+            }
+          };
           if (result && typeof result.then === "function") {
             return result.then(value => {
-              trace(process, "end", { startedAt, endedAt: performance.now(), outcome: "resolved" });
+              noteDiscoveryEnd();
+              const endedAt = performance.now();
+              trace(process, "end", { startedAt, endedAt, durationMs: endedAt - startedAt, outcome: "resolved" });
               return value;
             }, error => {
-              trace(process, "end", { startedAt, endedAt: performance.now(), outcome: "error",
+              const endedAt = performance.now();
+              trace(process, "end", { startedAt, endedAt, durationMs: endedAt - startedAt, outcome: "error",
                 error: String(error?.message ?? error) });
               throw error;
             });
           }
-          trace(process, "end", { startedAt, endedAt: performance.now(), outcome: "returned" });
+          noteDiscoveryEnd();
+          const endedAt = performance.now();
+          trace(process, "end", { startedAt, endedAt, durationMs: endedAt - startedAt, outcome: "returned" });
           return result;
         } catch (error) {
-          trace(process, "end", { startedAt, endedAt: performance.now(), outcome: "error",
+          const endedAt = performance.now();
+          trace(process, "end", { startedAt, endedAt, durationMs: endedAt - startedAt, outcome: "error",
             error: String(error?.message ?? error) });
           throw error;
         }
@@ -1542,7 +1562,6 @@ export class TorrentPool {
     };
     if (waitTrace?.trace === true && !this.#waitTraceHooks.has(torrent)) {
       this.#waitTraceHooks.add(torrent);
-      wrap("_onListening", "W1");
       wrap("_startDiscovery", "W2");
       wrap("_onStore", "W6");
       tracePieceStorePut(pieceStoreOf(torrent), trace);
@@ -1557,8 +1576,17 @@ export class TorrentPool {
           }, ...args);
         };
       }
-      torrent.on("metadata", metadata => trace("W4", "event", { files: metadata?.files?.length ?? null }));
-      torrent.on("wire", wire => trace("W3", "event", { peer: String(wire?.remoteAddress ?? "?") }));
+      const timing = this.#swarmTimingByTorrent.get(torrent);
+      if (timing) beginSwarmLifecycleTrace(timing, trace, Boolean(torrent.metadata));
+      torrent.on("metadata", metadata => {
+        const current = this.#swarmTimingByTorrent.get(torrent);
+        if (current) noteSwarmMetadata(current, trace, metadata?.files?.length ?? null);
+      });
+      torrent.on("wire", wire => {
+        trace("W3", "event", { peer: String(wire?.remoteAddress ?? "?") });
+        const current = this.#swarmTimingByTorrent.get(torrent);
+        if (current) noteSwarmPeer(current, trace, Boolean(torrent.metadata));
+      });
     }
     // Attached ONCE per torrent. WebTorrent answers a duplicate add by handing
     // back the torrent it already has, and this used to run again on it: a
@@ -1569,7 +1597,7 @@ export class TorrentPool {
     // once as a .torrent and once as a magnet is exactly that case, and the
     // roadmap already records it happening. Trace hooks above are installed
     // separately and only for an explicitly traced source.
-    if (this.#swarmTimingByTorrent.has(torrent)) {
+    if (alreadyTracked) {
       return;
     }
     // A torrent nobody has asked for yet does not exist: this is called the
@@ -1590,9 +1618,6 @@ export class TorrentPool {
     // for the whole life of the torrent, which is the same fault as three
     // different hashes with the hash removed.
     const label = () => String(torrent.infoHash ?? "?").slice(0, 8);
-    const addedAt = Date.now();
-    this.#swarmTimingByTorrent.set(torrent, { addedAt, firstPeerAt: null });
-
     torrent.on("download-request-cancelled", ({ piece, offset, length, reason, requestId }) => {
       logger.info(`download request=${requestId ?? `${torrent.infoHash ?? "unknown"}:${piece}:${offset}`} cancel bytes=${length} reason=${reason}`);
     });
@@ -1657,6 +1682,7 @@ export class TorrentPool {
         return;
       }
       timing.firstPeerAt = Date.now();
+      timing.firstPeerAtMonotonic ??= performance.now();
       const waited = secondsToFirstPeer(timing.addedAt, timing.firstPeerAt);
       const byTracker = this.#lastAnnounceByTorrent.get(torrent);
       const offered = bestAnnounce(byTracker ? byTracker.values() : []);

package/services/torrent/worker/trace-swarm-lifecycle.js

@@ -0,0 +1,49 @@
+/** Record first-peer and metadata waits on the torrent worker's monotonic clock. */
+export function beginSwarmLifecycleTrace(timing, trace, metadataAvailable, now = () => performance.now()) {
+  if (timing.firstPeerAtMonotonic !== null) {
+    trace("W3", "event", { outcome: "peer-already-connected" });
+  } else if (timing.peerWaitStartedAt !== null) {
+    trace("W3", "begin", { startedAt: timing.peerWaitStartedAt });
+  }
+
+  if (metadataAvailable) {
+    trace("W4", "event", { outcome: "already-available" });
+  } else if (timing.firstPeerAtMonotonic !== null) {
+    timing.metadataWaitStartedAt = now();
+    trace("W4", "begin", { startedAt: timing.metadataWaitStartedAt });
+  }
+}
+
+export function noteSwarmDiscovery(timing, trace, endedAt) {
+  if (timing.firstPeerAtMonotonic !== null || timing.peerWaitStartedAt !== null) return;
+  timing.peerWaitStartedAt = endedAt;
+  trace("W3", "begin", { startedAt: endedAt });
+}
+
+export function noteSwarmPeer(timing, trace, metadataAvailable, now = () => performance.now()) {
+  if (timing.firstPeerAtMonotonic !== null) return;
+  const endedAt = now();
+  timing.firstPeerAtMonotonic = endedAt;
+  if (timing.peerWaitStartedAt !== null) {
+    trace("W3", "end", { startedAt: timing.peerWaitStartedAt, endedAt,
+      durationMs: endedAt - timing.peerWaitStartedAt, outcome: "peer-connected" });
+  } else {
+    trace("W3", "event", { outcome: "peer-connected-before-trace" });
+  }
+  if (!metadataAvailable) {
+    timing.metadataWaitStartedAt = endedAt;
+    trace("W4", "begin", { startedAt: endedAt });
+  }
+}
+
+export function noteSwarmMetadata(timing, trace, files, now = () => performance.now()) {
+  const endedAt = now();
+  if (timing.metadataWaitStartedAt !== null) {
+    const startedAt = timing.metadataWaitStartedAt;
+    timing.metadataWaitStartedAt = null;
+    trace("W4", "end", { startedAt, endedAt, durationMs: endedAt - startedAt,
+      outcome: "available", files });
+  } else {
+    trace("W4", "event", { outcome: "available", files });
+  }
+}

package/services/torrent/worker/worker.js

@@ -345,8 +345,10 @@ async function runCommand(command, params, id) {
       // Reusing the same promise for a repeated add also collapses two callers
       // racing to open the same torrent into one.
       let pending = torrentsByKey.get(params.sourceKey);
+      let addStartedAt = null;
       if (!pending) {
-        emitWaitTrace(params.sourceKey, "W1", "event", { moment: "add-request" });
+        addStartedAt = performance.now();
+        emitWaitTrace(params.sourceKey, "W1", "begin", { startedAt: addStartedAt, moment: "add-request" });
         pending = pool.getTorrent(params.sourceType, params.source, {
           sourceKey: params.sourceKey, trace: params.trace === true, emitWaitTrace
         });
@@ -366,7 +368,22 @@ async function runCommand(command, params, id) {
       // empty list, and rebuilding it here would bring it back on every stream
       // and stats request, which all come through this command. Any other
       // destroyed torrent is rebuilt, because its files still need it.
-      const added = await pending;
+      let added;
+      try {
+        added = await pending;
+        if (params.trace === true && addStartedAt !== null) {
+          const endedAt = performance.now();
+          emitWaitTrace(params.sourceKey, "W1", "end", { endedAt, durationMs: endedAt - addStartedAt,
+            outcome: "ready" });
+        }
+      } catch (error) {
+        if (params.trace === true && addStartedAt !== null) {
+          const endedAt = performance.now();
+          emitWaitTrace(params.sourceKey, "W1", "end", { endedAt, durationMs: endedAt - addStartedAt,
+            outcome: "error", error: String(error?.message ?? error) });
+        }
+        throw error;
+      }
       const described = isUsableTorrentHandle(added) ? null : wholeSources.describe(params.sourceKey);
       if (described) {
         announceWholeFiles(params.sourceKey, described);
@@ -477,43 +494,50 @@ async function runCommand(command, params, id) {
       const statsStartedAt = performance.now();
       emitWaitTrace(params.sourceKey, "W10", "begin", { startedAt: statsStartedAt,
         fileIndex: params.fileIndex, forecast: params.forecast === true });
-      const torrent = await knownTorrent(params.sourceKey);
-      if (!torrent) {
-        const whole = wholeSources.fileOf(params.sourceKey, params.fileIndex);
-        emitWaitTrace(params.sourceKey, "W10", "end", { startedAt: statsStartedAt,
-          endedAt: performance.now(), outcome: whole ? "whole-file" : "pending", fileIndex: params.fileIndex });
-        return whole ? wholeFileStats(whole.length) : { pending: true };
-      }
-      // What this file's own interruptions demand, measured by the reader in
-      // this thread. It travels with the stats because the caller asking for
-      // them is the one that has to decide with them — the browser's smallest
-      // safe buffer, and the speed a quality step must sustain. Null until a
-      // second interruption has been seen: one wait shows no interval, and an
-      // interval invented from one point is exactly what this work removes.
-      const file = Array.isArray(torrent?.files) ? torrent.files[params.fileIndex] : null;
-      const forecastAt = performance.now();
-      const forecast = file && params.forecast === true ? downloadForecastOf(torrent) : null;
-      const forecastMs = params.forecast === true ? performance.now() - forecastAt : 0;
-      const stats = pool.getFileStats(torrent, params.fileIndex);
-      const ranges = [];
-      if (forecast) for (const [piece, availableAt] of forecast.arrivals) {
-        const start = piece * torrent.pieceLength;
-        const end = Math.min(torrent.length, (piece + 1) * torrent.pieceLength);
-        if (end > start) ranges.push({ start, end, availableAt });
-      }
-      emitWaitTrace(params.sourceKey, "W10", "end", { startedAt: statsStartedAt,
-        endedAt: performance.now(), outcome: "ok", fileIndex: params.fileIndex,
-        forecast: params.forecast === true });
-      return {
-        ...stats,
-        ...(params.forecast === true ? { downloadForecast: {
-          measuredAt: forecast?.measuredAt ?? Date.now(), global: true, ranges
-        } } : {}),
-        supply: supplyFiguresFor(torrent?.infoHash, file?.name, params.segmentSeconds ?? 4),
-        // How long this answer waited for the arrival forecast, which the
-        // caller says beside its own time (ViewerRequests, torrent-tv/meta#178).
-        forecastMs
+      const finishStatsTrace = (outcome, fields = {}) => {
+        const endedAt = performance.now();
+        emitWaitTrace(params.sourceKey, "W10", "end", { startedAt: statsStartedAt, endedAt,
+          durationMs: endedAt - statsStartedAt, outcome, fileIndex: params.fileIndex, ...fields });
       };
+      try {
+        const torrent = await knownTorrent(params.sourceKey);
+        if (!torrent) {
+          const whole = wholeSources.fileOf(params.sourceKey, params.fileIndex);
+          finishStatsTrace(whole ? "whole-file" : "pending");
+          return whole ? wholeFileStats(whole.length) : { pending: true };
+        }
+        // What this file's own interruptions demand, measured by the reader in
+        // this thread. It travels with the stats because the caller asking for
+        // them is the one that has to decide with them — the browser's smallest
+        // safe buffer, and the speed a quality step must sustain. Null until a
+        // second interruption has been seen: one wait shows no interval, and an
+        // interval invented from one point is exactly what this work removes.
+        const file = Array.isArray(torrent?.files) ? torrent.files[params.fileIndex] : null;
+        const forecastAt = performance.now();
+        const forecast = file && params.forecast === true ? downloadForecastOf(torrent) : null;
+        const forecastMs = params.forecast === true ? performance.now() - forecastAt : 0;
+        const stats = pool.getFileStats(torrent, params.fileIndex);
+        const ranges = [];
+        if (forecast) for (const [piece, availableAt] of forecast.arrivals) {
+          const start = piece * torrent.pieceLength;
+          const end = Math.min(torrent.length, (piece + 1) * torrent.pieceLength);
+          if (end > start) ranges.push({ start, end, availableAt });
+        }
+        finishStatsTrace("ok", { forecast: params.forecast === true });
+        return {
+          ...stats,
+          ...(params.forecast === true ? { downloadForecast: {
+            measuredAt: forecast?.measuredAt ?? Date.now(), global: true, ranges
+          } } : {}),
+          supply: supplyFiguresFor(torrent?.infoHash, file?.name, params.segmentSeconds ?? 4),
+          // How long this answer waited for the arrival forecast, which the
+          // caller says beside its own time (ViewerRequests, torrent-tv/meta#178).
+          forecastMs
+        };
+      } catch (error) {
+        finishStatsTrace("error", { error: String(error?.message ?? error) });
+        throw error;
+      }
     }
 
     case Command.PRIORITY_MAP: {
@@ -527,18 +551,27 @@ async function runCommand(command, params, id) {
       // Nor may one for a file held whole, which has nothing left to fetch.
       const torrent = await knownTorrent(params.sourceKey);
       if (!torrent) {
+        emitWaitTrace(params.sourceKey, "W7", "event", { outcome: "source-not-ready", fileIndex: params.fileIndex });
         return { appliedMs: null, receivedAt, repliedAt: performance.timeOrigin + performance.now() };
       }
       // What applying a map costs this thread, told to whoever sent it: every
       // zone becomes a window of the register and the swarm is told again
       // (torrent-tv/meta#166).
       const startedAt = performance.now();
-      emitWaitTrace(params.sourceKey, "W7", "begin", { fileIndex: params.fileIndex });
-      ensureArrivalsWired(params.sourceKey, torrent);
-      pool.applyPriorityMap(torrent, params.fileIndex, zones, params.durationSeconds);
-      torrent.emit("priority-map-changed", params.fileIndex);
-      emitWaitTrace(params.sourceKey, "W7", "end", { startedAt, endedAt: performance.now(),
-        fileIndex: params.fileIndex });
+      emitWaitTrace(params.sourceKey, "W7", "begin", { startedAt, fileIndex: params.fileIndex });
+      try {
+        ensureArrivalsWired(params.sourceKey, torrent);
+        pool.applyPriorityMap(torrent, params.fileIndex, zones, params.durationSeconds);
+        torrent.emit("priority-map-changed", params.fileIndex);
+        const endedAt = performance.now();
+        emitWaitTrace(params.sourceKey, "W7", "end", { startedAt, endedAt, durationMs: endedAt - startedAt,
+          outcome: "applied", fileIndex: params.fileIndex });
+      } catch (error) {
+        const endedAt = performance.now();
+        emitWaitTrace(params.sourceKey, "W7", "end", { startedAt, endedAt, durationMs: endedAt - startedAt,
+          outcome: "error", error: String(error?.message ?? error), fileIndex: params.fileIndex });
+        throw error;
+      }
       return { appliedMs: performance.now() - startedAt, receivedAt, repliedAt: performance.timeOrigin + performance.now() };
     }