@torrent-tv/proxy 2.90.0 → 2.92.0

package/bin/cli.js

@@ -442,10 +442,11 @@ try {
     // in and at the same instant as them.
     readExtra: () => {
       const fragments = fragmentBufferCollection();
-      return fragments.seen === 0
+      const pieces = fragments.seen === 0
         ? ""
         : `piece buffers handed here ${fragments.seen} seen, ${fragments.collected} collected, ` +
           `${fragments.seen - fragments.collected} still alive`;
+      return [pieces, `binary packet indexes ${started.mediaMemory.packetIndexBytes()} bytes`].filter(Boolean).join("; ");
     },
     // Once a minute cannot see what kills this process. Both out-of-memory
     // kills of 2026-09-02 happened inside a single gap of the old cadence: the
@@ -559,6 +560,8 @@ try {
     proxyId: clientId,
     token,
     proxyPort: actualPort,
+    name: clientName,
+    baseUrl: directBaseUrl,
     onSignal(sessionId, signal) {
       webRtcManager?.handleSignal(sessionId, signal);
     },
@@ -639,7 +642,7 @@ try {
     // reason as the transport snapshot above: the manager is built inside
     // `startProxyServer`, with this handler already in hand.
     onViewerPresent: (consumerId) => {
-      started?.outputParts?.viewers?.seen?.(consumerId);
+      started?.outputParts?.viewers?.present?.(consumerId);
     },
     onViewerGone: (consumerId, because) => {
       void started?.outputParts?.lifecycle?.viewerHasGone?.(consumerId, because)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.90.0",
+  "version": "2.92.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -29,13 +29,14 @@
   "scripts": {
     "start": "node ./bin/cli.js",
     "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
-    "test": "npm run lint && node --test",
+    "test": "npm run lint && node --require ./test/no-torrent/support/refuse-torrent.cjs --test \"test/no-torrent/**/*.test.js\"",
     "graph": "node scripts/render-run-graph.js",
     "lint": "biome lint ."
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
+    "@ffprobe-installer/ffprobe": "^2.1.2",
     "@silentbot1/nat-api": "^0.4.9",
     "chalk": "^5.4.1",
     "commander": "^12.1.0",
@@ -46,6 +47,7 @@
     "node-datachannel": "^0.32.0",
     "parse-torrent": "^11.0.23",
     "uint8-util": "2.2.6",
+    "undici": "^7.30.0",
     "webtorrent": "2.8.5",
     "werift": "^0.24.2",
     "ws": "^8.18.2"
@@ -53,6 +55,20 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.7"
   },
+  "allowScripts": {
+    "@ffprobe-installer/darwin-arm64@5.0.1": true,
+    "@ffprobe-installer/darwin-x64@5.1.0": true,
+    "@ffprobe-installer/linux-arm@5.2.0": true,
+    "@ffprobe-installer/linux-arm64@5.2.0": true,
+    "@ffprobe-installer/linux-ia32@5.2.0": true,
+    "@ffprobe-installer/linux-x64@5.2.0": true,
+    "@torrent-tv/utp-native@2.5.3-ttv.9": true,
+    "bufferutil@4.1.0": true,
+    "ffmpeg-static@5.3.0": true,
+    "node-datachannel@0.32.3": true,
+    "utf-8-validate@6.0.6": true,
+    "ip-set": false
+  },
   "overrides": {
     "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.9"
   }

package/routes/api/playback-plan/post.js

@@ -24,23 +24,37 @@ function getPayload(body) {
   return {};
 }
 
-export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner, sourceRegistry, torrentPool, ffmpegBin, localBaseUrl }) {
+export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner, sourceRegistry, torrentPool, ffmpegBin, localBaseUrl, viewers }) {
   const payload = getPayload(req.body);
   const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
   const fileIndex = Number(payload.fileIndex);
   const userAgent = typeof payload.userAgent === "string" ? payload.userAgent : "";
 
-  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+  if (!sourceKey || !Number.isSafeInteger(fileIndex) || fileIndex < 0) {
     return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
   }
+  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
+  const selection = {};
+  if (typeof payload.positionSeconds === "number" && Number.isFinite(payload.positionSeconds) && payload.positionSeconds >= 0) selection.positionSeconds = payload.positionSeconds;
+  if (typeof payload.wantsToPlay === "boolean") selection.wantsToPlay = payload.wantsToPlay;
+  if (consumerId) viewers?.selectsFile(consumerId, sourceKey, fileIndex, Date.now(), selection);
 
   // Interface delegates to PlaybackController (orchestrator + domain). Keeps route thin.
   const { PlaybackController } = await import("../../../services/server/controllers/PlaybackController.js");
   const controller = new PlaybackController({ torrentPool, sourceRegistry, ffmpegBin, localBaseUrl, playbackPlanner });
+  const cancellation = new AbortController();
+  const aborted = () => cancellation.abort();
+  const closed = () => { if (!reply.raw?.writableEnded) aborted(); };
+  req.raw?.once?.("aborted", aborted);
+  reply.raw?.once?.("close", closed);
+  if (req.raw?.aborted) aborted();
   try {
-    const plan = await controller.getPlan({ sourceKey, fileIndex, userAgent, maxWaitMs: 8_000 });
+    const params = { sourceKey, fileIndex, userAgent };
+    const plan = payload.waitForReady === true
+      ? await controller.getReadyPlan(params, { signal: cancellation.signal }) : await controller.getPlan(params);
     return reply.send(plan);
   } catch (error) {
+    if (cancellation.signal.aborted) return;
     if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {
       return reply.code(404).send({ error: error.message });
     }
@@ -48,6 +62,9 @@ export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner, s
       return reply.code(404).send({ error: error.message });
     }
     const message = error instanceof Error ? error.message : String(error);
-    return reply.code(500).send({ error: `Failed to prepare playback plan: ${message}` });
+    return reply.code(500).send({ error: `Failed to prepare playback plan: ${message}`, code: error?.code, canRetry: error?.canRetry !== false });
+  } finally {
+    req.raw?.removeListener?.("aborted", aborted);
+    reply.raw?.removeListener?.("close", closed);
   }
 }

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

