@torrent-tv/proxy 2.50.0 → 2.52.0

package/services/torrent-pool.js

@@ -7,6 +7,7 @@
  */
 
 import crypto from "node:crypto";
+import dns from "node:dns/promises";
 import os from "node:os";
 import path from "node:path";
 import { rmSync, statfsSync } from "node:fs";
@@ -14,6 +15,39 @@ import WebTorrent from "webtorrent";
 import { logger } from "../utils/logger.js";
 import { SharedPieceStore, findSharedStore } from "./piece-store/shared-piece-store.js";
 
+// The DHT's entry points. Two of the three the library ships answer nothing —
+// measured 2026-08-21 from the addon host: `router.bittorrent.com` and
+// `router.utorrent.com` did not reply to a hand-written `ping` at all, while a
+// control datagram to a DNS server came back in 20 ms, so the silence is
+// theirs. They stay in the list because they cost nothing and may come back;
+// what the list needed was entries that answer today.
+//
+// The names are RESOLVED HERE, to IPv4, and the addresses are what the library
+// is given. That is the second half of the fault: `dht.transmissionbt.com` is
+// alive — it answered `find_node` with eight nodes — but on a host with global
+// IPv6 its name resolves to an IPv6 address first, and the DHT's socket is
+// IPv4, so by name the one live entry was never reached. Measured the same day:
+// by name, 0 nodes after 21 s, every run; by address, 22 nodes in 5 s.
+//
+// Addresses are not written down. They rot exactly as the old list rotted.
+const DHT_BOOTSTRAP_NAMES = [
+  "dht.transmissionbt.com:6881",
+  "dht.libtorrent.org:25401",
+  "router.bittorrent.com:6881",
+  "router.utorrent.com:6881"
+];
+
+// How long after start a still-empty routing table is worth saying out loud.
+// Bootstrapping takes seconds; a table empty after this is a list that has died
+// and nobody has noticed, which is the state this host was found in.
+const DHT_EMPTY_REPORT_MS = 60 * 1000;
+
+// How long one bootstrap name may take to resolve. This is awaited before the
+// torrent client is built, so it is time during which the thread answers
+// nothing — and the DHT is best-effort, so a name that is slow to resolve is
+// worth less than the delay of waiting for it.
+const DHT_RESOLVE_TIMEOUT_MS = 2000;
+
 // WebTorrent's default download root (see webtorrent lib/torrent.js: TMP =
 // path.join(os.tmpdir(), 'webtorrent')). We use the default store, so all
 // torrent data lives under here.
@@ -100,6 +134,100 @@ const STALL_SPEED_BYTES = 32 * 1024;
 const STALL_REPORT_AFTER_MS = 10_000;
 const STALL_REPORT_INTERVAL_MS = 30_000;
 
