@torrent-tv/proxy 2.87.20 → 2.88.0

package/routes/api/delivery-sink/get.js

@@ -1,72 +1,72 @@
-/**
- * A stream of bytes with no torrent behind it, for measuring delivery alone.
- *
- * GET /api/delivery-sink?bytes=8388608
- *
- * The delivery freeze (roadmap item 11) takes hundreds of megabytes to appear
- * and needs the real transport to appear at all, so reproducing it means
- * pushing gigabytes through a data channel on demand. Doing that through a real
- * file drags in the swarm, the encoder and the disk, none of which is under
- * test and each of which has its own stalls; this route removes them and leaves
- * the path the question is about: the same handler, the same chunk loop, the
- * same backpressure, the same channel.
- *
- * The body is a repeating pattern rather than zeroes, so a receiver can verify
- * it got the bytes it was promised in the order they were sent — a silent
- * truncation would otherwise read as a successful transfer.
- *
- * Enabled only when the proxy was started with `--delivery-sink`; without the
- * flag the route answers 404, so an ordinary install has no such endpoint.
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ enabled: boolean }} deps
- * @returns {Promise<void>}
- */
-export async function handleApiDeliverySinkGet(req, reply, { enabled } = {}) {
-  if (enabled !== true) {
-    return reply.code(404).send({ error: "Not found." });
-  }
-
-  const requested = Number((req.query ?? {}).bytes);
-  const total = Number.isFinite(requested)
-    ? Math.min(Math.max(Math.trunc(requested), 0), MAX_SINK_BYTES)
-    : DEFAULT_SINK_BYTES;
-  const requestedChunk = Number((req.query ?? {}).chunkBytes);
-  const chunkBytes = Number.isFinite(requestedChunk)
-    ? Math.min(Math.max(Math.trunc(requestedChunk), 1024), CHUNK_BYTES)
-    : CHUNK_BYTES;
-
-  // One buffer, reused: allocating a fresh chunk per iteration would make this
-  // route measure the allocator as much as the transport.
-  const chunk = Buffer.alloc(chunkBytes);
-  for (let i = 0; i < chunkBytes; i += 1) {
-    chunk[i] = i % 251; // 251 is prime, so the pattern does not align to any power of two.
-  }
-
-  reply.header("content-type", "application/octet-stream");
-  reply.header("content-length", String(total));
-  reply.header("cache-control", "no-store");
-
-  let sent = 0;
-  const stream = new ReadableStream({
-    pull(controller) {
-      if (sent >= total) {
-        controller.close();
-        return;
-      }
-      const size = Math.min(chunkBytes, total - sent);
-      controller.enqueue(size === chunkBytes ? chunk : chunk.subarray(0, size));
-      sent += size;
-    }
-  });
-
-  return reply.send(stream);
-}
-
-/** Chunk size, matching what a body read hands the send loop for a real file. */
-const CHUNK_BYTES = 64 * 1024;
-/** Default when no size is asked for: about one segment of 1080p. */
-const DEFAULT_SINK_BYTES = 8 * 1024 * 1024;
-/** Ceiling, so one request cannot ask the proxy for an unbounded stream. */
-const MAX_SINK_BYTES = 64 * 1024 * 1024;
+/**
+ * A stream of bytes with no torrent behind it, for measuring delivery alone.
+ *
+ * GET /api/delivery-sink?bytes=8388608
+ *
+ * The delivery freeze (roadmap item 11) takes hundreds of megabytes to appear
+ * and needs the real transport to appear at all, so reproducing it means
+ * pushing gigabytes through a data channel on demand. Doing that through a real
+ * file drags in the swarm, the encoder and the disk, none of which is under
+ * test and each of which has its own stalls; this route removes them and leaves
+ * the path the question is about: the same handler, the same chunk loop, the
+ * same backpressure, the same channel.
+ *
+ * The body is a repeating pattern rather than zeroes, so a receiver can verify
+ * it got the bytes it was promised in the order they were sent — a silent
+ * truncation would otherwise read as a successful transfer.
+ *
+ * Enabled only when the proxy was started with `--delivery-sink`; without the
+ * flag the route answers 404, so an ordinary install has no such endpoint.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ enabled: boolean }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiDeliverySinkGet(req, reply, { enabled } = {}) {
+  if (enabled !== true) {
+    return reply.code(404).send({ error: "Not found." });
+  }
+
+  const requested = Number((req.query ?? {}).bytes);
+  const total = Number.isFinite(requested)
+    ? Math.min(Math.max(Math.trunc(requested), 0), MAX_SINK_BYTES)
+    : DEFAULT_SINK_BYTES;
+  const requestedChunk = Number((req.query ?? {}).chunkBytes);
+  const chunkBytes = Number.isFinite(requestedChunk)
+    ? Math.min(Math.max(Math.trunc(requestedChunk), 1024), CHUNK_BYTES)
+    : CHUNK_BYTES;
+
+  // One buffer, reused: allocating a fresh chunk per iteration would make this
+  // route measure the allocator as much as the transport.
+  const chunk = Buffer.alloc(chunkBytes);
+  for (let i = 0; i < chunkBytes; i += 1) {
+    chunk[i] = i % 251; // 251 is prime, so the pattern does not align to any power of two.
+  }
+
+  reply.header("content-type", "application/octet-stream");
+  reply.header("content-length", String(total));
+  reply.header("cache-control", "no-store");
+
+  let sent = 0;
+  const stream = new ReadableStream({
+    pull(controller) {
+      if (sent >= total) {
+        controller.close();
+        return;
+      }
+      const size = Math.min(chunkBytes, total - sent);
+      controller.enqueue(size === chunkBytes ? chunk : chunk.subarray(0, size));
+      sent += size;
+    }
+  });
+
+  return reply.send(stream);
+}
+
+/** Chunk size, matching what a body read hands the send loop for a real file. */
+const CHUNK_BYTES = 64 * 1024;
+/** Default when no size is asked for: about one segment of 1080p. */
+const DEFAULT_SINK_BYTES = 8 * 1024 * 1024;
+/** Ceiling, so one request cannot ask the proxy for an unbounded stream. */
+const MAX_SINK_BYTES = 64 * 1024 * 1024;