@@ -1,4 +1,5 @@
 import { contentsOf } from "../../../../services/torrent/Contents.js";
+import { logger } from "../../../../utils/logger.js";
 
 /**
  * List the files of a registered source (torrent file OR magnet).
@@ -7,13 +8,8 @@ import { contentsOf } from "../../../../services/torrent/Contents.js";
  *
  * The browser parses `.torrent` files locally, but a magnet URI carries no
  * file list — the metadata comes from the swarm and can take a while to
- * arrive on a cold magnet. Rather than block the request until it does (a
- * single long request racing the transport timeout, which surfaced as a
- * premature "no peers" error while the metadata was in fact still arriving),
- * this waits only a short per-request budget: if the metadata is not ready it
- * returns `{ pending: true }` while the fetch continues in the background. The
- * caller polls again until the file list comes back — mirroring the cold-
- * torrent playback-plan poll.
+ * arrive on a cold magnet. Metadata readiness, failure or caller cancellation
+ * ends the request; elapsed time does not change the answer about a torrent.
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
@@ -24,10 +20,9 @@ import { contentsOf } from "../../../../services/torrent/Contents.js";
  * @returns {Promise<void>}
  */
 
-/** Sentinel resolved when the per-request wait elapses before metadata. */
-const PENDING = Symbol("pending");
+const CANCELLED = Symbol("cancelled");
 
-export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool }) {
+export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers }) {
   const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
     return reply.code(400).send({ error: "sourceKey is required." });
@@ -37,20 +32,13 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
     return reply.code(404).send({ error: "Source key was not found." });
   }
 
-  // How long to wait within THIS request before returning `pending`. Well
-  // under the transport's request timeout so a single poll never races it.
-  const rawWait = Number(req.query?.maxWaitMs);
-  const maxWaitMs = Number.isFinite(rawWait) && rawWait > 0 ? Math.min(rawWait, 20_000) : 8_000;
-
-  // getTorrent dedupes concurrent/repeated calls via the pool's in-flight map,
-  // so polling keeps joining the same background fetch (metadata keeps
-  // downloading between polls). Race it against the wait budget; if the wait
-  // wins, the fetch is left running for the next poll to observe.
-  let timer;
-  const waitPromise = new Promise((resolve) => {
-    timer = setTimeout(() => resolve(PENDING), maxWaitMs);
-    timer.unref?.();
-  });
+  let cancelled;
+  const waitPromise = new Promise(resolve => { cancelled = () => resolve(CANCELLED); });
+  reply.raw?.once?.("close", cancelled);
+  if (reply.raw?.destroyed) {
+    reply.raw?.removeListener?.("close", cancelled);
+    return;
+  }
   const torrentPromise = torrentPool
     .getTorrent(sourceRecord.sourceType, sourceRecord.source)
     // Swallow so a rejection that loses the race is not an unhandled rejection;