+/**
+ * How far this torrent has got towards HAVING a swarm: connected, known, and
+ * waiting to be tried.
+ *
+ * The question a stalled download is asked is "were we offered anybody", and
+ * until 2026-08-21 nothing could answer it. The line printed `peers=` beside
+ * `wires=?`, which read as two quantities of which one was unknown — while in
+ * fact WebTorrent's `numPeers` IS `wires.length` (`lib/torrent.js`, both 2.8.5
+ * and 3.0.21), so the first was the connection count and the second was a
+ * field that has never printed anything. What was missing is the other side:
+ * how many peer addresses the client HOLDS but is not connected to. A tracker
+ * answering `seeders=5` while `connected=0, known=0` is a different fault from
+ * `connected=0, known=5`, and only the second is about connecting.
+ *
+ * `_peersLength` and `_numQueued` are WebTorrent internals, not its published
+ * interface — a cached counter and a getter in 2.8.5, both getters in 3.0.21,
+ * read the same way in each. Read defensively on purpose: if a later version
+ * drops them the field says nothing rather than breaking a poll the browser
+ * makes every two seconds.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {{ connectedPeers: number, knownPeers: number | null, queuedPeers: number | null }}
+ */
+export function describeSwarmReach(torrent) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires.length : 0;
+  const read = (value) => (typeof value === "number" && Number.isFinite(value) ? value : null);
+  let knownPeers = null;
+  let queuedPeers = null;
+  try {
+    knownPeers = read(torrent?._peersLength);
+    queuedPeers = read(torrent?._numQueued);
+  } catch {
+    // silent-ok: these are internals behind getters that can throw on a
+    // destroyed torrent, and the reading is a diagnostic. Nothing here is
+    // worth failing a stats poll for.
+  }
+  return { connectedPeers: wires, knownPeers, queuedPeers };
+}
+
+/**
+ * How long a torrent waited for its first connected peer.
+ *
+ * The whole of a cold start can be this one number and nothing else: measured
+ * 2026-08-21, a tracker answered `seeders=5` at 13:40:30 and the first wire
+ * arrived at 13:44:47 — 257 s during which the stats line repeated, unchanged,
+ * every two seconds. Once the peer connected the file's edges arrived at
+ * 6.8 MB/s and the plan finished in three seconds. It was never measured,
+ * never named, and the viewer saw it as an unexplained wait.
+ *
+ * @param {number} addedAtMs
+ * @param {number} firstPeerAtMs
+ * @returns {number | null} Seconds, or null while there is still no peer or
+ *   the two moments cannot be compared.
+ */
+export function secondsToFirstPeer(addedAtMs, firstPeerAtMs) {
+  if (!Number.isFinite(addedAtMs) || !Number.isFinite(firstPeerAtMs)) {
+    return null;
+  }
+  const seconds = (firstPeerAtMs - addedAtMs) / 1000;
+  return seconds >= 0 ? Number(seconds.toFixed(3)) : null;
+}
+
+/**
+ * The best answer any tracker has given, out of the answers they have given.
+ *
+ * A torrent announces to every tracker it lists and each answers separately,
+ * so keeping "the last one" makes the reading depend on which tracker replied
+ * most recently. A live tracker saying `complete=500` followed two seconds
+ * later by a dead one saying `complete=0` would print "nobody offered" — and
+ * telling that from "several offered and we reached none" is the entire reason
+ * this figure is carried. The best answer is the honest one: a swarm has as
+ * many seeders as the most informed tracker knows about.
+ *
+ * @param {Iterable<{ seeders: number | null, leechers: number | null }>} answers
+ * @returns {{ seeders: number | null, leechers: number | null, trackers: number }}
+ */
+export function bestAnnounce(answers) {
+  let seeders = null;
+  let leechers = null;
+  let trackers = 0;
+  for (const answer of answers ?? []) {
+    trackers += 1;
+    if (typeof answer?.seeders === "number" && (seeders === null || answer.seeders > seeders)) {
+      seeders = answer.seeders;
+      // Taken from the SAME answer, including when that answer gave no leecher
+      // count. Carrying the previous tracker's figure forward would pair one
+      // tracker's seeders with another's leechers and present the pair as one
+      // reading.
+      leechers = typeof answer.leechers === "number" ? answer.leechers : null;
+    }
+  }
+  return { seeders, leechers, trackers };
+}
+
 /**
  * What the swarm has been asked for, and what it is doing about it.
  *
@@ -449,6 +577,103 @@ function isMagnetSource(torrentId) {
   return typeof torrentId === "string" && /^magnet:\?/i.test(torrentId.trim());
 }
 
+/**
+ * Split a `host` or `host:port` bootstrap entry.
+ *
+ * @param {unknown} entry
+ * @returns {{ host: string, port: number } | null} Null for anything that is
+ *   not a usable entry, so a typo drops one node instead of failing the client.
+ */
+export function parseBootstrapEntry(entry) {
+  if (typeof entry !== "string") {
+    return null;
+  }
+  const trimmed = entry.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  const colon = trimmed.lastIndexOf(":");
+  if (colon < 0) {
+    return { host: trimmed, port: 6881 };
+  }
+  const host = trimmed.slice(0, colon);
+  const port = Number(trimmed.slice(colon + 1));
+  if (host.length === 0 || !Number.isInteger(port) || port <= 0 || port > 65535) {
+    return null;
+  }
+  return { host, port };
+}
+
+/**
+ * Turn bootstrap names into `address:port` entries, keeping only IPv4.
+ *
+ * Why the resolution happens here rather than being left to the library: the
+ * DHT's socket is IPv4, and a name that resolves to IPv6 first is silently
+ * unreachable through it — which is how a live bootstrap node came to look
+ * dead on this host. See {@link DHT_BOOTSTRAP_NAMES}.
+ *
+ * Best-effort by construction. A name that does not resolve is dropped and
+ * said; if none resolve the caller gets an empty list and the library keeps its
+ * own defaults, which is no worse than before.
+ *
+ * @param {string[]} [names]
+ * @param {number} [timeoutMs] - How long one name may take before it is
+ *   treated as unresolvable.
+ * @returns {Promise<string[]>}
+ */
+export async function resolveDhtBootstrap(names = DHT_BOOTSTRAP_NAMES, timeoutMs = DHT_RESOLVE_TIMEOUT_MS) {
+  const entries = names.map(parseBootstrapEntry).filter((entry) => entry !== null);
+  const resolved = [];
+  const failed = [];
+  await Promise.all(
+    entries.map(async ({ host, port }) => {
+      try {
+        // Capped, because this is awaited before the torrent client exists and
+        // therefore before this thread will answer anything. `dns.resolve4`
+        // talks to the host's resolver with c-ares' own defaults — about five
+        // seconds times four tries — so a black-holing resolver would hold the
+        // whole worker for twenty seconds with nothing said. A name that does
+        // not answer inside the cap is treated exactly like one that fails:
+        // dropped, named, and the rest of the list stands.
+        const addresses = await Promise.race([
+          dns.resolve4(host),
+          new Promise((_resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("timed out")), timeoutMs);
+            timer.unref?.();
+          })
+        ]);
+        for (const address of addresses) {
+          resolved.push(`${address}:${port}`);
+        }
+      } catch {
+        failed.push(`${host}:${port}`);
+      }
+    })
+  );
+  if (failed.length > 0) {
+    logger.warn(`torrent-pool: DHT bootstrap names that do not resolve to IPv4: ${failed.join(", ")}`);
+  }
+  return resolved;
+}
+
+/**
+ * How many nodes the client's DHT knows, or null when it has no DHT at all.
+ *
+ * @param {{ dht?: { nodes?: { toArray?: () => unknown[] } } }} client
+ * @returns {number | null}
+ */
+export function dhtNodeCount(client) {
+  const nodes = client?.dht?.nodes;
+  if (!nodes || typeof nodes.toArray !== "function") {
+    return null;
+  }
+  try {
+    return nodes.toArray().length;
+  } catch {
+    return null;
+  }
+}
+
 export class TorrentPool {
   /**
    * In-flight `client.add()` promises keyed by the same key as `torrents`.
@@ -521,13 +746,36 @@ export class TorrentPool {
   /** Periodic adaptive-upload adjustment timer. */
   #uploadAdjustTimer = null;
 
+  /** One-shot timer that reports the size of the DHT's routing table. */
+  #dhtReportTimer = null;
+
+  /**
+   * The last announce answer per torrent — what the TRACKER says the swarm
+   * holds, as opposed to what we have managed to connect to. Kept because the
+   * two disagreeing is the whole diagnosis: five seeders offered and none
+   * connected is a connectivity fault, and nobody offered is a supply fault.
+   *
+   * Kept PER TRACKER, because each answers for itself and the most recent
+   * answer is not the most informed one.
+   *
+   * @type {WeakMap<import("webtorrent").Torrent, Map<string, { seeders: number | null, leechers: number | null, at: number }>>}
+   */
+  #lastAnnounceByTorrent = new WeakMap();
+
+  /**
+   * When each torrent was added, and when its first peer connected.
+   *
+   * @type {WeakMap<import("webtorrent").Torrent, { addedAt: number, firstPeerAt: number | null }>}
+   */
+  #swarmTimingByTorrent = new WeakMap();
+
   /**
    * @param {{ maxDiskBytes?: number }} [options]
    *   `maxDiskBytes` caps total downloaded torrent data; when omitted a
    *   default is computed from free disk (min(10 GB, half free)). Pass 0 to
    *   disable the cap.
    */
-  constructor({ maxDiskBytes, memoryBytes } = {}) {
+  constructor({ maxDiskBytes, memoryBytes, dhtBootstrap } = {}) {
     this.#memoryBytes = Number.isFinite(memoryBytes) && memoryBytes > 0 ? memoryBytes : undefined;
 
     // Sweep orphaned torrent data left by a previous hard kill (no graceful
@@ -541,8 +789,33 @@ export class TorrentPool {
       logger.warn(`torrent-pool: could not sweep orphaned store at startup: ${message}`);
     }
 
+    const bootstrap = Array.isArray(dhtBootstrap) ? dhtBootstrap.filter(Boolean) : [];
+    if (bootstrap.length > 0) {
+      logger.info(`torrent-pool: DHT bootstrap nodes: ${bootstrap.join(", ")}`);
+    } else {
+      logger.warn("torrent-pool: no DHT bootstrap nodes resolved; the library's own list is all there is");
+    }
     /** @type {import("webtorrent").WebTorrent} */
-    this.client = new WebTorrent();
+    this.client = new WebTorrent(bootstrap.length > 0 ? { dht: { bootstrap } } : undefined);
+    // A bootstrap list rots, and it rots silently: the one the library ships
+    // had two dead entries and a third that could not be reached by name, and
+    // nothing said so for as long as that was true. Say it once, late enough
+    // that a slow bootstrap is not mistaken for a dead one.
+    this.#dhtReportTimer = setTimeout(() => {
+      const nodes = dhtNodeCount(this.client);
+      if (nodes === null) {
+        return;
+      }
+      if (nodes === 0) {
+        logger.warn(
+          "torrent-pool: the DHT knows no nodes a minute after start — its bootstrap list is not " +
+          "answering, so a torrent has only its trackers to find peers with"
+        );
+        return;
+      }
+      logger.info(`torrent-pool: the DHT knows ${nodes} nodes`);
+    }, DHT_EMPTY_REPORT_MS);
+    this.#dhtReportTimer.unref?.();
 
     /**
      * Active torrents keyed by `"${sourceType}:${sha1(source)}"`.
@@ -616,7 +889,10 @@ export class TorrentPool {
     }
     torrent.hurryUntil = until;
     logger.info(
-      `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] uploading generously for ` +
+      // `?? "?"` because one caller is the moment of adding, and `client.add`
+      // returns before the torrent id has been parsed — without it the line
+      // printed the first eight characters of the word "undefined".
+      `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] uploading generously for ` +
         `${Math.round(UPLOAD_HURRY_MS / 1000)}s — ${why}`
     );
     this.#adjustUploadLimit();
@@ -924,24 +1200,102 @@ export class TorrentPool {
    * warnings (tracker rejections/errors surface here). Without these a
    * zero-peer torrent gives no clue WHY it has no peers.
    *
-   * @param {string} label - Short source label for log lines.
    * @param {import("webtorrent").Torrent} torrent
    * @returns {void}
    */
-  #attachSwarmDiagnostics(label, torrent) {
+  #attachSwarmDiagnostics(torrent) {
+    // 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
+    // torrent with twelve connections and a first peer five minutes old had its
+    // timing record reset, so it began reporting "no peer yet" and the next
+    // connection printed "first peer connected after 0.3s" — a false statement
+    // about a swarm that had been healthy for minutes. The same film opened
+    // once as a .torrent and once as a magnet is exactly that case, and the
+    // roadmap already records it happening.
+    if (this.#swarmTimingByTorrent.has(torrent)) {
+      return;
+    }
     // A torrent nobody has asked for yet does not exist: this is called the
     // moment one is added, which is the moment a viewer started waiting.
     this.#markHurry(torrent, "just added");
-    const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
-    logger.info(
-      `torrent-pool: [${label}] added: files=${torrent.files?.length ?? 0} ` +
-        `private=${torrent.private ? "yes" : "no"} trackers=${trackerCount}`
-    );
+    // ONE name for a torrent, and it is the infohash. These lines used to be
+    // labelled with the first eight characters of a sha1 of the SOURCE BYTES,
+    // while the neighbouring lines used the infohash and the stats line used
+    // the registry's own key — three different hashes of one film, in the same
+    // second, none of them matching. Correlating a swarm across three lines
+    // cost a guess every time. The infohash is the one identifier every side
+    // of this system already shares.
+    //
+    // Read at the moment of PRINTING, not now. `client.add` returns before the
+    // torrent id has been parsed — measured against the vendored 2.8.5, both a
+    // magnet and a .torrent buffer have `infoHash === undefined` on the line
+    // after `add` returns — so a label captured here would be the string "?"
+    // 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 });
+
+    // The first connected peer, said once, because the wait for it can BE the
+    // whole cold start and nothing else measures it.
+    torrent.on("wire", () => {
+      const timing = this.#swarmTimingByTorrent.get(torrent);
+      if (!timing || timing.firstPeerAt !== null) {
+        return;
+      }
+      timing.firstPeerAt = Date.now();
+      const waited = secondsToFirstPeer(timing.addedAt, timing.firstPeerAt);
+      const byTracker = this.#lastAnnounceByTorrent.get(torrent);
+      const offered = bestAnnounce(byTracker ? byTracker.values() : []);
+      logger.info(
+        `torrent-pool: [${label()}] first peer connected after ${waited === null ? "?" : waited.toFixed(1)}s` +
+          (offered.trackers > 0
+            ? ` (${offered.trackers} tracker(s) had answered, best seeders=${offered.seeders ?? "?"} ` +
+              `leechers=${offered.leechers ?? "?"})`
+            : " (no tracker answer had arrived)")
+      );
+    });
 
     torrent.on("warning", (warning) => {
-      logger.warn(`torrent-pool: [${label}] warning: ${formatWarning(warning)}`);
+      logger.warn(`torrent-pool: [${label()}] warning: ${formatWarning(warning)}`);
     });
 
+    // Everything below needs the torrent to have been PARSED, and `add` returns
+    // before that: `announce`, `files` and `private` are all still empty, and
+    // `discovery` — which owns the tracker client — is not created until
+    // `_startDiscovery`, which runs immediately before `ready` is emitted.
+    // Attaching the tracker listener at add-time therefore attaches it to
+    // nothing at all, and every announce answer is lost. The two listeners
+    // above stay where they are, because `wire` and `warning` live on the
+    // torrent from construction and both fire before `ready`: the peer that
+    // DELIVERS a magnet's metadata connects first, and `wire` is emitted on
+    // connection and never replayed.
+    const describeOnce = () => {
+      const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
+      logger.info(
+        `torrent-pool: [${label()}] added: files=${torrent.files?.length ?? 0} ` +
+          `private=${torrent.private ? "yes" : "no"} trackers=${trackerCount}`
+      );
+      this.#attachTrackerDiagnostics(torrent, label);
+    };
+    if (torrent.ready === true) {
+      describeOnce();
+    } else {
+      torrent.once("ready", describeOnce);
+    }
+  }
+
+  /**
+   * Watch what the trackers answer.
+   *
+   * Separated from the rest because it can only be done once the torrent has
+   * been parsed — see the reasoning at the call site.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {() => string} label
+   * @returns {void}
+   */
+  #attachTrackerDiagnostics(torrent, label) {
     // bittorrent-tracker's Client emits "update" with each announce response.
     // `complete`/`incomplete` are the tracker's seeder/leecher counts — the
     // authoritative answer to "does the tracker accept us and does the swarm
