@torrent-tv/proxy 2.91.0 → 2.92.0

package/services/encode/segment-formats/presentation-segment.js

@@ -0,0 +1,114 @@
+import { readTrackEdits, walkBoxes } from "./mp4-boxes.js";
+
+/** Repartition closed muxer output by presentation interval, preserving decode order. */
+export function presentationSegment(current, following, { from, to }) {
+  const own = packetsOf(current);
+  const next = following ? packetsOf(following) : null;
+  const tracks = [];
+  for (const [id, track] of own.tracks) {
+    const edit = own.edits.get(id);
+    if (!edit) throw new Error("A segment track has no declared clock.");
+    const samples = [...track.samples];
+    if (track.kind === "soun" && next?.tracks.has(id)) {
+      const nextEdit = next.edits.get(id);
+      if (!nextEdit || nextEdit.timescale !== edit.timescale) throw new Error("Adjacent segment clocks differ.");
+      for (const sample of next.tracks.get(id).samples) {
+        samples.push({ ...sample, dts: sample.dts + nextEdit.offset - edit.offset });
+      }
+    }
+    const start = BigInt(Math.round(from * Number(edit.timescale)));
+    const end = BigInt(Math.round(to * Number(edit.timescale)));
+    const selected = samples.filter(sample => {
+      const pts = sample.dts + sample.composition + edit.offset;
+      return pts < end && pts + sample.duration > start;
+    });
+    selected.sort((left, right) => left.dts < right.dts ? -1 : left.dts > right.dts ? 1 : 0);
+    if (!selected.length) throw new Error("A presentation segment lacks required media.");
+    tracks.push({ id, samples: selected });
+  }
+  const makeMoof = offset => box("moof", full("mfhd", 0, 0, u32(1)), ...tracks.map(track => {
+    const entries = track.samples.map(sample => Buffer.concat([
+      u32(Number(sample.duration)), u32(sample.bytes.length), u32(sample.flags), i32(Number(sample.composition))
+    ]));
+    const payload = Buffer.concat([u32(track.samples.length), i32(offset), ...entries]);
+    offset += track.samples.reduce((bytes, sample) => bytes + sample.bytes.length, 0);
+    const clock = Buffer.alloc(8);
+    clock.writeBigUInt64BE(track.samples[0].dts);
+    return box("traf", full("tfhd", 0, 0x20000, u32(track.id)), full("tfdt", 1, 0, clock), full("trun", 1, 0xf01, payload));
+  }));
+  const size = makeMoof(0).length;
+  return Buffer.concat([own.init, makeMoof(size + 8), box("mdat", ...tracks.flatMap(track => track.samples.map(sample => sample.bytes)))]);
+}
+
+function packetsOf(raw) {
+  const edits = readTrackEdits(raw);
+  const tracks = new Map();
+  const defaults = new Map();
+  const payloads = [];
+  walkBoxes(raw, (type, start, end) => { if (type === "mdat") payloads.push([start, end]); }, 0, raw.length, () => false);
+  let id = null, firstMoof = null;
+  walkBoxes(raw, (type, start) => {
+    if (type === "tkhd") id = raw.readUInt32BE(start + (raw[start] === 1 ? 20 : 12));
+    if (type === "hdlr" && id !== null) tracks.set(id, { kind: raw.toString("latin1", start + 8, start + 12), samples: [] });
+    if (type === "trex") defaults.set(raw.readUInt32BE(start + 4), {
+      duration: raw.readUInt32BE(start + 12), size: raw.readUInt32BE(start + 16), flags: raw.readUInt32BE(start + 20)
+    });
+  });
+  walkBoxes(raw, (type, start, end) => {
+    if (type !== "moof") return;
+    const moof = start - 8;
+    firstMoof ??= moof;
+    walkBoxes(raw, (type, trafStart, trafEnd) => {
+      if (type !== "traf") return;
+      let trackId, clock = 0n, base = moof, data = null, values;
+      walkBoxes(raw, (type, at, boxEnd) => {
+        if (type === "tfhd") {
+          const flags = raw.readUIntBE(at + 1, 3);
+          trackId = raw.readUInt32BE(at + 4);
+          values = { ...defaults.get(trackId) };
+          let cursor = at + 8;
+          if (flags & 1) { base = Number(raw.readBigUInt64BE(cursor)); cursor += 8; }
+          if (flags & 2) cursor += 4;
+          for (const [flag, field] of [[8, "duration"], [16, "size"], [32, "flags"]]) {
+            if (flags & flag) { values[field] = raw.readUInt32BE(cursor); cursor += 4; }
+          }
+        } else if (type === "tfdt") {
+          clock = raw[at] === 1 ? raw.readBigUInt64BE(at + 4) : BigInt(raw.readUInt32BE(at + 4));
+        } else if (type === "trun") {
+          if (!tracks.has(trackId) || !values) throw new Error("Fragment refers to an undeclared track.");
+          const flags = raw.readUIntBE(at + 1, 3), count = raw.readUInt32BE(at + 4);
+          let cursor = at + 8, firstFlags = null;
+          if (flags & 1) { data = base + raw.readInt32BE(cursor); cursor += 4; }
+          if (flags & 4) { firstFlags = raw.readUInt32BE(cursor); cursor += 4; }
+          if (data === null) throw new Error("Fragment has no explicit payload location.");
+          for (let index = 0; index < count; index++) {
+            const sample = { ...values, composition: 0n, dts: clock };
+            if (index === 0 && firstFlags !== null) sample.flags = firstFlags;
+            for (const [flag, field] of [[0x100, "duration"], [0x200, "size"], [0x400, "flags"], [0x800, "composition"]]) {
+              if (flags & flag) {
+                if (cursor + 4 > boxEnd) throw new Error("Fragment sample declaration is truncated.");
+                sample[field] = field === "composition" ? BigInt(raw[at] === 1 ? raw.readInt32BE(cursor) : raw.readUInt32BE(cursor)) : raw.readUInt32BE(cursor);
+                cursor += 4;
+              }
+            }
+            if (!(sample.duration > 0) || !(sample.size > 0) || !Number.isSafeInteger(data) ||
+              !payloads.some(([start, end]) => data >= start && data + sample.size <= end)) throw new Error("Fragment sample bytes are incomplete.");
+            sample.duration = BigInt(sample.duration);
+            sample.bytes = raw.subarray(data, data + sample.size);
+            tracks.get(trackId).samples.push(sample);
+            data += sample.size;
+            clock += sample.duration;
+          }
+        }
+      }, trafStart, trafEnd, () => false);
+    }, start, end, () => false);
+  }, 0, raw.length, () => false);
+  if (firstMoof === null) throw new Error("A closed segment has no fragments.");
+  if (tracks.size === 0 || [...tracks.values()].some(track => track.samples.length === 0)) throw new Error("A closed segment lacks declared track samples.");
+  return { init: raw.subarray(0, firstMoof), edits, tracks };
+}
+
+function box(type, ...parts) { const payload = Buffer.concat(parts); return Buffer.concat([u32(payload.length + 8), Buffer.from(type), payload]); }
+function full(type, version, flags, payload) { const header = Buffer.alloc(4); header[0] = version; header.writeUIntBE(flags, 1, 3); return box(type, header, payload); }
+function u32(value) { const bytes = Buffer.alloc(4); bytes.writeUInt32BE(value); return bytes; }
+function i32(value) { const bytes = Buffer.alloc(4); bytes.writeInt32BE(value); return bytes; }