@@ -61,12 +49,10 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
   try {
     result = await Promise.race([torrentPromise, waitPromise]);
   } finally {
-    clearTimeout(timer);
+    reply.raw?.removeListener?.("close", cancelled);
   }
 
-  if (result === PENDING) {
-    return reply.send({ pending: true });
-  }
+  if (result === CANCELLED) return;
   if (result instanceof Error) {
     return reply.code(502).send({ error: `Could not load torrent metadata: ${result.message}` });
   }
@@ -80,6 +66,12 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
   // only video present). It ships the paths already relative to the torrent
   // root, so there is no stripping rule on the other side either.
   const contents = contentsOf(torrent);
+  for (const file of contents.files()) {
+    if (file.excludedReason) logger.info(`contents request=${req.id ?? "unstated"} source=${sourceKey} ` +
+      `file=${file.fileIndex} name=${JSON.stringify(file.relativePath)} bytes=${file.length} excluded=${file.excludedReason}`);
+  }
+  const consumerId = typeof req.query?.consumerId === "string" ? req.query.consumerId.trim() : "";
+  if (consumerId) viewers?.visibleFiles(consumerId, sourceKey, contents.items.map(item => item.fileIndex));
   return reply.send({
     name: torrent.name ?? "",
     infoHash: torrent.infoHash ?? "",

package/routes/api/sources/post.js

@@ -23,7 +23,7 @@ function getPayload(body) {
   return {};
 }
 
-export async function handleApiSourcesPost(req, reply, { sourceRegistry }) {
+export async function handleApiSourcesPost(req, reply, { sourceRegistry, viewers }) {
   const payload = getPayload(req.body);
   const sourceType = typeof payload.sourceType === "string" ? payload.sourceType : "";
   const source = typeof payload.source === "string" ? payload.source : "";
@@ -32,5 +32,7 @@ export async function handleApiSourcesPost(req, reply, { sourceRegistry }) {
   }
 
   const sourceKey = await sourceRegistry.upsert(sourceType, source);
-  return reply.send({ sourceKey });
+  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
+  if (consumerId) viewers?.selectsSource(consumerId, sourceKey);
+  return reply.send({ sourceKey, playbackMapVersion: 1 });
 }

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

@@ -30,32 +30,25 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
 
   let torrent;
   try {
-    // getTorrent resolves immediately when the torrent is already loaded.
-    torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+    torrent = torrentPool.knownTorrent(sourceKey);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     logger.warn(`stats: getTorrent failed for ${sourceKey.slice(0, 8)}: ${message} stack=${error instanceof Error ? error.stack?.split("\n")[1]?.trim() ?? "" : ""}`);
     return reply.code(500).send({ error: `Failed to load torrent: ${message}` });
   }
   if (!torrent) {
-    logger.warn(`stats: torrent missing for ${sourceKey.slice(0, 8)} (getTorrent returned null/undefined)`);
-    return reply.code(500).send({ error: "Torrent instance not found" });
+    return reply.code(202).send({ pending: true });
   }
 
   const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
   const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
 
-  // Optional: pin the resume window to a FIXED byte offset for the duration of
-  // one buffering episode (see getFileStats JSDoc) instead of the live, moving
-  // read position — otherwise "bytes needed" can jump up mid-poll as the window
-  // slides forward with playback/encoding progress.
-  const resumeAnchorRaw = typeof req.query.resumeAnchorByteStart === "string" ? req.query.resumeAnchorByteStart : "";
-  const resumeAnchorByteStart = resumeAnchorRaw !== "" && /^\d+$/.test(resumeAnchorRaw) ? Number(resumeAnchorRaw) : 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, { resumeAnchorByteStart });
+  const stats = await torrentPool.getFileStats(torrent, fileIndex);
+  if (stats?.pending || !stats) return reply.code(202).send({ pending: true });
 
   // 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

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

@@ -0,0 +1,16 @@
+/** Report the position and intent of a viewer playing the source directly. */
+export async function handleApiSourceViewerPost(req, reply, { sourceRegistry, viewers }) {
+  const { sourceKey, fileIndex: indexText } = req.params;
+  const fileIndex = Number(indexText);
+  const body = req.body;
+  if (!Number.isSafeInteger(fileIndex) || fileIndex < 0 || !body || typeof body !== "object" ||
+      typeof body.consumerId !== "string" || !body.consumerId) {
+    return reply.code(400).send({ error: "A file index and consumerId are required.", canRetry: false });
+  }
+  if (!sourceRegistry.get(sourceKey)) return reply.code(404).send({ error: "Source key was not found.", canRetry: false });
+  if (!viewers.reportSource(body.consumerId, sourceKey, fileIndex, body)) {
+    return reply.code(409).send({ error: "The source selection is no longer current.",
+      code: "REQUEST_OBSOLETE", canRetry: false });
+  }
+  return reply.send({ received: true });
+}

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

@@ -1,217 +1,8 @@
-import { logger } from "../../../../utils/logger.js";
-import { TEXT_SUBTITLE_SIDECAR_EXTENSIONS } from "../../../../services/torrent/files.js";
-import { contentsOf } from "../../../../services/torrent/Contents.js";
-
-const metadataWarmups = new Map();
-const METADATA_RETRY_MS = 2500;
-
-function startMetadataWarmup({ sourceKey, items, preferredFileIndex, userAgent, playbackPlanner, torrentPool, torrent }) {
-  if (!playbackPlanner || !Array.isArray(items) || items.length === 0) {
-    return false;
-  }
-  let state = metadataWarmups.get(sourceKey);
-  if (!state) {
-    state = { pending: new Set(), preferredFileIndex: null, running: false, items: [] };
-    metadataWarmups.set(sourceKey, state);
-  }
-  state.items = items;
-  for (const item of items) {
-    if (Number.isInteger(item?.fileIndex)) {
-      state.pending.add(item.fileIndex);
-    }
-  }
-  if (Number.isInteger(preferredFileIndex) && state.pending.has(preferredFileIndex)) {
-    state.preferredFileIndex = preferredFileIndex;
-  }
-  if (state.running) {
-    return true;
-  }
-  state.running = true;
-  void (async () => {
-    try {
-      while (state.pending.size > 0) {
-        const fileIndex = state.preferredFileIndex !== null && state.pending.has(state.preferredFileIndex)
-          ? state.preferredFileIndex
-          : state.pending.values().next().value;
-        state.preferredFileIndex = null;
-        if (!Number.isInteger(fileIndex)) {
-          break;
-        }
-        const item = state.items.find((entry) => entry.fileIndex === fileIndex);
-        if (!item) {
-          state.pending.delete(fileIndex);
-          continue;
-        }
-        const sidecars = contentsOf(torrent).sidecarsOf(fileIndex);
-        const sidecarFiles = [...sidecars.audio, ...sidecars.subtitles];
-        await Promise.all(sidecarFiles.map((file) =>
-          torrentPool.prefetchFileEdges(torrent, file.fileIndex, {
-            tailBytes: 0,
-            headBytes: TEXT_SUBTITLE_SIDECAR_EXTENSIONS.has(file.extension)
-              ? Math.max(1, file.length)
-              : undefined,
-            timeoutMs: 10_000
-          }).catch((error) => {
-            logger.info(`warm ${sourceKey.slice(0, 8)}:${fileIndex}: sidecar metadata not ready for "${file.name}": ${error?.message ?? error}`);
-          })
-        ));
-        const plan = await playbackPlanner.getPlan({
-          sourceKey,
-          fileIndex,
-          userAgent,
-          maxWaitMs: 0,
-          background: true
-        }).catch((error) => {
-          logger.info(`warm ${sourceKey.slice(0, 8)}:${fileIndex}: media metadata not ready: ${error?.message ?? error}`);
-          return null;
-        });
-        if (plan && !plan.pending) {
-          state.pending.delete(fileIndex);
-        } else if (torrent.files?.[fileIndex]?.done === true) {
-          state.pending.delete(fileIndex);
-        }
-        if (state.pending.size > 0) {
-          await new Promise((resolve) => setTimeout(resolve, METADATA_RETRY_MS));
-        }
-      }
-    } catch (error) {
-      logger.warn(`warm ${sourceKey.slice(0, 8)}: metadata queue stopped: ${error?.message ?? error}`);
-    } finally {
-      state.running = false;
-      if (state.pending.size === 0) {
-        metadataWarmups.delete(sourceKey);
-      }
-    }
-  })();
-  return true;
-}
-
-/**
- * Start fetching a source before anyone asks to play it.
- *
- * POST /api/sources/:sourceKey/warm   { fileIndex?: number, positionSeconds?: number, userAgent?: string }
- *
- * 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/torrent-pool.js").TorrentPool,
- *   playbackPlanner?: ReturnType<import("../../../../services/media/playback-planner.js").createPlaybackPlanner>,
- *   durationOf?: ({ sourceKey: string, fileIndex: number }) => Promise<number | null>
- * }} deps
- * @returns {Promise<void>}
- */
-export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, torrentPool, playbackPlanner = null, durationOf = null }) {
+/** Compatibility acknowledgement: source preparation is owned by present viewers. */
+export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, viewers }) {
   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;
-  // Where the viewer is about to resume, if they are resuming. The edges below
-  // are what the codec probe reads; this is what the VIEWER will read, and until
-  // now nothing asked for it before the encoder did.
-  const requestedPosition = Number(body.positionSeconds);
-  const positionSeconds = Number.isFinite(requestedPosition) && requestedPosition > 0
-    ? requestedPosition
-    : 0;
-  const userAgent = typeof body.userAgent === "string" ? body.userAgent : "";
-
-  // 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 });
-  }
-
-  const contents = contentsOf(torrent);
-  const named = fileIndex !== null && torrent.files?.[fileIndex] ? fileIndex : null;
-  if (named !== null) {
-    const selectedSidecars = contents.sidecarsOf(named);
-    for (const file of [...selectedSidecars.audio, ...selectedSidecars.subtitles]) {
-      void torrentPool.prefetchFileEdges(torrent, file.fileIndex, {
-        tailBytes: 0,
-        headBytes: TEXT_SUBTITLE_SIDECAR_EXTENSIONS.has(file.extension)
-          ? Math.max(1, file.length)
-          : undefined,
-        timeoutMs: 10_000,
-        awaited: true
-      }).catch((error) => {
-        logger.info(`warm ${sourceKey.slice(0, 8)}:${named}: selected sidecar metadata not ready for "${file.name}": ${error?.message ?? error}`);
-      });
-    }
-  }
-  const orderedItems = named === null
-    ? contents.items
-    : [...contents.items.filter((item) => item.fileIndex === named), ...contents.items.filter((item) => item.fileIndex !== named)];
-  const metadataStarted = startMetadataWarmup({
-    sourceKey,
-    items: orderedItems,
-    preferredFileIndex: named,
-    userAgent,
-    playbackPlanner,
-    torrentPool,
-    torrent
-  });
-  const sidecarCount = new Set(orderedItems.flatMap((item) => {
-    const matched = contents.sidecarsOf(item.fileIndex);
-    return [...matched.audio, ...matched.subtitles].map((file) => file.fileIndex);
-  })).size;
-  const fillStarted = typeof torrentPool.fillTorrent === "function"
-    ? await torrentPool.fillTorrent(torrent).catch((error) => {
-      logger.warn(`warm ${sourceKey.slice(0, 8)}: whole-torrent fill could not start: ${error?.message ?? error}`);
-      return false;
-    })
-    : false;
-  if (named !== null && positionSeconds > 0 && typeof torrentPool.warmResumePosition === "function") {
-    void Promise.resolve(
-      (typeof durationOf === "function"
-        ? durationOf({ sourceKey, fileIndex: named })
-        : Promise.resolve(null)
-      ).then((durationSeconds) =>
-        torrentPool.warmResumePosition(torrent, named, positionSeconds, durationSeconds)
-      )
-    ).catch((error) => {
-      logger.warn(`warm ${sourceKey.slice(0, 8)}: the viewer's position failed: ${error?.message ?? error}`);
-    });
-  }
-
-  logger.info(
-    `warm ${sourceKey.slice(0, 8)}: swarm started for "${torrent.name}"` +
-      `, metadata for ${contents.items.length} video file(s) ${metadataStarted ? "queued" : "unavailable"}` +
-      `, ${sidecarCount} related audio/subtitle file(s)` +
-      (fillStarted ? ", whole-torrent fill enabled at TAIL urgency" : ", whole-torrent fill unavailable")
-  );
-
-  return reply.send({ started: true, swarm: true, edges: metadataStarted, sidecars: sidecarCount, fill: fillStarted });
+  if (!sourceKey) return reply.code(400).send({ error: "sourceKey is required." });
+  if (!sourceRegistry.get(sourceKey)) return reply.code(404).send({ error: "Source key was not found." });
+  const started = (viewers?.forSource(sourceKey).length ?? 0) > 0;
+  return reply.send({ started, swarm: started, edges: false, fill: false });
 }