@torrent-tv/proxy 2.86.0 → 2.87.1

package/services/{torrent-worker → torrent/worker}/pool-adapter.js

@@ -35,7 +35,7 @@ export class WorkerTorrentPool {
   #torrents = new Map();
 
   /**
-   * @param {{ maxDiskBytes?: number, memoryBytes?: number, stateDir?: string }} [options]
+   * @param {{ memoryBytes?: number, stateDir?: string }} [options]
    */
   constructor(options = {}) {
     this.#client = new TorrentWorkerClient(options);
@@ -83,6 +83,22 @@ export class WorkerTorrentPool {
     return this.#client.allowSpillBytes(bytes);
   }
 
+  get memoryClaim() {
+    return this.#client.memoryClaim ?? { held: 0, wanted: 0 };
+  }
+
+  allowMemoryBytes(bytes) {
+    return this.#client.allowMemoryBytes(bytes);
+  }
+
+  get wholeFileBytes() {
+    return this.#client.wholeFileBytes ?? 0;
+  }
+
+  allowWholeFileBytes(bytes) {
+    return this.#client.allowWholeFileBytes(bytes);
+  }
+
   /**
    * Bytes every torrent here has moved.
    *
@@ -132,62 +148,8 @@ export class WorkerTorrentPool {
     return answer?.started === true;
   }
 
-  /**
-   * The text subtitle tracks a file carries, read from its own header.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getSubtitleTracks(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return [];
-    }
-    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
-    return Array.isArray(answer?.tracks) ? answer.tracks : [];
-  }
 
-  /**
-   * What the container itself declares about its subtitle tracks, in its own
-   * order and including the picture-based ones — for lining up against
-   * ffmpeg's own numbering.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getDeclaredSubtitleTracks(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return [];
-    }
-    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
-    return Array.isArray(answer?.declared) ? answer.declared : [];
-  }
 
-  /**
-   * Every track one file declares, read from its own header by the container
-   * layer.
-   *
-   * The audio menu is built from ffmpeg's `-i` banner, which carries neither
-   * `FlagOriginal`, `FlagCommentary`, `FlagVisualImpaired`, `FlagEnabled` nor
-   * `LanguageBCP47` — so without this a director's commentary and the film
-   * itself are indistinguishable in it. Also how a soundtrack shipped as its own
-   * file is read: a `.mka` is Matroska and the same reader serves it.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getContainerTracks(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return [];
-    }
-    const answer = await this.#client.getContainerTracks({ sourceKey, fileIndex });
-    return Array.isArray(answer?.tracks) ? answer.tracks : [];
-  }
 
   /**
    * Start fetching the region a viewer is about to resume at. Named in seconds
@@ -198,99 +160,19 @@ export class WorkerTorrentPool {
    * @param {number} positionSeconds
    * @returns {Promise<boolean>}
    */
-  async warmResumePosition(torrent, fileIndex, positionSeconds) {
+  async warmResumePosition(torrent, fileIndex, positionSeconds, durationSeconds) {
     const sourceKey = torrent?.sourceKey;
     if (!sourceKey) {
       return false;
     }
-    const answer = await this.#client.warmResumePosition({ sourceKey, fileIndex, positionSeconds });
+    const answer = await this.#client.warmResumePosition({ sourceKey, fileIndex, positionSeconds, durationSeconds });
     return answer?.started === true;
   }
 
-  /**
-   * What one file declares about itself: format, duration, and where its own
-   * timeline begins.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
-   */
-  async getContainerMediaInfo(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    const answer = await this.#client.getContainerMediaInfo({ sourceKey, fileIndex });
-    return answer?.info ?? null;
-  }
 
-  /**
-   * Where one file's keyframes are, from the container's own table. Null when
-   * this file has no readable index — which is a final answer about the file,
-   * and the reason a copy of it has to be re-encoded instead.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<{ times: number[], tolerance: number } | null>}
-   */
-  async getContainerKeyframes(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    const answer = await this.#client.getContainerKeyframes({ sourceKey, fileIndex });
-    return answer?.index ?? null;
-  }
 
-  /**
-   * The audio tracks one file declares, in the order ffmpeg numbers them
-   * `0:a:N`.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getDeclaredAudioTracks(torrent, fileIndex) {
-    const tracks = await this.getContainerTracks(torrent, fileIndex);
-    return tracks
-      .filter((track) => track?.type === "audio")
-      .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0));
-  }
 
-  /**
-   * The video track one file declares, or null where it declares none.
-   *
-   * One, because ffmpeg's `0:v:0` is what everything downstream is built on and
-   * a second video stream is a cover image far more often than a second film.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object | null>}
-   */
-  async getDeclaredVideoTrack(torrent, fileIndex) {
-    const tracks = await this.getContainerTracks(torrent, fileIndex);
-    return (
-      tracks
-        .filter((track) => track?.type === "video")
-        .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0))[0] ?? null
-    );
-  }
 
-  /**
-   * The cues of one subtitle track that the downloaded clusters already carry.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {number} trackNumber
-   * @returns {Promise<object | null>}
-   */
-  async getSubtitleCues(torrent, fileIndex, trackNumber) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    return this.#client.getSubtitleCues({ sourceKey, fileIndex, trackNumber });
-  }
 
   /**
    * Reorder piece selection around a read position.
@@ -352,6 +234,88 @@ export class WorkerTorrentPool {
    * @param {{ headBytes?: number, tailBytes?: number, timeoutMs?: number }} [options]
    * @returns {Promise<unknown>}
    */