@@ -953,13 +1307,25 @@ export class TorrentPool {
         // strip the query string before logging.
         const announceUrl =
           typeof data?.announce === "string" ? data.announce.replace(/\?.*$/, "") : "?";
+        const seeders = typeof data?.complete === "number" ? data.complete : null;
+        const leechers = typeof data?.incomplete === "number" ? data.incomplete : null;
+        // Kept, not only printed: what the tracker says the swarm holds is one
+        // half of every later question about why nothing is arriving, and a
+        // number that exists only in a log line cannot be put beside the other
+        // half two minutes later.
+        let byTracker = this.#lastAnnounceByTorrent.get(torrent);
+        if (!byTracker) {
+          byTracker = new Map();
+          this.#lastAnnounceByTorrent.set(torrent, byTracker);
+        }
+        byTracker.set(announceUrl, { seeders, leechers, at: Date.now() });
         logger.info(
-          `torrent-pool: [${label}] announce ${announceUrl}: ` +
-            `seeders=${data?.complete ?? "?"} leechers=${data?.incomplete ?? "?"}`
+          `torrent-pool: [${label()}] announce ${announceUrl}: ` +
+            `seeders=${seeders ?? "?"} leechers=${leechers ?? "?"}`
         );
       });
     } else {
-      logger.info(`torrent-pool: [${label}] tracker client not exposed; announce results not logged`);
+      logger.info(`torrent-pool: [${label()}] tracker client not exposed; announce results not logged`);
     }
   }
 
