@torrent-tv/proxy 2.88.6 → 2.89.0

package/test/helpers/matroska-file.js

@@ -0,0 +1,296 @@
+/**
+ * @file Synthetic Matroska files for the checks — built element by element,
+ * so every check states exactly what the file says and where.
+ *
+ * Positions inside the Segment are known only after the elements before them
+ * are built, so a file is described as a list of top-level elements, and the
+ * SeekHead and Cues that point at others are built from the lengths of the
+ * rest (all positions are fixed-width, so they do not change the lengths they
+ * are computed from).
+ */
+
+import { crc32 } from "node:zlib";
+
+export const ID = {
+  EBML: 0x1a45dfa3,
+  SEGMENT: 0x18538067,
+  SEEK_HEAD: 0x114d9b74,
+  SEEK: 0x4dbb,
+  SEEK_ID: 0x53ab,
+  SEEK_POSITION: 0x53ac,
+  INFO: 0x1549a966,
+  TIMESTAMP_SCALE: 0x2ad7b1,
+  TRACKS: 0x1654ae6b,
+  TRACK_ENTRY: 0xae,
+  TRACK_NUMBER: 0xd7,
+  TRACK_TYPE: 0x83,
+  CODEC_ID: 0x86,
+  LANGUAGE: 0x22b59c,
+  LANGUAGE_BCP47: 0x22b59d,
+  NAME: 0x536e,
+  CUES: 0x1c53bb6b,
+  CUE_POINT: 0xbb,
+  CUE_TIME: 0xb3,
+  CUE_TRACK_POSITIONS: 0xb7,
+  CUE_TRACK: 0xf7,
+  CUE_CLUSTER_POSITION: 0xf1,
+  CLUSTER: 0x1f43b675,
+  TIMESTAMP: 0xe7,
+  CRC32: 0xbf,
+  SIMPLE_BLOCK: 0xa3,
+  BLOCK_GROUP: 0xa0,
+  BLOCK: 0xa1,
+  BLOCK_DURATION: 0x9b,
+  VOID: 0xec
+};
+
+/** @param {number} id @returns {Buffer} */
+export function idBytes(id) {
+  const bytes = [];
+  let rest = id;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  }
+  return Buffer.from(bytes);
+}
+
+/** A four-byte size: a valid vint whatever the payload. @param {number} size */
+function sizeBytes(size) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(size, 0);
+  buffer[0] |= 0x10;
+  return buffer;
+}
+
+/** @param {number} id @param {Buffer} payload @returns {Buffer} */
+export function element(id, payload) {
+  return Buffer.concat([idBytes(id), sizeBytes(payload.length), payload]);
+}
+
+/** An element whose size field says "unknown" (one byte, all value bits set). */
+export function unknownSizeElement(id, payload) {
+  return Buffer.concat([idBytes(id), Buffer.from([0xff]), payload]);
+}
+
+/** @param {number} id @param {number} value */
+export function uintElement(id, value) {
+  const bytes = [];
+  let rest = value;
+  do {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  } while (rest > 0);
+  return element(id, Buffer.from(bytes));
+}
+
+/** A fixed-width unsigned integer, so a position computed twice keeps its length. */
+export function uint32Element(id, value) {
+  const payload = Buffer.alloc(4);
+  payload.writeUInt32BE(value, 0);
+  return element(id, payload);
+}
+
+/** @param {number} id @param {string} value */
+export function stringElement(id, value) {
+  return element(id, Buffer.from(value, "utf8"));
+}
+
+/**
+ * @param {{ number: number, type: number, codecId: string, language?: string | null, languageBcp47?: string, name?: string }} track
+ * @returns {Buffer}
+ */
+export function trackEntry({ number, type, codecId, language = null, languageBcp47 = "", name = "" }) {
+  const parts = [uintElement(ID.TRACK_NUMBER, number), uintElement(ID.TRACK_TYPE, type), stringElement(ID.CODEC_ID, codecId)];
+  if (language !== null) {
+    parts.push(stringElement(ID.LANGUAGE, language));
+  }
+  if (languageBcp47) {
+    parts.push(stringElement(ID.LANGUAGE_BCP47, languageBcp47));
+  }
+  if (name) {
+    parts.push(stringElement(ID.NAME, name));
+  }
+  return element(ID.TRACK_ENTRY, Buffer.concat(parts));
+}
+
+/**
+ * One cue, as a BlockGroup carrying its own duration.
+ *
+ * @param {{ track: number, relativeTicks: number, durationTicks: number, text: string }} params
+ */
+export function cueBlock({ track, relativeTicks, durationTicks, text }) {
+  const header = Buffer.alloc(4);
+  header[0] = 0x80 | track;
+  header.writeInt16BE(relativeTicks, 1);
+  header[3] = 0;
+  const block = element(ID.BLOCK, Buffer.concat([header, Buffer.from(text, "utf8")]));
+  return element(ID.BLOCK_GROUP, Buffer.concat([block, uintElement(ID.BLOCK_DURATION, durationTicks)]));
+}
+
+/**
+ * A picture block: a SimpleBlock of `payload` bytes on `track`.
+ *
+ * @param {{ track: number, payload: Buffer }} params
+ */
+export function pictureBlock({ track, payload }) {
+  const header = Buffer.alloc(4);
+  header[0] = 0x80 | track;
+  header.writeInt16BE(0, 1);
+  header[3] = 0x80;
+  return element(ID.SIMPLE_BLOCK, Buffer.concat([header, payload]));
+}
+
+/**
+ * A cluster's DATA: its Timestamp (optionally after a CRC-32) and its blocks.
+ *
+ * @param {{ ticks: number, blocks: Buffer[], crc?: boolean | "wrong" }} params
+ * @returns {Buffer}
+ */
+export function clusterData({ ticks, blocks, crc = false }) {
+  const rest = Buffer.concat([uintElement(ID.TIMESTAMP, ticks), ...blocks]);
+  if (!crc) {
+    return rest;
+  }
+  const value = Buffer.alloc(4);
+  value.writeUInt32LE(crc === "wrong" ? (crc32(rest) ^ 0xffffffff) >>> 0 : crc32(rest), 0);
+  return Buffer.concat([Buffer.concat([idBytes(ID.CRC32), Buffer.from([0x84]), value]), rest]);
+}
+
+/**
+ * A whole file.
+ *
+ * `clusters` are each `{ data, unknownSize? }`. `cues` says which tracks the
+ * Cues table names for every cluster: an array of track numbers, or null for
+ * no Cues element at all. `cuesBeforeClusters` puts the Cues element ahead of
+ * the clusters with no SeekHead entry for it.
+ *
+ * @param {object} params
+ * @param {Buffer[]} params.tracks - TrackEntry elements.
+ * @param {Array<{ data: Buffer, unknownSize?: boolean, ticks: number }>} params.clusters
+ * @param {number[] | null} [params.cues]
+ * @param {boolean} [params.cuesBeforeClusters]
+ * @returns {{ file: Buffer, clusterAt: number[], cuesAt: number | null, segmentDataOffset: number }}
+ */
+export function buildMatroska({ tracks, clusters, cues = [], cuesBeforeClusters = false }) {
+  const info = element(ID.INFO, uintElement(ID.TIMESTAMP_SCALE, 1_000_000));
+  const tracksElement = element(ID.TRACKS, Buffer.concat(tracks));
+  const clusterElements = clusters.map((cluster) =>
+    cluster.unknownSize ? unknownSizeElement(ID.CLUSTER, cluster.data) : element(ID.CLUSTER, cluster.data)
+  );
+
+  const cuesWith = (positions) =>
+    cues === null
+      ? Buffer.alloc(0)
+      : element(
+          ID.CUES,
+          Buffer.concat(
+            clusters.map((cluster, index) =>
+              element(
+                ID.CUE_POINT,
+                Buffer.concat([
+                  uint32Element(ID.CUE_TIME, cluster.ticks),
+                  ...cues.map((track) =>
+                    element(
+                      ID.CUE_TRACK_POSITIONS,
+                      Buffer.concat([uintElement(ID.CUE_TRACK, track), uint32Element(ID.CUE_CLUSTER_POSITION, positions[index])])
+                    )
+                  )
+                ])
+              )
+            )
+          )
+        );
+  const seekEntry = (targetId, position) =>
+    element(ID.SEEK, Buffer.concat([element(ID.SEEK_ID, idBytes(targetId)), uint32Element(ID.SEEK_POSITION, position)]));
+  const seekHeadWith = (infoAt, tracksAt, cuesAt) =>
+    element(
+      ID.SEEK_HEAD,
+      Buffer.concat([
+        seekEntry(ID.INFO, infoAt),
+        seekEntry(ID.TRACKS, tracksAt),
+        ...(cues !== null && !cuesBeforeClusters ? [seekEntry(ID.CUES, cuesAt)] : [])
+      ])
+    );
+
+  const zeros = clusters.map(() => 0);
+  const headLength = seekHeadWith(0, 0, 0).length;
+  const infoAt = headLength;
+  const tracksAt = infoAt + info.length;
+  const cuesLength = cuesWith(zeros).length;
+  const firstClusterAt = tracksAt + tracksElement.length + (cuesBeforeClusters ? cuesLength : 0);
+  const positions = [];
+  let at = firstClusterAt;
+  for (const cluster of clusterElements) {
+    positions.push(at);
+    at += cluster.length;
+  }
+  const cuesAt = cues === null ? null : cuesBeforeClusters ? tracksAt + tracksElement.length : at;
+  const parts = [seekHeadWith(infoAt, tracksAt, cuesAt ?? 0), info, tracksElement];
+  if (cuesBeforeClusters) {
+    parts.push(cuesWith(positions));
+  }
+  parts.push(...clusterElements);
+  if (!cuesBeforeClusters) {
+    parts.push(cuesWith(positions));
+  }
+  const payload = Buffer.concat(parts);
+  const ebml = element(ID.EBML, Buffer.from([0x42, 0x86, 0x81, 0x01]));
+  const segment = element(ID.SEGMENT, payload);
+  const segmentDataOffset = ebml.length + segment.length - payload.length;
+  return {
+    file: Buffer.concat([ebml, segment]),
+    clusterAt: positions.map((position) => segmentDataOffset + position),
+    cuesAt: cuesAt === null ? null : segmentDataOffset + cuesAt,
+    segmentDataOffset
+  };
+}
+
+/**
+ * A reader over a buffer that answers null for the ranges a check says are
+ * not here, and records every range asked for.
+ *
+ * @param {Buffer} bytes
+ * @param {{ missing?: (start: number, end: number) => boolean, short?: boolean }} [options]
+ */
+export function readerOver(bytes, options = {}) {
+  const reads = [];
+  const read = async (start, end) => {
+    reads.push({ start, end });
+    if (options.missing?.(start, end)) {
+      return null;
+    }
+    const slice = bytes.subarray(start, end + 1);
+    return options.short ? slice.subarray(0, Math.max(0, slice.length - 1)) : Buffer.from(slice);
+  };
+  return { read, reads };
+}
+
+/**
+ * What the cue walk may read: the held ranges, a strict read of them, a
+ * portion and where viewers stand.
+ *
+ * @param {Buffer} bytes
+ * @param {Array<[number, number]>} ranges
+ * @param {{ portionBytes?: number, wantedSeconds?: number[], reads?: Array<{ start: number, end: number }> }} [options]
+ * @returns {import("../../services/media/container/Container.js").HeldReader}
+ */
+export function heldOver(bytes, ranges, options = {}) {
+  const holds = (start, end) => ranges.some(([from, to]) => start >= from && end <= to);
+  return {
+    ranges,
+    isHeld: (start, end) => holds(start, Math.min(end, bytes.length - 1)),
+    read: async (start, end) => {
+      options.reads?.push({ start, end });
+      const last = Math.min(end, bytes.length - 1);
+      if (!holds(start, last)) {
+        const error = new Error(`bytes ${start}-${last} are not available yet`);
+        error.name = "BytesUnavailable";
+        throw error;
+      }
+      return Buffer.from(bytes.subarray(start, last + 1));
+    },
+    portionBytes: options.portionBytes ?? Number.POSITIVE_INFINITY,
+    wantedSeconds: options.wantedSeconds ?? []
+  };
+}

