@torrent-tv/proxy 2.88.6 → 2.89.0

package/services/media/container/AviContainer.js

@@ -34,7 +34,7 @@ export class AviContainer extends Container {
 
   async readTracks() {
     const head = await this.readRange(0, Math.min(4095, this.fileSize - 1));
-    if (!head || !isAvi(head)) return [];
+    if (!isAvi(head)) return [];
     // AVI track table is minimal — expose one video track for uniformity.
     return [new VideoTrack({
       trackNumber: 1,
@@ -65,9 +65,11 @@ export class AviContainer extends Container {
     }
     /** @type {import("./Container.js").ContainerMediaInfo} */
     const info = { format: this.formatName, durationSeconds: null, startTimeSeconds: 0 };
-    this.mediaInfo = info;
     const head = await this.readRange(0, Math.min(4095, this.fileSize - 1));
-    if (!head || !isAvi(head)) {
+    // Kept only once the head has been read: one that had not arrived used to
+    // leave an empty answer here for the life of the container.
+    this.mediaInfo = info;
+    if (!isAvi(head)) {
       return info;
     }
     // RIFF("AVI ") -> LIST("hdrl") -> avih. The avih chunk's payload begins with

package/services/media/container/Container.js

@@ -12,6 +12,8 @@
  *  - AVI RIFF §: LIST hdrl, idx1
  */
 
+import { strictReader } from "./unavailable.js";
+
 /**
  * What one file declares about itself. Every field is either a value the
  * container states or `null`, which means the container does not state it —
@@ -27,41 +29,35 @@
 
 export class Container {
   /**
-   * Two ways of reading, because two readers of one file want different things
-   * and the file is opened once.
-   *
-   * `readRange` fetches what is missing: the head and the track table are
-   * kilobytes, they are needed before anything can be offered, and the codec
-   * probe has already pulled the head of every file that plays. `readHeld`
-   * reads only what is already downloaded and asks the swarm for nothing, which
-   * is what the cue walk needs — turning subtitles on must not pull bytes the
-   * viewer is not waiting for. `isHeld` says whether a range can be read that
-   * way at all, so the walk can leave a cluster for next time instead of
-   * blocking on it.
-   *
-   * They are given per container rather than per call because a container is
-   * cached per file and both readers want the same parsed head. Where the
-   * caller supplies only `readRange`, the held reader is that one and every
-   * range counts as held — which is the right answer for a local file, and for
-   * a torrent it is the caller's job to say otherwise.
-   *
-   * The torrent is NOT passed in and must not be: `readHeld` and `isHeld` are
-   * the only two facts about it this layer needs, and reducing it to two
-   * functions is what keeps the container ignorant of where its bytes live.
+   * One reader, the one that fetches what is missing, and one container per
+   * file — the one `ContainerOrchestrator` keeps.
+   *
+   * `readRange` is made strict here: it answers with every byte asked for or
+   * throws `BytesUnavailable`, so no reading in any subclass can mistake a read
+   * that has not arrived for an element that is not there. What a subclass keeps
+   * it keeps only after a reading succeeded (see `unavailable.js`).
+   *
+   * The cue walk reads only what is already downloaded and asks the swarm for
+   * nothing. That reader is NOT given here: it is handed to
+   * {@link Container#readHeldCues} on every pass, because what is downloaded
+   * changes between passes and the container is kept for the life of the file.
+   * It used to be given here, which is why the walk had to build a second
+   * container over the same file and read its head and Cues a second time.
+   *
+   * `portionBytes` is the largest read a reading makes, stated by whoever knows
+   * the medium — a torrent's piece length. Absent, an element is read in one go.
    *
    * @param {object} params
-   * @param {(start:number,end:number)=>Promise<Buffer|null>} params.readRange
-   * @param {number} params.fileSize
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} [params.readRange]
+   * @param {number} [params.fileSize]
    * @param {string} [params.label]
-   * @param {(start:number,end:number)=>Promise<Buffer|null>} [params.readHeld]
-   * @param {(start:number,end:number)=>boolean} [params.isHeld]
+   * @param {number} [params.portionBytes]
    */
-  constructor({ readRange, fileSize, label = "", readHeld, isHeld }) {
-    this.readRange = readRange;
+  constructor({ readRange, fileSize, label = "", portionBytes } = {}) {
     this.fileSize = fileSize;
+    this.readRange = typeof readRange === "function" ? strictReader(readRange, fileSize) : readRange;
     this.label = label;
-    this.readHeld = typeof readHeld === "function" ? readHeld : readRange;
-    this.isHeld = typeof isHeld === "function" ? isHeld : () => true;
+    this.portionBytes = Number.isFinite(portionBytes) && portionBytes > 0 ? portionBytes : Number.POSITIVE_INFINITY;
   }
 
 
@@ -272,13 +268,17 @@ export class Container {
       declared,
       "subtitle",
       (track) => ({
-        // Matroska applies `eng` when Language is absent, and ffmpeg reports
-        // that default as if the file had stated it. Preserve only an explicit
-        // container value; otherwise let cue-text detection decide later.
-        language: track.declaresLanguage === true
-          ? (track.languageBcp47 || track.language || "")
-          : "",
+        // The language the container states, its default included. RFC 9559
+        // §5.1.4.1.19 gives `Language` the default `eng`, and RFC 8794
+        // §11.1.19 says an element equal to its default need not be written
+        // and that a reader MUST then read the default — so a track with no
+        // Language element is English by the file's own statement. Until
+        // 2026-10-01 that was treated as "says nothing", and an English track
+        // was offered as Unknown. Where the language came from travels beside
+        // it, so a reading of the text that disagrees can be reported.
+        language: track.languageBcp47 || track.language || "",
         declaresLanguage: track.declaresLanguage === true,
+        languageSource: typeof track.languageSource === "string" ? track.languageSource : "",
         isDefault: track.isDefault === true,
         declaresDefault: track.declaresDefault === true,
         // Read from the file rather than guessed from the track's name. Both
@@ -405,19 +405,27 @@ export class Container {
    * different evidence are a disagreement waiting to happen.
    *
    * `progress` is what has already been read, kept by the caller because it
-   * belongs to the file rather than to one pass: `walked` holds cluster
-   * positions, `harvested` holds sample offsets per track. Each container adds
-   * to the one it uses.
+   * belongs to the file rather than to one pass. Each container keeps its own
+   * part of it under its own name; nothing else reads inside.
+   *
+   * `held` is how to read what is downloaded NOW, handed in per pass: which
+   * ranges are whole, a read of one that never fetches (strict: every byte or
+   * `BytesUnavailable`), the portion a read may span, and where the viewers
+   * stand, in seconds, so the work nearest them is taken first.
    *
    * @param {object} _plan - This file's subtitle plan.
    * @param {object} _track - The track asked about.
-   * @param {{ walked: Set<number>, harvested: Map<number, Set<number>> }} _progress
-   * @returns {Promise<{ found: Map<number, object[]>, covered: number, indexed: number }>}
+   * @param {object} _progress
+   * @param {HeldReader} _held
+   * @returns {Promise<{ found: Map<number, object[]>, covered: number, indexed: number, withdrawn: number[] }>}
    *   `found` is track number to the cues found in THIS pass — Matroska fills
-   *   every track from one walk, so it is a map and not a list.
+   *   every track from one walk, so it is a map and not a list. Each cue may
+   *   carry `source`, the position it was read from; `withdrawn` lists sources
+   *   found in an earlier pass that turned out not to be what they were taken
+   *   for, whose cues the caller must take back.
    */
-  async readHeldCues(_plan, _track, _progress) {
-    return { found: new Map(), covered: 0, indexed: 0 };
+  async readHeldCues(_plan, _track, _progress, _held) {
+    return { found: new Map(), covered: 0, indexed: 0, withdrawn: [] };
   }
 
   /**
@@ -524,6 +532,21 @@ export class Container {
   }
 }
 
+/**
+ * What the cue walk may read on one pass.
+ *
+ * @typedef {object} HeldReader
+ * @property {(start: number, end: number) => boolean} isHeld - Whether the whole
+ *   inclusive range is downloaded.
+ * @property {Array<[number, number]>} ranges - The downloaded ranges, ascending.
+ * @property {(start: number, end: number) => Promise<Buffer>} read - Every byte
+ *   of a downloaded range, or `BytesUnavailable`; never fetches.
+ * @property {number} portionBytes - The largest read one step may make.
+ * @property {(() => number[]) | number[]} wantedSeconds - Where viewers stand,
+ *   in film seconds — a function, read again between clusters, so a pass can
+ *   stop when a viewer has moved.
+ */
+
 // ---------------------------------------------------------------------------
 // Lining ffmpeg's banner up with what a container declares. Here because the
 // correction is about what a CONTAINER states and the banner cannot.

package/services/media/container/ContainerFactory.js

@@ -9,6 +9,7 @@
 import { MatroskaContainer } from "./MatroskaContainer.js";
 import { Mp4Container } from "./Mp4Container.js";
 import { AviContainer } from "./AviContainer.js";
+import { strictReader } from "./unavailable.js";
 
 const SNIFF_BYTES = 16;
 
@@ -16,41 +17,22 @@ export class ContainerFactory {
   /**
    * The container these bytes are, built over them.
    *
-   * `params` is passed through whole, so a caller with a torrent's two readers
-   * gets a container that has both — see {@link Container}'s constructor.
+   * Null means the bytes were read and are none of the formats this knows — a
+   * statement about the file. Bytes that have not arrived throw
+   * `BytesUnavailable`, which is not one: until 2026-10-01 they came back as
+   * null too, and a file whose head was still downloading was remembered as
+   * being of no known format.
    *
-   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string, readHeld?: Function, isHeld?: Function }} params
+   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string, portionBytes?: number }} params
    * @returns {Promise<import("./Container.js").Container|null>}
    */
   static async create(params) {
     const { readRange, fileSize } = params;
     if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
-    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
-    if (!head) return null;
+    const head = await strictReader(readRange, fileSize)(0, Math.min(SNIFF_BYTES, fileSize) - 1);
     if (MatroskaContainer.detect(head)) return new MatroskaContainer(params);
     if (Mp4Container.detect(head)) return new Mp4Container(params);
     if (AviContainer.detect(head)) return new AviContainer(params);
     return null;
   }
-
-  /**
-   * The container a file NAME suggests, for the moment the bytes cannot be
-   * sniffed.
-   *
-   * The head of a file nobody has opened is not downloaded, and the cue walk
-   * asks the swarm for nothing — so on that one path the name is all there is.
-   * It is a fallback and never a preference: the bytes decide wherever they can
-   * be read, because a name is what somebody typed and a header is what the
-   * muxer wrote.
-   *
-   * @param {string} name
-   * @returns {typeof MatroskaContainer | typeof Mp4Container | null}
-   */
-
-  static byName(name) {
-    const text = String(name ?? "");
-    if (/\.(mp4|m4v|m4a)$/i.test(text)) return Mp4Container;
-    if (/\.(mkv|mka|webm)$/i.test(text)) return MatroskaContainer;
-    return null;
-  }
 }