@@ -1060,17 +1426,18 @@ export class TorrentPool {
               this.#lastAccess.delete(existing);
               this.#readPositionByTorrent.delete(existing);
               this.client.remove(existing, { destroyStore: true }, () => {
-                this.client.add(torrentId, {
+                const addedReplacement = this.client.add(torrentId, {
                   store: SharedPieceStore,
                   storeCacheSlots: 0,
                   storeOpts: { memoryBytes: this.#memoryBytes }
                 }, (replacement) => {
                   this.torrents.set(key, replacement);
                   this.#lastAccess.set(replacement, Date.now());
-                  this.#attachSwarmDiagnostics(dupMatch[1].slice(0, 8), replacement);
                   this.#pending.delete(key);
+                  this.#attachSwarmDiagnostics(replacement);
                   resolve(replacement);
                 });
+                this.#attachSwarmDiagnostics(addedReplacement);
               });
               return;
             }
@@ -1091,7 +1458,7 @@ export class TorrentPool {
       // piece across threads detached memory still in use. Ours owns what it
       // hands out, holds pieces in shared memory the main thread can read
       // directly, and spills to disk instead of losing them.
-      this.client.add(torrentId, {
+      const added = this.client.add(torrentId, {
         store: SharedPieceStore,
         storeCacheSlots: 0,
         storeOpts: { memoryBytes: this.#memoryBytes }
@@ -1100,11 +1467,23 @@ export class TorrentPool {
         this.torrents.set(key, readyTorrent);
         this.#lastAccess.set(readyTorrent, Date.now());
         this.#pending.delete(key);
-        // Key layout is `${sourceType}:${sha1}`; log with the sha1 prefix so
-        // lines correlate with the [stats] source key.
-        this.#attachSwarmDiagnostics(key.split(":")[1]?.slice(0, 8) ?? key, readyTorrent);
+        // The torrent this call ends up with is not always the one it added:
+        // on a duplicate infohash WebTorrent destroys the new one and hands
+        // back the one it already had. Watching only what `add` returned would
+        // leave the survivor unwatched. Attaching twice costs nothing — the
+        // guard makes the second call a no-op when it is the same object.
+        this.#attachSwarmDiagnostics(readyTorrent);
         resolve(readyTorrent);
       });
+      // Attached to what `add` returns, NOT inside its callback. That callback
+      // is `torrent.once("ready")`, and for a magnet everything this watches
+      // has already happened by then: peer discovery starts before the metadata
+      // arrives, so the tracker's answers land before any listener exists, and
+      // the peer that DELIVERED the metadata connected before `ready` fired —
+      // `wire` is emitted at the moment of connection and never replayed. The
+      // torrent that waited minutes for its first peer would have been the one
+      // case this could not measure.
+      this.#attachSwarmDiagnostics(added);
     });
 
     this.#pending.set(key, promise);
@@ -1280,7 +1659,15 @@ export class TorrentPool {
    *   uploadSpeed: number,
    *   fileProgress: number | null,
    *   fileDownloaded: number | null,
-   *   fileLength: number | null
+   *   fileLength: number | null,
+   *   connectedPeers: number,
+   *   knownPeers: number | null,
+   *   queuedPeers: number | null,
+   *   trackerSeeders: number | null,
+   *   trackerLeechers: number | null,
+   *   trackersAnswered: number,
+   *   secondsToFirstPeer: number | null,
+   *   secondsWaitingForFirstPeer: number | null
    * }}
    */
   getFileStats(torrent, fileIndex = null, options = {}) {
@@ -1288,7 +1675,34 @@ export class TorrentPool {
     const downloadSpeed = typeof torrent?.downloadSpeed === "number" ? torrent.downloadSpeed : 0;
     const uploadSpeed = typeof torrent?.uploadSpeed === "number" ? torrent.uploadSpeed : 0;
 
-    const base = { numPeers, downloadSpeed, uploadSpeed };
+    // Everything the caller needs to tell "nobody was offered" from "several
+    // were offered and we connected to none". All of it is read HERE, on the
+    // thread that owns the torrent: the handle the routes hold is a proxy
+    // across a worker boundary, where `torrent.wires` simply does not exist —
+    // which is why the line that tried to print it printed a question mark in
+    // every line it has ever written.
+    const reach = describeSwarmReach(torrent);
+    const byTracker = this.#lastAnnounceByTorrent.get(torrent);
+    const announce = bestAnnounce(byTracker ? byTracker.values() : []);
+    const timing = this.#swarmTimingByTorrent.get(torrent) ?? null;
+
+    const base = {
+      numPeers,
+      downloadSpeed,
+      uploadSpeed,
+      connectedPeers: reach.connectedPeers,
+      knownPeers: reach.knownPeers,
+      queuedPeers: reach.queuedPeers,
+      trackerSeeders: announce.seeders,
+      trackerLeechers: announce.leechers,
+      trackersAnswered: announce.trackers,
+      secondsToFirstPeer: timing ? secondsToFirstPeer(timing.addedAt, timing.firstPeerAt) : null,
+      // How long this torrent has been waiting, when it is still waiting. The
+      // figure above answers "how long did it take"; this one answers "how long
+      // has it been", which is the question during the wait itself.
+      secondsWaitingForFirstPeer:
+        timing && timing.firstPeerAt === null ? secondsToFirstPeer(timing.addedAt, Date.now()) : null
+    };
 
     if (fileIndex === null || !Number.isInteger(fileIndex) || !Array.isArray(torrent?.files)) {
       return { ...base, fileProgress: null, fileDownloaded: null, fileLength: null };
@@ -1681,6 +2095,10 @@ export class TorrentPool {
       clearInterval(this.#uploadAdjustTimer);
       this.#uploadAdjustTimer = null;
     }
+    if (this.#dhtReportTimer) {
+      clearTimeout(this.#dhtReportTimer);
+      this.#dhtReportTimer = null;
+    }
     // Cancel any pending idle-removal timers — destroyAll handles teardown.
     for (const timer of this.#idleTimers.values()) {
       clearTimeout(timer);

package/services/torrent-worker/worker.js

@@ -35,12 +35,19 @@ import { Command, Event } from "./protocol.js";
 // would drag in WebTorrent — and with it the real `webrtc-polyfill` — before
 // the hook above had a chance to register. Verified the hard way: with a static
 // import the process still aborted, and the stack named the genuine polyfill.
-const { TorrentPool } = await import("../torrent-pool.js");
+const { TorrentPool, resolveDhtBootstrap } = await import("../torrent-pool.js");
 const { collectStoreStats, findSharedStore } = await import("../piece-store/shared-piece-store.js");
 
+// Resolved before the client exists, because the client builds its DHT in its
+// own constructor and the addresses have to be in hand by then. Awaiting here
+// costs the few milliseconds of a DNS answer, once, on a thread that has not
+// been asked for anything yet.
+const dhtBootstrap = await resolveDhtBootstrap();
+
 const pool = new TorrentPool({
   maxDiskBytes: workerData?.maxDiskBytes,
-  memoryBytes: workerData?.memoryBytes
+  memoryBytes: workerData?.memoryBytes,
+  dhtBootstrap
 });
 
 /** Torrents by sourceKey — the main thread names them, this thread owns them. */