@torrent-tv/proxy 2.9.98 → 2.9.99

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.9.99
+
+- **New**: A source can be told to start before anyone asks to play it — `POST /api/sources/:sourceKey/warm`. Everything a cold torrent must do first takes seconds and none of it depends on which file is wanted: announce to the trackers, connect to peers, be unchoked by them. Given a file index it also fetches the two pieces at that file's edges, which is what the codec probe reads and what took **6.7 s of the 10.3 s** before playback in the session measured 2026-08-04. All of it used to begin only once a file had been chosen, because it was buried inside the playback plan. The route returns as soon as the work is under way and reports a refusal rather than an error — nothing is broken if a warm-up does not happen, since the ordinary path still does all of it.
+- **Chore**: Two callers asking for the same file's edges at once now share one prefetch instead of opening a second pair of readers, each claiming a window and holding pieces. That happens by design on a single-video torrent, where the warm-up and the playback plan both want them.
+
 ## 2.9.98
 
 - **Fix**: The upload is no longer raised at moments when nobody wants a byte. A torrent with no reader was counted as starving whenever its download read low — which it always does while the encoder is held back for running ahead of the viewer. Measured: four cycles of 512 KB/s and back in three minutes, each reported as `earn unchoke … down=0KB/s`. Starvation now requires somebody to be waiting.

package/package.json

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

package/routes/api/sources/warm/post.js

@@ -0,0 +1,83 @@
+import { logger } from "../../../../utils/logger.js";
+
+/**
+ * Start fetching a source before anyone asks to play it.
+ *
+ * POST /api/sources/:sourceKey/warm   { fileIndex?: number }
+ *
+ * Everything a torrent must do before the first byte of video can be served
+ * takes seconds and none of it depends on the viewer: announce to the
+ * trackers, connect to peers, be unchoked by them, and fetch the two pieces at
+ * the file's edges that the codec probe reads. Measured 2026-08-04 on a cold
+ * 7.4 GB torrent: 6.7 s of the 10.3 s before playback was those two pieces
+ * arriving, with the swarm ramping from nothing.
+ *
+ * That work used to begin only when a file had been chosen, because it was
+ * buried inside the playback plan. It can begin as soon as the viewer has
+ * picked a TORRENT — while they are still reading the list of episodes — and
+ * then most or all of it has happened by the time they choose.
+ *
+ * Returns as soon as the work is under way. The caller is not waiting for a
+ * result; it is only saying "you may start". Failures are logged and answered
+ * as `started: false` rather than as an error, because nothing is broken if a
+ * warm-up does not happen — the ordinary path still does all of it.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{
+ *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
+ *   torrentPool: import("../../../../services/torrent-pool.js").TorrentPool
+ * }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, torrentPool }) {
+  const sourceKey = typeof req.params.sourceKey === "string" ? req.params.sourceKey.trim() : "";
+  if (!sourceKey) {
+    return reply.code(400).send({ error: "sourceKey is required." });
+  }
+
+  const sourceRecord = sourceRegistry.get(sourceKey);
+  if (!sourceRecord) {
+    return reply.code(404).send({ error: "Source key was not found." });
+  }
+
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  const requestedIndex = Number(body.fileIndex);
+  const fileIndex = Number.isInteger(requestedIndex) && requestedIndex >= 0 ? requestedIndex : null;
+
+  // Adding the torrent is what announces to the trackers and starts connecting
+  // to peers, and it is also what a magnet needs in order to fetch its
+  // metadata. It is awaited because everything else needs the torrent object,
+  // and because until it resolves there is nothing to report.
+  let torrent;
+  try {
+    torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`warm ${sourceKey.slice(0, 8)}: could not add the torrent: ${message}`);
+    return reply.send({ started: false, swarm: false, edges: false });
+  }
+
+  // The edges are only worth fetching once it is known WHICH file will be
+  // played: on a season pack, warming twenty episodes' worth would spend the
+  // pool owner's bandwidth on nineteen files nobody opened. The caller passes
+  // an index when the torrent holds a single video, and again later if it
+  // wants to.
+  let edges = false;
+  if (fileIndex !== null && torrent.files?.[fileIndex]) {
+    edges = true;
+    // Deliberately not awaited: this is the multi-second part, and the point of
+    // the whole route is that the viewer goes on choosing while it happens.
+    Promise.resolve(torrentPool.prefetchFileEdges(torrent, fileIndex)).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`warm ${sourceKey.slice(0, 8)}: file edges failed: ${message}`);
+    });
+  }
+
+  logger.info(
+    `warm ${sourceKey.slice(0, 8)}: swarm started for "${torrent.name}"` +
+      (edges ? `, fetching the edges of file ${fileIndex}` : ", file not chosen yet")
+  );
+
+  return reply.send({ started: true, swarm: true, edges });
+}

package/server.js

@@ -19,6 +19,7 @@ import { handleHealthzGet } from "./routes/healthz/get.js";
 import { handleApiSourcesPost } from "./routes/api/sources/post.js";
 import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
 import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
+import { handleApiSourceWarmPost } from "./routes/api/sources/warm/post.js";
 import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
 import { handleApiSubtitlesGet } from "./routes/api/subtitles/get.js";
 import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/post.js";
@@ -176,6 +177,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   app.get("/api/sources/:sourceKey/files", async (req, reply) =>
     handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool })
   );
+  app.post("/api/sources/:sourceKey/warm", async (req, reply) =>
+    handleApiSourceWarmPost(req, reply, { sourceRegistry, torrentPool })
+  );
   app.post("/api/playback-plan", async (req, reply) =>
     handleApiPlaybackPlanPost(req, reply, { playbackPlanner })
   );

package/services/torrent-pool.js

@@ -383,6 +383,14 @@ export class TorrentPool {
    */
   #readPositionByTorrent = new Map();
 