package/test/keyframe-table-budget.test.js

@@ -17,6 +17,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { KeyframeTables } from "../services/media/KeyframeTables.js";
+import { BytesUnavailable } from "../services/media/container/unavailable.js";
 
 const QUIET = { info: () => {}, warn: () => {} };
 
@@ -100,3 +101,23 @@ test("a read that fails is not turned into a bounded wait's silence", async () =
     "a read that threw is a different thing from a read that is still running"
   );
 });
+
+test("bytes not downloaded yet are a table that has not arrived, and the next arrival reads again", async () => {
+  let calls = 0;
+  const keyframes = tables(1_000, async () => {
+    calls += 1;
+    if (calls === 1) {
+      throw new BytesUnavailable(100, 199, 0);
+    }
+    return { times: [0, 4], tolerance: 0, format: "matroska" };
+  });
+
+  const { table, arrived } = await keyframes.within(FILE);
+  assert.equal(arrived, false, "the opening goes on and re-encodes; it is not failed over a shortage of bytes");
+  assert.equal(table.answered, false, "missing bytes say nothing about the file's keyframes");
+
+  keyframes.readAgainIfUnanswered(FILE);
+  await keyframes.read(FILE);
+  assert.equal(calls, 2);
+  assert.deepEqual(keyframes.of(FILE).times, [0, 4]);
+});