package/routes/api/link-probe/get.js

@@ -1,51 +1,51 @@
-/**
- * @file `GET /api/link-probe?bytes=N` — bytes to measure the link with.
- *
- * WHY THIS EXISTS. A viewer's link is measured from completed transfers, and
- * the only transfers that counted were segments of the film. So the figure came
- * into being after playback had begun — after the quality offer had been made,
- * and after the start-up decisions that want it. Worse, the page's report of
- * its OWN facts was skipped when there was no figure, so at a cold open — the
- * moment where where-the-viewer-is matters most — the page said nothing at all
- * (2026-09-14).
- *
- * There is nothing to wait for: a proxy can send bytes the moment its channel
- * is up, which is when the page opens rather than when a film is chosen.
- *
- * NOT `delivery-sink`, which is the load stand's and answers any size asked
- * for. This is part of the product, always on, and bounded — the browser's own
- * sizing stops at 2 MiB and this refuses more, so a caller cannot turn it into
- * a way of drawing a proxy owner's uplink.
- *
- * The body is zeros. What is being measured is the wire, and zeros cross it at
- * the same speed as anything else; producing them costs one allocation.
- */
-
-/**
- * The most this route will send for one ask.
- *
- * The figure is only ever used to decide what a link can carry, and the most
- * anything this product offers is a 1080p rung at around 12 Mbit/s. Two
- * mebibytes inside the browser's minimum measurable transfer (50 ms) is
- * 336 Mbit/s, twenty-eight times that rung: a link too fast to time at this
- * size is beyond anything a decision here distinguishes.
- */
-export const MAX_LINK_PROBE_BYTES = 2 * 1024 * 1024;
-
-/**
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @returns {Promise<void>}
- */
-export async function handleApiLinkProbeGet(req, reply) {
-  const asked = Number(/** @type {{ bytes?: string }} */ (req.query)?.bytes);
-  if (!Number.isFinite(asked) || asked <= 0) {
-    return reply.code(400).send({ error: "bytes (>0) is required." });
-  }
-  const bytes = Math.min(Math.floor(asked), MAX_LINK_PROBE_BYTES);
-  return reply
-    .code(200)
-    .header("Content-Type", "application/octet-stream")
-    .header("Cache-Control", "no-store")
-    .send(Buffer.alloc(bytes));
-}
+/**
+ * @file `GET /api/link-probe?bytes=N` — bytes to measure the link with.
+ *
+ * WHY THIS EXISTS. A viewer's link is measured from completed transfers, and
+ * the only transfers that counted were segments of the film. So the figure came
+ * into being after playback had begun — after the quality offer had been made,
+ * and after the start-up decisions that want it. Worse, the page's report of
+ * its OWN facts was skipped when there was no figure, so at a cold open — the
+ * moment where where-the-viewer-is matters most — the page said nothing at all
+ * (2026-09-14).
+ *
+ * There is nothing to wait for: a proxy can send bytes the moment its channel
+ * is up, which is when the page opens rather than when a film is chosen.
+ *
+ * NOT `delivery-sink`, which is the load stand's and answers any size asked
+ * for. This is part of the product, always on, and bounded — the browser's own
+ * sizing stops at 2 MiB and this refuses more, so a caller cannot turn it into
+ * a way of drawing a proxy owner's uplink.
+ *
+ * The body is zeros. What is being measured is the wire, and zeros cross it at
+ * the same speed as anything else; producing them costs one allocation.
+ */
+
+/**
+ * The most this route will send for one ask.
+ *
+ * The figure is only ever used to decide what a link can carry, and the most
+ * anything this product offers is a 1080p rung at around 12 Mbit/s. Two
+ * mebibytes inside the browser's minimum measurable transfer (50 ms) is
+ * 336 Mbit/s, twenty-eight times that rung: a link too fast to time at this
+ * size is beyond anything a decision here distinguishes.
+ */
+export const MAX_LINK_PROBE_BYTES = 2 * 1024 * 1024;
+
+/**
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @returns {Promise<void>}
+ */
+export async function handleApiLinkProbeGet(req, reply) {
+  const asked = Number(/** @type {{ bytes?: string }} */ (req.query)?.bytes);
+  if (!Number.isFinite(asked) || asked <= 0) {
+    return reply.code(400).send({ error: "bytes (>0) is required." });
+  }
+  const bytes = Math.min(Math.floor(asked), MAX_LINK_PROBE_BYTES);
+  return reply
+    .code(200)
+    .header("Content-Type", "application/octet-stream")
+    .header("Cache-Control", "no-store")
+    .send(Buffer.alloc(bytes));
+}

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