+  /**
+   * One byte range of one file, as bytes, on THIS thread.
+   *
+   * What the media layer is built from: a container takes `readRange(start,
+   * end)` and nothing else, so with this it can be parsed here instead of in
+   * the torrent thread. It used to be parsed there for one stated reason —
+   * "the main thread cannot open a read stream on one of its files", which is
+   * true of WebTorrent's own API and not of the bytes: the pieces live in
+   * shared memory and this read is the same one that serves every segment,
+   * so it waits for what has not arrived and steers the swarm toward it.
+   *
+   * **It COPIES, deliberately.** The zero-copy path — positions across the
+   * channel, the piece pinned until the far side says it is done — exists for
+   * 10 MB segments on the critical path, where the copy was measured at
+   * 18.84 ms. A container header is 64-256 KB and read once per file, about
+   * 0.12 ms, against a parse of 0.8 s and a swarm wait of up to a minute. The
+   * pinning protocol would buy nothing and is not on this path.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} start - First byte, inclusive.
+   * @param {number} end - Last byte, inclusive.
+   * @returns {Promise<Buffer | null>} Null when the read failed or was cut
+   *   short, which a container reads as "this file does not say".
+   */
+  /**
+   * The byte ranges of one file the torrent holds WHOLE.
+   *
+   * What the subtitle walk decides from: it may read only what is already
+   * downloaded, and a list taken once per pass replaces a question per cluster.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<Array<[number, number]>>}
+   */
+  async heldRangesOf(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    return sourceKey ? this.#client.heldRanges({ sourceKey, fileIndex }) : [];
+  }
+
+  /**
+   * Bytes of a range the torrent already holds, never fetched.
+   *
+   * Not `readRangeOf`: that one declares demand and steers the swarm, which is
+   * right for a viewer waiting on a segment and wrong for a walk that must pull
+   * nothing the viewer is not waiting for.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} start
+   * @param {number} end - Inclusive.
+   * @returns {Promise<Buffer | null>}
+   */
+  async readHeldOf(torrent, fileIndex, start, end) {
+    const sourceKey = torrent?.sourceKey;
+    return sourceKey ? this.#client.readHeld({ sourceKey, fileIndex, start, end }) : null;
+  }
+
+  async readRangeOf(torrent, fileIndex, start, end) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey || !(end >= start) || !(start >= 0)) {
+      return null;
+    }
+    const stream = this.#client.createReadStream({ sourceKey, fileIndex, start, end });
+    const chunks = [];
+    let total = 0;
+    try {
+      const reader = stream.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        chunks.push(Buffer.from(value));
+        total += value.length;
+      }
+    } catch {
+      return null;
+    }
+    return total > 0 ? Buffer.concat(chunks, total) : null;
+  }
+
   async prefetchFileEdges(torrent, fileIndex, options = {}) {
     const sourceKey = torrent?.sourceKey;
     if (!sourceKey) {

package/services/{torrent-worker → torrent/worker}/protocol.js

@@ -79,37 +79,28 @@ export const Command = {
    * the work is under way.
    */
   FILL_FILE: "fill-file",
-  /** The text subtitle tracks a file carries, for the viewer's menu. */
-  SUBTITLE_TRACKS: "subtitle-tracks",
   /**
-   * Every track a file declares, read from its own header by the container
-   * layer. Answers what ffmpeg's `-i` banner cannot: FlagOriginal,
-   * FlagCommentary, FlagVisualImpaired, FlagEnabled and LanguageBCP47 appear
-   * nowhere in it. Asked of the picture AND of a soundtrack shipped as its own
-   * file beside it, which is the same question about a different file.
-   */
-  CONTAINER_TRACKS: "container-tracks",
-  /**
-   * What a file declares about itself as a whole — format, duration, and where
-   * its own timeline begins. Read from the same header, by the same reader, as
-   * the track table above; the alternative was a second ffmpeg over the proxy's
-   * own HTTP reading the same bytes again.
+   * Start fetching the region a viewer is about to resume at, named in seconds
+   * and turned into bytes here, where the file's own duration can be read.
    */
-  CONTAINER_MEDIA_INFO: "container-media-info",
+  WARM_POSITION: "warm-position",
   /**
-   * Where a file's keyframes are, from the container's own table. A property of
-   * immutable bytes, read once per file by the same container that answers the
-   * two above — and the answer decides whether a picture can be copied at all,
-   * which must be the same answer for every viewer of that file.
+   * The byte ranges of one file the torrent holds WHOLE, so the subtitle walk
+   * can decide what it may read without asking the swarm. A list rather than a
+   * question per cluster: a pass asks about every cluster of the file, and
+   * hundreds of round trips for a walk meant to be free when there is nothing
+   * new would be the cost of the split, not of the work.
    */
-  CONTAINER_KEYFRAMES: "container-keyframes",
+  HELD_RANGES: "held-ranges",
+
   /**
-   * Start fetching the region a viewer is about to resume at, named in seconds
-   * and turned into bytes here, where the file's own duration can be read.
+   * Bytes of a range the torrent already holds, read from the store and never
+   * fetched. The ordinary range read declares demand and steers the swarm,
+   * which is right for a viewer waiting on a segment and wrong for a walk that
+   * must pull nothing.
    */
-  WARM_POSITION: "warm-position",
-  /** Cues of one subtitle track, from the clusters already downloaded. */
-  SUBTITLE_CUES: "subtitle-cues",
+  READ_HELD: "read-held",
+
   /** Shut the client down, optionally deleting downloaded data. */
   /**
    * How much disk the spilled pieces may take between them.
@@ -120,6 +111,8 @@ export const Command = {
    * divides its share between the stores it holds.
    */
   SPILL_ALLOWANCE: "spill-allowance",
+  WHOLE_FILES_ALLOWANCE: "whole-files-allowance",
+  MEMORY_ALLOWANCE: "memory-allowance",
   DESTROY_ALL: "destroy-all"
 };
 
@@ -155,12 +148,15 @@ export const Event = {
   /** A log line, so worker output reaches the same place as everything else. */
   LOG: "log",
   /**
-   * New subtitle cues were read for one track, unprompted — the worker found
-   * them off its own `verified`-piece walk, not in answer to a
-   * {@link Command.SUBTITLE_CUES} call. Lets the main thread PUSH them to
-   * whichever browser is watching instead of waiting to be asked.
+   * Pieces of these files have arrived.
+   *
+   * ANNOUNCED, not asked: the torrent is the only thing that knows a piece just
+   * verified, and what anybody does about it — walk a subtitle track's new
+   * clusters, say — is no business of this thread. It used to walk them itself,
+   * which put the cue reading in the thread that owns the swarm.
    */
-  SUBTITLE_CUES_READY: "subtitle-cues-ready",
+  PIECES_ARRIVED: "pieces-arrived",
+
   /**
    * A file has been downloaded whole and written out as a file.
    *

package/services/torrent/worker/resume-warm.js

@@ -0,0 +1,107 @@
+/**
+ * @file Fetching the region under a viewer's resume position.
+ *
+ * All that is left of a file that used to read containers here as well. The
+ * parsing moved to the main thread on 2026-09-15: a container is built from one
+ * function, `readRange(start, end)`, the pieces behind it live in shared memory,
+ * and the reason it had been put here — "the main thread cannot open a read
+ * stream on one of its files" — was true of WebTorrent's own API and not of the
+ * bytes. Three commands, a second `ContainerOrchestrator` in this thread, and
+ * every answer carried back over the channel went with it.
+ *
+ * What stays is the part that really is the torrent's: turning a position in
+ * seconds into a byte offset and pulling that region off the swarm. How long
+ * the file runs is TOLD to it, because that is what the file states about
+ * itself and this thread no longer reads such things.
+ */
+
+import { logger } from "../../../utils/logger.js";
+
+
+
+
+
+
+
+
+
+
+/**
+ * How much of the file to pull in under the viewer's resume position.
+ *
+ * One piece of a video torrent is 4-16 MB and a resume lands anywhere inside
+ * one, so anything smaller would still leave the encoder waiting for the piece
+ * it starts in. Eight megabytes covers that piece and usually the next.
+ */
+const RESUME_REGION_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Where a position in seconds falls in a file, in bytes.
+ *
+ * Proportional, and therefore approximate on a variable bitrate — which is what
+ * it is for: a prefetch that puts the swarm to work on roughly the right place
+ * while the plan and the session are still being built. The encoder's own read
+ * asks for the exact bytes a moment later and corrects it.
+ *
+ * A position past the end is clamped to the end rather than refused: a resume
+ * position can outlive the file it was recorded against, and reading the last
+ * bytes is harmless where reading past them is an error.
+ *
+ * @param {number} fileLength
+ * @param {number} durationSeconds
+ * @param {number} positionSeconds
+ * @returns {number}
+ */
+export function resumeByteOffset(fileLength, durationSeconds, positionSeconds) {
+  if (!(fileLength > 0) || !(durationSeconds > 0) || !(positionSeconds > 0)) {
+    return 0;
+  }
+  const within = Math.min(positionSeconds, durationSeconds);
+  return Math.min(fileLength - 1, Math.floor((fileLength * within) / durationSeconds));
+}
+
+/**
+ * Start fetching the region a viewer is about to resume at.
+ *
+ * Where that region IS can only be worked out from two numbers the file itself
+ * holds — its length and its duration — so this belongs beside the container
+ * read rather than in the route: the route knows a position in seconds and
+ * nothing else. The conversion is proportional and therefore approximate on a
+ * variable bitrate; it is a prefetch, and the encoder's own read corrects it.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {number} positionSeconds
+ * @param {{ prefetchEdges?: () => Promise<unknown>, fetchRegion?: (start: number, bytes: number) => Promise<unknown> }} options
+ * @returns {Promise<boolean>} Whether a region was asked for.
+ */
+export async function warmResumePosition(torrent, fileIndex, sourceKey, positionSeconds, options = {}) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !(positionSeconds > 0) || typeof options.fetchRegion !== "function") {
+    return false;
+  }
+  // TOLD, not worked out here. How long a file runs is what the file states
+  // about itself, and that is read on the main thread now; this one turns a
+  // position into a byte offset and fetches the region under it, which is all
+  // of the job that is actually the torrent's.
+  const duration = Number(options.durationSeconds);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    logger.info(
+      `warm ${sourceKey.slice(0, 8)}: "${String(file.name).slice(0, 40)}" does not declare its ` +
+      "duration, so where the viewer's position falls in it cannot be worked out — " +
+      "the region under it is left to the encoder's own read"
+    );
+    return false;
+  }
+  const at = resumeByteOffset(file.length, duration, positionSeconds);
+  logger.info(
+    `warm ${sourceKey.slice(0, 8)}: fetching ${(RESUME_REGION_BYTES / (1024 * 1024)).toFixed(0)}MB under the ` +
+    `viewer's position ${positionSeconds.toFixed(1)}s of ${duration.toFixed(1)}s, which is ` +
+    `${(at / (1024 * 1024)).toFixed(1)}MB into "${String(file.name).slice(0, 40)}"`
+  );
+  await options.fetchRegion(at, RESUME_REGION_BYTES);
+  return true;
+}
+
+

package/services/{torrent-worker → torrent/worker}/webrtc-shim.js

@@ -9,7 +9,7 @@
  * does not help. The upstream issue about workers (#129) was closed in 0.4.0
  * but only covers use from a worker ALONE, which does work.
  *
- * We need it twice: `webrtc-manager.js` runs the video channel to the browser on
+ * We need it twice: `transport/webrtc-manager.js` runs the video channel to the browser on
  * the main thread, and the torrent client — which is now on its own thread —
  * creates peer connections of its own to announce on `wss://` trackers. Before
  * the thread split both lived in one isolate and nothing was wrong; afterwards
@@ -17,7 +17,7 @@
  *
  * So the native stack stays where it earns its keep — the main thread, carrying
  * video — and the torrent's trackers get a JavaScript implementation, where the
- * traffic is a handful of signalling messages. `services/torrent-worker/worker.js`
+ * traffic is a handful of signalling messages. `services/torrent/worker/worker.js`
  * installs a module resolution hook that points `webrtc-polyfill` here; nothing
  * outside the worker thread is affected, and no dependency is patched (the addon
  * installs with `--ignore-scripts`, so a postinstall patch would never run).