+  /**
+   * Edge prefetches currently running, keyed by infoHash and file index, so two
+   * callers asking at the same time share one.
+   *
+   * @type {Map<string, Promise<void>>}
+   */
+  #edgePrefetches = new Map();
+
   /** Global disk cap in bytes (0 = disabled). */
   #maxDiskBytes = 0;
 
@@ -1034,6 +1042,37 @@ export class TorrentPool {
     fileIndex,
     { headBytes = 256 * 1024, tailBytes = 2 * 1024 * 1024, timeoutMs = 300_000 } = {}
   ) {
+    if (!torrent || !Array.isArray(torrent.files)) {
+      return;
+    }
+    // Two callers can ask for the same edges at once: the warm-up that starts
+    // when a torrent is picked, and the playback plan a moment later. Reading
+    // the same two pieces twice costs nothing in bandwidth — the torrent
+    // fetches each piece once — but it does open a second pair of readers, each
+    // claiming a window and holding pieces. One is enough.
+    const inFlightKey = `${torrent.infoHash}:${fileIndex}`;
+    const running = this.#edgePrefetches.get(inFlightKey);
+    if (running) {
+      return running;
+    }
+    const prefetch = this.#prefetchFileEdgesOnce(torrent, fileIndex, { headBytes, tailBytes, timeoutMs });
+    this.#edgePrefetches.set(inFlightKey, prefetch);
+    try {
+      return await prefetch;
+    } finally {
+      this.#edgePrefetches.delete(inFlightKey);
+    }
+  }
+
+  /**
+   * The body of {@link prefetchFileEdges}, without the de-duplication.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {number} fileIndex
+   * @param {{ headBytes: number, tailBytes: number, timeoutMs: number }} options
+   * @returns {Promise<void>}
+   */
+  async #prefetchFileEdgesOnce(torrent, fileIndex, { headBytes, tailBytes, timeoutMs }) {
     if (!torrent || !Array.isArray(torrent.files)) {
       return;
     }

package/test/read-window.test.js

@@ -219,7 +219,8 @@ test("criticality marks the window being waited for, not the whole range", async
   try {
     const iterator = readFragments({
       torrent, fileIndex: 0, start: 0, end: 8000 * PIECE - 1,
-      cancellation: { isCancelled: () => false }
+      cancellation: { isCancelled: () => false },
+      windowBytes: WINDOW_PIECES * PIECE
     });
     const pending = iterator.next();
     await new Promise((resolve) => setImmediate(resolve));