@@ -1,29 +1,29 @@
-/**
- * Refresh metadata for audio tracks whose sidecar headers were unavailable
- * when the playback plan was built.
- *
- * POST /api/playback-plan/audio-tracks
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ playbackPlanner: object }} deps
- */
-export async function handleApiPlaybackPlanAudioTracksPost(req, reply, { playbackPlanner }) {
-  const payload = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
-  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
-  const fileIndex = Number(payload.fileIndex);
-  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
-    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
-  }
-  try {
-    const { PlaybackController } = await import("../../../../services/server/controllers/PlaybackController.js");
-    const controller = new PlaybackController({ playbackPlanner });
-    return reply.send(await controller.refreshAudioTracks({ sourceKey, fileIndex }));
-  } catch (error) {
-    if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {
-      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 refresh audio track metadata: ${message}` });
-  }
-}
+/**
+ * Refresh metadata for audio tracks whose sidecar headers were unavailable
+ * when the playback plan was built.
+ *
+ * POST /api/playback-plan/audio-tracks
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ playbackPlanner: object }} deps
+ */
+export async function handleApiPlaybackPlanAudioTracksPost(req, reply, { playbackPlanner }) {
+  const payload = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
+  const fileIndex = Number(payload.fileIndex);
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
+  }
+  try {
+    const { PlaybackController } = await import("../../../../services/server/controllers/PlaybackController.js");
+    const controller = new PlaybackController({ playbackPlanner });
+    return reply.send(await controller.refreshAudioTracks({ sourceKey, fileIndex }));
+  } catch (error) {
+    if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {
+      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 refresh audio track metadata: ${message}` });
+  }
+}

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

@@ -1,53 +1,53 @@
-/**
- * Determine the best playback mode (direct stream or HLS transcode) for a
- * torrent file and return the corresponding plan.
- *
- * POST /api/playback-plan
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ playbackPlanner: ReturnType<import("../../../services/media/playback-planner.js").createPlaybackPlanner> }} deps
- * @returns {Promise<void>}
- */
-
-/**
- * Extract a plain object from the request body, guarding against
- * non-object payloads (arrays, primitives, null).
- *
- * @param {unknown} body
- * @returns {Record<string, unknown>}
- */
-function getPayload(body) {
-  if (body && typeof body === "object" && !Array.isArray(body)) {
-    return body;
-  }
-  return {};
-}
-
-export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner, sourceRegistry, torrentPool, ffmpegBin, localBaseUrl }) {
-  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) {
-    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
-  }
-
-  // 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 });
-  try {
-    const plan = await controller.getPlan({ sourceKey, fileIndex, userAgent, maxWaitMs: 8_000 });
-    return reply.send(plan);
-  } catch (error) {
-    if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {
-      return reply.code(404).send({ error: error.message });
-    }
-    if (error instanceof Error && error.code === "FILE_NOT_FOUND") {
-      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}` });
-  }
-}
+/**
+ * Determine the best playback mode (direct stream or HLS transcode) for a
+ * torrent file and return the corresponding plan.
+ *
+ * POST /api/playback-plan
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ playbackPlanner: ReturnType<import("../../../services/media/playback-planner.js").createPlaybackPlanner> }} deps
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner, sourceRegistry, torrentPool, ffmpegBin, localBaseUrl }) {
+  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) {
+    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
+  }
+
+  // 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 });
+  try {
+    const plan = await controller.getPlan({ sourceKey, fileIndex, userAgent, maxWaitMs: 8_000 });
+    return reply.send(plan);
+  } catch (error) {
+    if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {
+      return reply.code(404).send({ error: error.message });
+    }
+    if (error instanceof Error && error.code === "FILE_NOT_FOUND") {
+      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}` });
+  }
+}

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