package/test/matroska-cluster-discovery.test.js

@@ -0,0 +1,323 @@
+/**
+ * @file Where a Matroska file's clusters are, found from what is downloaded —
+ * and what is read out of them, in what order, within what memory.
+ *
+ * RFC 9559 §22.1 says each subtitle frame SHOULD be named by the Cues table, and
+ * a file may have no Cues at all. Until 2026-10-01 such a file showed no
+ * subtitles ever. Every check builds a file element by element, says which
+ * byte ranges are "downloaded", and runs passes of the walk the way arriving
+ * pieces would. Fakes only.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { MatroskaContainer } from "../services/media/container/MatroskaContainer.js";
+import {
+  ID,
+  buildMatroska,
+  clusterData,
+  cueBlock,
+  element,
+  heldOver,
+  idBytes,
+  pictureBlock,
+  readerOver,
+  trackEntry
+} from "./helpers/matroska-file.js";
+
+const TRACKS = [
+  trackEntry({ number: 1, type: 1, codecId: "V_MPEG4/ISO/AVC", language: "jpn" }),
+  trackEntry({ number: 2, type: 17, codecId: "S_TEXT/UTF8" })
+];
+
+/** One cluster a second-and-a-bit long with one line on track 2 and a picture. */
+function plainCluster(ticks, text, picture = Buffer.alloc(16, 7)) {
+  return {
+    ticks,
+    data: clusterData({
+      ticks,
+      blocks: [pictureBlock({ track: 1, payload: picture }), cueBlock({ track: 2, relativeTicks: 0, durationTicks: 900, text })]
+    })
+  };
+}
+
+async function planOf(file) {
+  const { read } = readerOver(file);
+  const container = new MatroskaContainer({ readRange: read, fileSize: file.length });
+  return { container, plan: await container.readSubtitlePlan() };
+}
+
+async function pass(container, plan, progress, held) {
+  const result = await container.readHeldCues(plan, plan.tracks[0], progress, held);
+  return { ...result, texts: (result.found.get(2) ?? []).map((cue) => cue.text) };
+}
+
+test("a Cues table that names only the picture still leads to every subtitle line", async () => {
+  const { file } = buildMatroska({
+    tracks: TRACKS,
+    cues: [1],
+    clusters: [plainCluster(0, "a"), plainCluster(10_000, "b"), plainCluster(20_000, "c")]
+  });
+  const { container, plan } = await planOf(file);
+  assert.equal(plan.cuesState, "complete");
+  assert.deepEqual(plan.tracks[0].clusterPositions, [], "the table names no cluster for the subtitle track");
+  const result = await pass(container, plan, {}, heldOver(file, [[0, file.length - 1]]));
+  assert.deepEqual(result.texts.sort(), ["a", "b", "c"]);
+});
+
+test("with no Cues, the chain reads what is joined up and the search finds what lies past a gap", async () => {
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [plainCluster(0, "a"), plainCluster(10_000, "b"), plainCluster(20_000, "c"), plainCluster(30_000, "d")]
+  });
+  const { container, plan } = await planOf(file);
+  assert.equal(plan.cuesState, "absent");
+  const progress = {};
+  const gap = [clusterAt[2], clusterAt[3] - 1];
+  const first = await pass(container, plan, progress, heldOver(file, [[0, gap[0] - 1], [gap[1] + 1, file.length - 1]]));
+  assert.deepEqual(first.texts.sort(), ["a", "b", "d"], "the third cluster is not downloaded; the fourth is found by searching");
+  assert.equal(first.stats.fromSearch, 1);
+
+  const second = await pass(container, plan, progress, heldOver(file, [[0, file.length - 1]]));
+  assert.deepEqual(second.texts, ["c"], "the gap filled: the chain reaches the third, and nothing is read twice");
+  assert.deepEqual(second.withdrawn, [], "the search was right, so nothing is taken back");
+});
+
+test("the walk reads the structure of a cluster, not the frames of its picture", async () => {
+  // Pictures of 64 KB: a walk that read them would move them all.
+  const picture = Buffer.alloc(64 * 1024, 7);
+  const { file } = buildMatroska({
+    tracks: TRACKS,
+    cues: [1],
+    clusters: [plainCluster(0, "a", picture), plainCluster(10_000, "b", picture), plainCluster(20_000, "c", picture)]
+  });
+  const { container, plan } = await planOf(file);
+  const reads = [];
+  const held = heldOver(file, [[0, file.length - 1]], { portionBytes: 4 * 1024 * 1024, reads });
+  const result = await pass(container, plan, {}, held);
+  assert.deepEqual(result.texts.sort(), ["a", "b", "c"]);
+  const moved = reads.reduce((sum, { start, end }) => sum + (end - start + 1), 0);
+  assert.ok(moved < picture.length, `${moved} bytes read for three clusters of ${picture.length}-byte pictures`);
+});
+
+test("with no Cues, the search stops at the first cluster it accepts and the chain knows the rest", async () => {
+  const picture = Buffer.alloc(64 * 1024, 7);
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [0, 10_000, 20_000, 30_000, 40_000].map((ticks, index) => plainCluster(ticks, String(index), picture))
+  });
+  const { container, plan } = await planOf(file);
+  const reads = [];
+  // The first cluster's header is not here, so nothing establishes the chain:
+  // only the search can start it.
+  const held = heldOver(file, [[0, clusterAt[0] - 1], [clusterAt[0] + 12, file.length - 1]], { portionBytes: 32 * 1024, reads });
+  const result = await pass(container, plan, {}, held);
+  assert.deepEqual(result.texts.sort(), ["1", "2", "3", "4"]);
+  assert.equal(result.stats.fromSearch, 4, "found by the search, then by its chain");
+  const searchedPast = reads.filter(({ start }) => start > clusterAt[2]).reduce((sum, { start, end }) => sum + (end - start + 1), 0);
+  assert.ok(searchedPast < picture.length, `${searchedPast} bytes read past the third cluster`);
+});
+
+test("a Cluster id inside a picture's bytes is checked and refused, and gives no line", async () => {
+  // An id, a plausible size and some bytes — inside a SimpleBlock's payload.
+  const fake = Buffer.concat([idBytes(ID.CLUSTER), Buffer.from([0x88]), Buffer.alloc(8, 0x41)]);
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [plainCluster(0, "a"), plainCluster(10_000, "b", Buffer.concat([Buffer.alloc(8), fake, Buffer.alloc(8)]))]
+  });
+  const { container, plan } = await planOf(file);
+  // The second cluster's own header is not downloaded, so nothing establishes it.
+  const result = await pass(
+    container,
+    plan,
+    {},
+    heldOver(file, [[0, clusterAt[1] - 1], [clusterAt[1] + 12, file.length - 1]])
+  );
+  assert.deepEqual(result.texts, ["a"]);
+  assert.ok(result.stats.rejectedCandidates >= 1, "the false start was looked at and refused");
+});
+
+test("a candidate that a cluster the file establishes later turns out to contain is taken back, with its lines", async () => {
+  // A whole, well-formed cluster hidden inside a picture block of a real one.
+  const hidden = element(
+    ID.CLUSTER,
+    clusterData({ ticks: 12_000, blocks: [cueBlock({ track: 2, relativeTicks: 0, durationTicks: 500, text: "hidden" })] })
+  );
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [
+      plainCluster(0, "a"),
+      plainCluster(10_000, "b", Buffer.concat([Buffer.alloc(4), hidden, Buffer.alloc(4)])),
+      plainCluster(20_000, "c")
+    ]
+  });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  const hiddenAt = file.indexOf(hidden);
+  const first = await pass(
+    container,
+    plan,
+    progress,
+    heldOver(file, [[0, clusterAt[1] - 1], [clusterAt[1] + 12, file.length - 1]])
+  );
+  assert.ok(first.texts.includes("hidden"), "the search found it and its structure held");
+
+  const second = await pass(container, plan, progress, heldOver(file, [[0, file.length - 1]]));
+  assert.deepEqual(second.withdrawn, [hiddenAt], "the real cluster around it takes it back");
+  assert.deepEqual(second.texts, ["b"], "and gives its own line");
+});
+
+test("a cluster whose bytes are only partly here is read once, when they all are", async () => {
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: [1],
+    clusters: [plainCluster(0, "a"), plainCluster(10_000, "b")]
+  });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  const partly = await pass(container, plan, progress, heldOver(file, [[0, clusterAt[1] + 20]]));
+  assert.deepEqual(partly.texts, ["a"]);
+  const whole = await pass(container, plan, progress, heldOver(file, [[0, file.length - 1]]));
+  assert.deepEqual(whole.texts, ["b"]);
+  const again = await pass(container, plan, progress, heldOver(file, [[0, file.length - 1]]));
+  assert.deepEqual(again.texts, [], "nothing is read twice");
+});
+
+test("a cluster of unknown size ends where the next top-level element begins", async () => {
+  const { file } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [plainCluster(0, "a"), { ...plainCluster(10_000, "b"), unknownSize: true }, plainCluster(20_000, "c")]
+  });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  const held = heldOver(file, [[0, file.length - 1]]);
+  const first = await pass(container, plan, progress, held);
+  const second = await pass(container, plan, progress, held);
+  assert.deepEqual([...first.texts, ...second.texts].sort(), ["a", "b", "c"]);
+});
+
+test("a CRC-32 before the Timestamp is a cluster like any other; a candidate whose CRC is wrong is refused", async () => {
+  const withCrc = (ticks, text, crc) => ({
+    ticks,
+    data: clusterData({ ticks, crc, blocks: [cueBlock({ track: 2, relativeTicks: 0, durationTicks: 500, text })] })
+  });
+  for (const [crc, expected] of [[true, ["b", "c"]], ["wrong", ["c"]]]) {
+    const { file, clusterAt } = buildMatroska({
+      tracks: TRACKS,
+      cues: null,
+      clusters: [withCrc(0, "a", false), withCrc(10_000, "b", crc), withCrc(20_000, "c", false)]
+    });
+    const { container, plan } = await planOf(file);
+    // The first cluster's header is not here, so the second is reached only by
+    // the search, which checks the CRC.
+    const result = await pass(container, plan, {}, heldOver(file, [[0, clusterAt[0] - 1], [clusterAt[0] + 12, file.length - 1]]));
+    assert.deepEqual(result.texts.sort(), expected, `crc ${crc}`);
+    if (crc === "wrong") {
+      assert.ok(result.stats.rejectedCandidates >= 1);
+    }
+  }
+});
+
+test("a candidate whose end has not arrived waits, and is read when it has", async () => {
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [plainCluster(0, "a"), plainCluster(10_000, "b"), plainCluster(20_000, "c")]
+  });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  const first = await pass(
+    container,
+    plan,
+    progress,
+    heldOver(file, [[0, clusterAt[1] - 1], [clusterAt[2], clusterAt[2] + 20]])
+  );
+  assert.deepEqual(first.texts, ["a"]);
+  assert.equal(first.stats.pendingCandidates, 1, "found, and waiting for its bytes");
+  const second = await pass(container, plan, progress, heldOver(file, [[0, clusterAt[1] - 1], [clusterAt[2], file.length - 1]]));
+  assert.deepEqual(second.texts, ["c"]);
+});
+
+test("an id cut by the end of what is downloaded is found once the run grows", async () => {
+  const { file, clusterAt } = buildMatroska({
+    tracks: TRACKS,
+    cues: null,
+    clusters: [plainCluster(0, "a"), plainCluster(10_000, "b"), plainCluster(20_000, "c")]
+  });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  // The run ends two bytes into the third cluster's id.
+  await pass(container, plan, progress, heldOver(file, [[0, clusterAt[1] - 1], [clusterAt[1] + 12, clusterAt[2] + 1]]));
+  const grown = await pass(container, plan, progress, heldOver(file, [[0, clusterAt[1] - 1], [clusterAt[1] + 12, file.length - 1]]));
+  assert.ok(grown.texts.includes("c"), "the cut id was searched again and found");
+});
+
+test("the cluster a viewer stands in is read first, then the one before it, then onward", async () => {
+  const clusters = [0, 10_000, 20_000, 30_000, 40_000].map((ticks) => plainCluster(ticks, `at ${ticks / 1000}`));
+  // A line that starts in the 10 s cluster and is still on screen at 25 s.
+  clusters[1] = {
+    ticks: 10_000,
+    data: clusterData({ ticks: 10_000, blocks: [cueBlock({ track: 2, relativeTicks: 0, durationTicks: 16_000, text: "at 10" })] })
+  };
+  const { file } = buildMatroska({ tracks: TRACKS, cues: [1], clusters });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  const held = heldOver(file, [[0, file.length - 1]], { wantedSeconds: [25] });
+  const first = await pass(container, plan, progress, held);
+  assert.deepEqual(first.texts, ["at 20", "at 10"], "the pass ends with what is on screen, to be pushed at once");
+  assert.equal(first.more, true, "and says there is more to read now");
+  const second = await pass(container, plan, progress, held);
+  assert.deepEqual(second.texts, ["at 30", "at 40", "at 0"], "then onward from the viewer, then the rest");
+  assert.equal(second.more, false);
+});
+
+test("a pass reading the rest stops when a viewer moves, and the next one starts from there", async () => {
+  const clusters = [0, 10_000, 20_000, 30_000, 40_000, 50_000].map((ticks) => plainCluster(ticks, `at ${ticks / 1000}`));
+  const { file } = buildMatroska({ tracks: TRACKS, cues: [1], clusters });
+  const { container, plan } = await planOf(file);
+  const progress = {};
+  let viewer = [];
+  let readsBeforeSeek = 2;
+  const held = heldOver(file, [[0, file.length - 1]]);
+  held.wantedSeconds = () => {
+    // The viewer seeks to 45 s after the pass has read two clusters.
+    readsBeforeSeek -= 1;
+    if (readsBeforeSeek < 0) {
+      viewer = [45];
+    }
+    return viewer;
+  };
+  const first = await pass(container, plan, progress, held);
+  assert.equal(first.more, true, "stopped for the viewer who moved");
+  const second = await pass(container, plan, progress, held);
+  assert.deepEqual(second.texts.slice(0, 1), ["at 40"], "the next pass reads where the viewer now is first");
+});
+
+test("no read is larger than one portion, and a block larger than one is refused while the rest is read", async () => {
+  const portion = 96;
+  const { file } = buildMatroska({
+    tracks: TRACKS,
+    cues: [1],
+    clusters: [
+      plainCluster(0, "short"),
+      {
+        ticks: 10_000,
+        data: clusterData({ ticks: 10_000, blocks: [cueBlock({ track: 2, relativeTicks: 0, durationTicks: 500, text: "x".repeat(200) })] })
+      },
+      plainCluster(20_000, "also short")
+    ]
+  });
+  const { container, plan } = await planOf(file);
+  const reads = [];
+  const result = await pass(container, plan, {}, heldOver(file, [[0, file.length - 1]], { portionBytes: portion, reads }));
+  assert.deepEqual(result.texts.sort(), ["also short", "short"]);
+  assert.equal(result.stats.refusedElements, 1);
+  assert.ok(reads.every(({ start, end }) => end - start + 1 <= portion), "every read stayed within one portion");
+});
+