package/services/media/ContainerOrchestrator.js

@@ -16,7 +16,8 @@
  */
 
 import { ContainerFactory } from "./container/ContainerFactory.js";
-import { isUnavailable } from "./container/unavailable.js";
+import { BytesUnavailable, isUnavailable } from "./container/unavailable.js";
+import { IndexMemoryUnavailable } from "./container/memory-unavailable.js";
 import { logger } from "../../utils/logger.js";
 
 /**
@@ -29,6 +30,12 @@ import { logger } from "../../utils/logger.js";
 export const CONTAINER_HEAD_BYTES = 256 * 1024;
 
 export class ContainerOrchestrator {
+  #reads = new Map();
+  #lifetimes = new Map();
+  #activityEpoch = 0;
+  #activeReads = 0;
+
+  activity() { return { epoch: this.#activityEpoch, active: this.#activeReads > 0 }; }
   constructor() {
     /** @type {Map<string, import("./container/Container.js").Container|null>} */
     this.cache = new Map();
@@ -60,6 +67,93 @@ export class ContainerOrchestrator {
     return this.cache.get(`${sourceKey}:${fileIndex}`);
   }
 
+  packetIndexBytes() {
+    return [...new Set(this.cache.values())].reduce((bytes, container) => bytes + (container?.packetIndexBytes?.() ?? 0), 0);
+  }
+
+  /** Read one statement without converting missing bytes into an empty answer. */
+  async inspect(params, statement = "tracks") {
+    if (!["container", "tracks", "media-info", "keyframes", "packets"].includes(statement)) {
+      throw new TypeError(`Unknown media statement: ${statement}`);
+    }
+    const key = `${params.sourceKey}:${params.fileIndex}`;
+    let lifetime = this.#lifetimes.get(key);
+    if (!lifetime) this.#lifetimes.set(key, lifetime = {});
+    const isCurrent = () => this.#lifetimes.get(key) === lifetime && params.isCurrent?.() !== false;
+    const previous = this.#reads.get(key) ?? Promise.resolve();
+    const reading = previous.catch(() => undefined).then(async () => {
+      if (!isCurrent()) return { result: { kind: "terminal", reason: "request-obsolete", requestId: params.requestId } };
+      const revision = params.onReadStart?.(statement);
+      const result = await this.#inspectRead({ ...params, isCurrent }, statement);
+      return { result, revision };
+    });
+    this.#reads.set(key, reading);
+    try {
+      const { result, revision } = await reading;
+      if (!isCurrent()) return { kind: "terminal", reason: "request-obsolete", requestId: params.requestId };
+      if (result.kind === "needs-ranges") params.onNeedsRanges?.(result);
+      if (statement === "tracks" && result.kind === "result") params.onTracks?.(result.value);
+      await params.onReadResult?.(statement, result, revision);
+      return result;
+    } finally {
+      if (this.#reads.get(key) === reading) this.#reads.delete(key);
+    }
+  }
+
+  async #inspectRead(params, statement) {
+    const requestId = params.requestId ?? `${params.sourceKey}:${params.fileIndex}:${statement}`;
+    this.#activityEpoch++;
+    this.#activeReads++;
+    try {
+      const container = await this.containerFor(params);
+      if (!container) {
+        const result = { kind: "terminal", reason: "format-not-supported", requestId };
+        logger.info(`media request=${requestId} terminal=${result.reason}`);
+        return result;
+      }
+      let value;
+      if (statement === "container") {
+        value = container;
+      } else if (statement === "tracks") {
+        const key = `${params.sourceKey}:${params.fileIndex}`;
+        value = this.tracks.get(key);
+        if (!value) {
+          value = await container.readTracks();
+          if (!Array.isArray(value)) throw new Error("Container did not return a track table.");
+          if (params.isCurrent?.() === false) return { kind: "terminal", reason: "request-obsolete", requestId };
+          this.tracks.set(key, value);
+        }
+      } else if (statement === "media-info") {
+        value = await container.readMediaInfo();
+      } else if (statement === "keyframes") {
+        value = await container.readKeyframeIndex();
+      } else if (statement === "packets") {
+        value = await container.readPacketIndex(params.packetInterval);
+        await value?.prepareAudioDependencies?.(params.packetInterval, container.readRange);
+      } else {
+        throw new TypeError(`Unknown media statement: ${statement}`);
+      }
+      return { kind: "result", value, requestId };
+    } catch (error) {
+      if (error instanceof IndexMemoryUnavailable) {
+        const result = { kind: "needs-memory", bytes: error.bytes, requestId };
+        logger.info(`media request=${requestId} needs memory=${error.bytes}`);
+        return result;
+      }
+      if (isUnavailable(error)) {
+        const result = { kind: "needs-ranges", ranges: [[error.start, error.end]], requestId };
+        logger.info(`media request=${requestId} needs bytes=${error.start}-${error.end}`);
+        return result;
+      }
+      const result = { kind: "terminal", reason: "media-read-failed", message: error?.message ?? String(error), requestId };
+      logger.warn(`media request=${requestId} terminal=${result.reason}: ${result.message}`);
+      return result;
+    } finally {
+      this.#activeReads--;
+      this.#activityEpoch++;
+    }
+  }
+
   /**
    * The file's one container, built on first ask.
    *
@@ -74,12 +168,13 @@ export class ContainerOrchestrator {
    * @throws {import("./container/unavailable.js").BytesUnavailable} While the
    *   head has not arrived. Nothing is kept for it.
    */