@@ -1,100 +1,106 @@
-import { contentsOf } from "../../../../services/torrent/Contents.js";
-
-/**
- * List the files of a registered source (torrent file OR magnet).
- *
- * GET /api/sources/:sourceKey/files
- *
- * 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.
- *
- * @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
- * }} deps
- * @returns {Promise<void>}
- */
-
-/** Sentinel resolved when the per-request wait elapses before metadata. */
-const PENDING = Symbol("pending");
-
-export async function handleApiSourceFilesGet(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." });
-  }
-
-  // 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?.();
-  });
-  const torrentPromise = torrentPool
-    .getTorrent(sourceRecord.sourceType, sourceRecord.source)
-    // Swallow so a rejection that loses the race is not an unhandled rejection;
-    // the next poll re-issues getTorrent and re-observes any real error.
-    .catch((error) => (error instanceof Error ? error : new Error(String(error))));
-
-  let result;
-  try {
-    result = await Promise.race([torrentPromise, waitPromise]);
-  } finally {
-    clearTimeout(timer);
-  }
-
-  if (result === PENDING) {
-    return reply.send({ pending: true });
-  }
-  if (result instanceof Error) {
-    return reply.code(502).send({ error: `Could not load torrent metadata: ${result.message}` });
-  }
-
-  const torrent = result;
-  // WHAT IS IN THIS TORRENT, decided here and nowhere else. The browser used to
-  // decide it again — a list of video extensions in its parser and a second,
-  // shorter pair inside its picker — and the three answers had already diverged
-  // (measured 2026-09-12: `.dat` was offered there and not counted here, which
-  // also decides whether a sidecar whose name matches nothing can belong to the
-  // 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);
-  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(),
-    // 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.
-    items: contents.items.map((item) => ({
-      fileIndex: item.fileIndex,
-      audio: item.audio.map((part) => part.fileIndex),
-      subtitles: item.subtitles.map((part) => part.fileIndex),
-      images: item.images.map((part) => part.fileIndex)
-    }))
-  });
-}
+import { contentsOf } from "../../../../services/torrent/Contents.js";
+
+/**
+ * List the files of a registered source (torrent file OR magnet).
+ *
+ * GET /api/sources/:sourceKey/files
+ *
+ * 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.
+ *
+ * @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
+ * }} deps
+ * @returns {Promise<void>}
+ */
+
+/** Sentinel resolved when the per-request wait elapses before metadata. */
+const PENDING = Symbol("pending");
+
+export async function handleApiSourceFilesGet(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." });
+  }
+
+  // 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?.();
+  });
+  const torrentPromise = torrentPool
+    .getTorrent(sourceRecord.sourceType, sourceRecord.source)
+    // Swallow so a rejection that loses the race is not an unhandled rejection;
+    // the next poll re-issues getTorrent and re-observes any real error.
+    .catch((error) => (error instanceof Error ? error : new Error(String(error))));
+
+  let result;
+  try {
+    result = await Promise.race([torrentPromise, waitPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (result === PENDING) {
+    return reply.send({ pending: true });
+  }
+  if (result instanceof Error) {
+    return reply.code(502).send({ error: `Could not load torrent metadata: ${result.message}` });
+  }
+
+  const torrent = result;
+  // WHAT IS IN THIS TORRENT, decided here and nowhere else. The browser used to
+  // decide it again — a list of video extensions in its parser and a second,
+  // shorter pair inside its picker — and the three answers had already diverged
+  // (measured 2026-09-12: `.dat` was offered there and not counted here, which
+  // also decides whether a sidecar whose name matches nothing can belong to the
+  // 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);
+  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(),
+    // 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.
+    items: contents.items.map((item) => ({
+      fileIndex: item.fileIndex,
+      audio: item.audio.map((part) => part.fileIndex),
+      subtitles: item.subtitles.map((part) => part.fileIndex),
+      images: item.images.map((part) => part.fileIndex),
+      // What the name says about which episode this is, in the release's own
+      // numbering — read by the page to ask which episode of the show it is.
+      episode: item.episode
+    })),
+    // One film, a series, or not known — whether one identification of the
+    // whole release applies to its pictures at all.
+    shape: contents.shape
+  });
+}