-  async containerFor({ sourceKey, fileIndex, readRange, fileSize, label = "", portionBytes }) {
+  async containerFor({ sourceKey, fileIndex, readRange, fileSize, label = "", portionBytes, probe, packetMemory }) {
     const key = `${sourceKey}:${fileIndex}`;
     if (this.cache.has(key)) return this.cache.get(key);
     if (this.pending.has(key)) return this.pending.get(key);
-    const p = ContainerFactory.create({ readRange, fileSize, label, portionBytes })
+    const p = ContainerFactory.create({ readRange, fileSize, label, portionBytes, probe, packetMemory })
       .then((c) => {
+        if (this.pending.get(key) !== p) throw new Error("Container request was withdrawn.");
         this.cache.set(key, c);
         if (c) logger.info(`container: ${c.formatName} for "${label}"`);
         else logger.info(`container: unknown for "${label}"`);
@@ -92,7 +187,7 @@ export class ContainerOrchestrator {
         throw e;
       })
       .finally(() => {
-        this.pending.delete(key);
+        if (this.pending.get(key) === p) this.pending.delete(key);
       });
     this.pending.set(key, p);
     return p;
@@ -106,13 +201,8 @@ export class ContainerOrchestrator {
    * @returns {Promise<import("./container/Container.js").Container|null>}
    */
   async getContainer(params) {
-    try {
-      return await this.containerFor(params);
-    } catch {
-      // `containerFor` has already said what failed, where it was not a
-      // shortage of bytes; either way nothing was kept.
-      return null;
-    }
+    const result = await this.inspect(params, "container");
+    return result.kind === "result" ? result.value : null;
   }
 
   /**
@@ -121,26 +211,8 @@ export class ContainerOrchestrator {
    *   the bytes have not arrived; that empty answer is not kept.
    */
   async getTracks(params) {
-    const key = `${params.sourceKey}:${params.fileIndex}`;
-    const known = this.tracks.get(key);
-    if (known) {
-      return known;
-    }
-    try {
-      const container = await this.containerFor(params);
-      if (!container) return [];
-      const tracks = await container.readTracks();
-      if (Array.isArray(tracks)) {
-        this.tracks.set(key, tracks);
-        return tracks;
-      }
-      return [];
-    } catch (e) {
-      if (!isUnavailable(e)) {
-        logger.warn(`container: readTracks failed for "${params.label}": ${e?.message ?? e}`);
-      }
-      return [];
-    }
+    const result = await this.inspect(params, "tracks");
+    return result.kind === "result" ? result.value : [];
   }
 
   /**
@@ -155,16 +227,8 @@ export class ContainerOrchestrator {
    * @returns {Promise<import("./container/Container.js").ContainerMediaInfo|null>}
    */
   async getMediaInfo(params) {
-    try {
-      const container = await this.containerFor(params);
-      if (!container) return null;
-      return await container.readMediaInfo();
-    } catch (e) {
-      if (!isUnavailable(e)) {
-        logger.warn(`container: readMediaInfo failed for "${params.label}": ${e?.message ?? e}`);
-      }
-      return null;
-    }
+    const result = await this.inspect(params, "media-info");
+    return result.kind === "result" ? result.value : null;
   }
 
   /**
@@ -176,17 +240,23 @@ export class ContainerOrchestrator {
    *   not record "no keyframes" for a file whose index is still downloading.
    */
   async getKeyframeIndex(params) {
-    const container = await this.containerFor(params);
-    if (!container) return null;
-    try {
-      return await container.readKeyframeIndex();
-    } catch (e) {
-      if (isUnavailable(e)) throw e;
-      return null;
+    const result = await this.inspect(params, "keyframes");
+    if (result.kind === "needs-memory") throw new IndexMemoryUnavailable(result.bytes);
+    if (result.kind === "needs-ranges") {
+      const [start, end] = result.ranges[0];
+      throw new BytesUnavailable(start, end, 0);
     }
+    return result.kind === "result" ? result.value : null;
   }
 
   forget(sourceKey, fileIndex) {
+    const prefix = `${sourceKey}:`;
+    for (const key of this.#lifetimes.keys()) {
+      if (fileIndex === undefined ? key.startsWith(prefix) : key === `${sourceKey}:${fileIndex}`) {
+        this.#lifetimes.delete(key);
+        this.#reads.delete(key);
+      }
+    }
     if (fileIndex === undefined) {
       for (const k of [...this.cache.keys()]) if (k.startsWith(`${sourceKey}:`)) this.cache.delete(k);
       for (const k of [...this.pending.keys()]) if (k.startsWith(`${sourceKey}:`)) this.pending.delete(k);

package/services/media/KeyframeTables.js

@@ -1,69 +1,9 @@
-/**
- * @file Reading the keyframe table of a file: once, whoever asks, with a bound
- * on how long anybody waits for it.
- *
- * The table itself is `container/KeyframeTable.js`, one object per file. This is
- * the policy around filling it in, and it is a policy because three things had
- * to be true at once and each of them was learned from a field session:
- *
- * 1. **once per file, and one WAIT per file.** Two sessions created in the same
- *    moment used to miss the cache together and read the table twice — which is
- *    what two viewers opening one film do, measured 13 ms apart on 2026-09-03.
- *    Whoever asks second joins the read already running;
- * 2. **the wait is bounded, the READ is not.** A picture cannot be copied
- *    without the table, so the answer to "not yet" is to re-encode — but the
- *    read goes on, lands in the file's own table, and is there for whoever holds
- *    it. Cancelling it would make every later viewer pay the whole wait again;
- * 3. **a read that THREW is not an answer.** "The head is not downloaded" says
- *    nothing about the file; turning it into "this file has no keyframes" makes
- *    every picture of it a re-encode for as long as the process lives. Bytes
- *    that have not arrived reach here as `BytesUnavailable` — until 2026-10-01
- *    they came back as a reading of no times, which `KeyframeTable.learn`
- *    records as answered, so point 3 held only for reads that crashed. When
- *    pieces of such a file arrive the read is made again
- *    (`readAgainIfUnanswered`), and its answer lands in the same table.
- *
- * **What it does NOT know.** Where the bytes come from. The reader is one
- * function handed in at construction — on this proxy it crosses to the torrent
- * thread, where one container per file answers the track table and the media
- * info from the same header — so this can be exercised with plain values alone.
- * It used to live in the session manager, which also carried a SECOND reader
- * that fetched the file over the proxy's own HTTP and parsed it there: a
- * transport inside a layer that must not have one, and a second answer to a
- * question with one owner.
- *
- * **Why this is not `ContainerOrchestrator`.** Both live on the main thread
- * (the parse moved there on 2026-09-15). That one holds the file's one
- * container, which keeps its own reading of the Cues table; this keeps the
- * ANSWER the sessions hold — the keyframe times taken from that reading, and
- * the wait around it, which a container cannot have because it does not know
- * there is a viewer.
- */
+/** One shared keyframe table per source file. Reads use available bytes only. */
 
 import { KeyframeTable } from "./container/KeyframeTable.js";
 import { isUnavailable } from "./container/unavailable.js";
 import { logger as defaultLogger } from "../../utils/logger.js";
 
-/**
- * How long anybody waits for the table before giving up on copying the picture.
- *
- * Measured on the addon host, 2026-09-04, over seventeen files from
- * `Dropbox/trn` — four containers, pieces from 0.25 to 16 MB, files from 0.36 to
- * 20 GB, each torrent registered fresh so nothing of it was downloaded
- * (`research/keyframe-table-read-2026-09-04.md`). Every table that arrived did
- * so within 24.8 s, most within half a second; the two files that answered
- * nothing took 120.9 s and 120.5 s.
- *
- * Those two figures are not a coincidence and they are what fixes this one:
- * they are TWO of the bound the read already has — `READ_ABANDON_MS` in
- * `torrent/worker/resume-warm.js`, one for the wait on the file's edges and
- * one for the read itself, in series. A caller waiting for two of them is the
- * defect; waiting for one is the bound, and it leaves 2.4x over the slowest
- * table that did arrive. The line printed when it fires names which case
- * happened, so the field can move it rather than an argument.
- */
-export const KEYFRAME_TABLE_BUDGET_MS = 60_000;
-
 export class KeyframeTables {
   /** One per file, handed out rather than copied. @type {Map<string, KeyframeTable>} */
   #byFile = new Map();
@@ -74,9 +14,6 @@ export class KeyframeTables {
   /** @type {((params: { sourceKey: string, fileIndex: number }) => Promise<object | null>) | null} */
   #readTable;
 
-  /** @type {number} */
-  #budgetMs;
-
   /** @type {{ info: Function, warn: Function }} */
   #logger;
 
@@ -85,13 +22,10 @@ export class KeyframeTables {
    * @param {(params: { sourceKey: string, fileIndex: number }) => Promise<object | null>} [params.readTable] -
    *   Whatever can answer what this file's container states. The whole of this
    *   object's outside world.
-   * @param {number} [params.budgetMs] - How long `within` waits.
    * @param {{ info: Function, warn: Function }} [params.logger]
    */
-  constructor({ readTable = null, budgetMs = KEYFRAME_TABLE_BUDGET_MS, logger = defaultLogger } = {}) {
+  constructor({ readTable = null, logger = defaultLogger } = {}) {
     this.#readTable = typeof readTable === "function" ? readTable : null;
-    const declared = Number(budgetMs);
-    this.#budgetMs = Number.isFinite(declared) && declared > 0 ? declared : KEYFRAME_TABLE_BUDGET_MS;
     this.#logger = logger;
   }
 
@@ -104,11 +38,6 @@ export class KeyframeTables {
     return `${sourceKey}:${fileIndex}`;
   }
 
-  /** How long a caller of `within` waits. @returns {number} */
-  get budgetMs() {
-    return this.#budgetMs;
-  }
-
   /**
    * This file's table — the one object everyone reading it holds.
    *
@@ -173,6 +102,7 @@ export class KeyframeTables {
     }
     const work = started
       .then((reading) => {
+        if (this.#byFile.get(key) !== table) throw new DOMException("Keyframe request was withdrawn.", "AbortError");
         table.learn({
           times: Array.isArray(reading?.times) ? reading.times : null,
           tolerance: reading?.tolerance,
@@ -202,7 +132,7 @@ export class KeyframeTables {
         throw error;
       })
       .finally(() => {
-        this.#reading.delete(key);
+        if (this.#reading.get(key) === work) this.#reading.delete(key);
       });
     this.#reading.set(key, work);
     return work;
@@ -247,47 +177,15 @@ export class KeyframeTables {
     void this.warm(params);
   }
 
-  /**
-   * The same read, with a bound on how long THIS caller waits for it.
-   *
-   * The read is not cancelled when the bound is reached — it goes on, and it
-   * lands in the table this returns, which is the file's own. What the bound
-   * decides is only whether this caller waits: a copied picture cannot be cut
-   * without the table, so the answer to "not yet" is to re-encode, which needs
-   * no table because it places the keyframes itself.
-   *
-   * @param {{ sourceKey: string, fileIndex: number, logName?: string }} params
-   * @returns {Promise<{ table: KeyframeTable, arrived: boolean }>} `arrived` is
-   *   about THIS wait. False with an unanswered table means the read is still
-   *   running, or found the bytes not downloaded yet and will be made again
-   *   when they arrive — neither is the same as a file with no keyframes.
-   */
+  /** Available-byte reads do not replace copying after elapsed time. */
   async within(params) {
-    const read = this.read(params);
-    let timer = null;
-    const budget = new Promise((resolve) => {
-      timer = setTimeout(() => resolve(null), this.#budgetMs);
-      // A caller must not be held open by this timer alone.
-      timer?.unref?.();
-    });
-    // Bytes not downloaded yet are "not arrived" to this caller: the table
-    // stays unanswered and is read again when pieces of the file arrive.
-    // Thrown out of here, a shortage of bytes would fail the opening of an
-    // output. Any other failure is still the caller's to see.
-    const answer = await Promise.race([
-      read.then(
-        (table) => ({ table, arrived: true }),
-        (error) => {
-          if (isUnavailable(error)) {
-            return { table: this.of(params), arrived: false };
-          }
-          throw error;
-        }
-      ),
-      budget
-    ]);
-    clearTimeout(timer);
-    return answer ?? { table: this.of(params), arrived: false };
+    try {
+      const table = await this.read(params);
+      return { table, arrived: table.answered };
+    } catch (error) {
+      if (isUnavailable(error)) return { table: this.of(params), arrived: false };
+      throw error;
+    }
   }
 
   /**
@@ -342,11 +240,14 @@ export class KeyframeTables {
       for (const key of [...this.#byFile.keys()]) {
         if (key.startsWith(`${sourceKey}:`)) {
           this.#byFile.delete(key);
+          this.#reading.delete(key);
         }
       }
       return;
     }
-    this.#byFile.delete(KeyframeTables.keyFor(sourceKey, fileIndex));
+    const key = KeyframeTables.keyFor(sourceKey, fileIndex);
+    this.#byFile.delete(key);
+    this.#reading.delete(key);
   }
 
   /** @returns {number} */

package/services/media/MediaReadRequests.js

@@ -0,0 +1,120 @@
+/** Retry unfinished statements when their missing resource changes. */
+export class MediaReadRequests {
+  #requests = new Map();
+  #read;
+  #failed;
+  #versions = new Map();
+  #listeners = new Map();
+  #memoryVersion = 0;
+
+  memoryRevision() { return this.#memoryVersion; }
+
+  subscribe(sourceKey, fileIndex, listener) {
+    const key = `${sourceKey}:${fileIndex}`;
+    let listeners = this.#listeners.get(key);
+    if (!listeners) this.#listeners.set(key, listeners = new Set());
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+      if (!listeners.size) this.#listeners.delete(key);
+    };
+  }
+
+  #notify(sourceKey, fileIndex, result) {
+    for (const listener of [...(this.#listeners.get(`${sourceKey}:${fileIndex}`) ?? [])]) listener(result);
+  }
+
+  constructor({ read, failed }) {
+    this.#read = read;
+    this.#failed = failed;
+  }
+
+  revision(sourceKey, fileIndex) {
+    return this.#versions.get(`${sourceKey}:${fileIndex}`) ?? 0;
+  }
+
+  record(params, statement, result, revision = this.revision(params.sourceKey, params.fileIndex), memoryRevision = this.#memoryVersion) {
+    const key = requestKey(params, statement);
+    if (!["needs-ranges", "needs-memory"].includes(result.kind)) {
+      this.#notify(params.sourceKey, params.fileIndex, result);
+      return this.#requests.delete(key);
+    }
+    const existing = this.#requests.get(key);
+    if (existing) { existing.params = params; existing.kind = result.kind; }
+    else this.#requests.set(key, { params, statement, kind: result.kind, running: false, changed: false });
+    const request = this.#requests.get(key);
+    // A read can change from missing memory to missing bytes. An event for
+    // its previous resource cannot authorize another read of unchanged bytes.
+    request.changed = result.kind === "needs-memory"
+      ? memoryRevision !== this.#memoryVersion : revision !== this.revision(params.sourceKey, params.fileIndex);
+    if (request.changed) {
+      if (!request.running) queueMicrotask(() => { if (!request.running) void this.#retry(request); });
+    }
+  }
+
+  memoryChanged() {
+    this.#memoryVersion++;
+    for (const request of this.#requests.values()) {
+      if (request.kind !== "needs-memory") continue;
+      // The retried statement announces its result. A memory event is not a
+      // source change for another statement still waiting for missing bytes.
+      request.changed = true;
+      if (!request.running) void this.#retry(request);
+    }
+  }
+
+  bytesChanged(sourceKey, fileIndex) {
+    const fileKey = `${sourceKey}:${fileIndex}`;
+    this.#versions.set(fileKey, this.revision(sourceKey, fileIndex) + 1);
+    this.#notify(sourceKey, fileIndex, { kind: "bytes-changed" });
+    for (const request of this.#requests.values()) {
+      if (request.params.sourceKey !== sourceKey || request.params.fileIndex !== fileIndex) continue;
+      if (request.kind !== "needs-ranges") continue;
+      request.changed = true;
+      if (!request.running) void this.#retry(request);
+    }
+  }
+
+  forget(sourceKey, fileIndex) {
+    for (const key of [...this.#listeners.keys()]) {
+      if (fileIndex === undefined ? key.startsWith(`${sourceKey}:`) : key === `${sourceKey}:${fileIndex}`) {
+        for (const listener of [...this.#listeners.get(key)]) listener({ kind: "cancelled", reason: "source-forgotten" });
+        this.#listeners.delete(key);
+      }
+    }
+    for (const [key, request] of this.#requests) {
+      if (request.params.sourceKey === sourceKey && (fileIndex === undefined || request.params.fileIndex === fileIndex)) {
+        this.#requests.delete(key);
+      }
+    }
+    for (const key of this.#versions.keys()) {
+      if (fileIndex === undefined ? key.startsWith(`${sourceKey}:`) : key === `${sourceKey}:${fileIndex}`) this.#versions.delete(key);
+    }
+  }
+
+  retain(sourceKey, fileIndex, wanted) {
+    for (const [key, request] of this.#requests) {
+      if (request.params.sourceKey === sourceKey && request.params.fileIndex === fileIndex &&
+        !wanted(request.params, request.statement)) this.#requests.delete(key);
+    }
+  }
+
+  async #retry(request) {
+    request.running = true;
+    const key = requestKey(request.params, request.statement);
+    try {
+      while (request.changed && this.#requests.get(key) === request) {
+        request.changed = false;
+        await this.#read(request.params, request.statement);
+      }
+    } catch (error) {
+      this.#failed?.(request.params, request.statement, error);
+    } finally {
+      request.running = false;
+    }
+  }
+}
+
+function requestKey(params, statement) {
+  return JSON.stringify([params.sourceKey, params.fileIndex, statement, params.requestId ?? null]);
+}