@2018kguo/recto 0.3.0 → 0.5.0

package/dist/ranged.js

@@ -9,11 +9,14 @@
 // `timeoutMs`), so run it on a worker thread of its own, never on a server's main loop.
 //
 // Fetched bytes are kept as fixed-size chunks indexed by chunk number, so a read costs
-// O(chunks it spans), whatever the number of fetches so far. The first fetch reads the head
-// (and learns the size); a file it does not cover gets its tail next, since an ordinary
-// file's cross-reference table is at its end. A miss that continues the previous fetch (a
-// long xref table or page run read front to back) doubles the read-ahead, so a sequential
-// scan of n chunks costs O(log n) round trips.
+// O(chunks it spans), whatever the number of fetches so far. The first round asks for the head
+// and the tail at once (the tail as a suffix range, `bytes=-n`, since the size isn't known
+// yet): an ordinary file's cross-reference table is at its end, and a small file's head is
+// all of it. That round, and the one for a cross-reference section the tail didn't hold, run
+// before the engine's synchronous parse, so in a browser they're `fetch` calls in parallel
+// rather than synchronous requests one after another. A miss that continues the previous
+// fetch (a long xref table or page run read front to back) doubles the read-ahead, so a
+// sequential scan of n chunks costs O(log n) round trips.
 import { PdfError } from "./errors.js";
 const DEFAULT_CHUNK_BYTES = 64 * 1024;
 const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
@@ -24,6 +27,11 @@ const MAX_READ_AHEAD_BYTES = 8 * 1024 * 1024;
  * first-page cross-reference section.
  */
 const HEAD_CHUNKS = 4;
+/**
+ * The tail asked for alongside the head: the last chunk, which ends the file, and the one
+ * before, where a file's last objects and a short xref section usually are.
+ */
+const TAIL_CHUNKS = 2;
 /**
  * A ranged open reserves the file's length of linear memory: fresh pages, committed only where
  * fetched, so memory use follows the bytes fetched and not the length (measured in
@@ -37,6 +45,8 @@ class RangeLoader {
     chunkBytes;
     /** Fetched chunks by chunk number (a flat array, sized once the length is known). */
     #chunks = [];
+    /** A chunk's start or end, by chunk number, until the rest of it arrives. */
+    #pieces = new Map();
     /** Set once a fetch failed; every later read fails and every call throws it. */
     failure = null;
     #bytesFetched = 0;
@@ -75,16 +85,78 @@ class RangeLoader {
     }
     /** Fetches chunks `firstChunk..endChunk`, keeping only those not held yet. */
     fetchChunks(firstChunk, endChunk) {
+        const runs = this.#missing(firstChunk, endChunk);
+        if (runs.length > 0) {
+            this.#absorb(this.#round(runs, (limit, timeoutMs, passesTotal) => this.#timed(passesTotal, () => this.#fetch(runs, timeoutMs, limit))));
+        }
+    }
+    /** The same, through `fetchAsync` when there is one: before the parse, a browser need not block. */
+    async #fetchChunksAsync(firstChunk, endChunk, fetchAsync) {
+        await this.#fetchRunsAsync(this.#missing(firstChunk, endChunk), fetchAsync);
+    }
+    async #fetchRunsAsync(runs, fetchAsync) {
+        if (runs.length === 0) {
+            return;
+        }
+        this.#absorb(await this.#round(runs, (limit, timeoutMs, passesTotal) => fetchAsync
+            ? this.#timedAsync(passesTotal, fetchAsync(runs, timeoutMs, limit))
+            : this.#timed(passesTotal, () => this.#fetch(runs, timeoutMs, limit))));
+    }
+    /**
+     * The first round: the head and, in parallel, the tail as a suffix, then the last
+     * cross-reference section if the tail didn't hold it. A file the head covers needs no more;
+     * a server that doesn't answer the suffix gets the tail by offset in a round of its own.
+     */
+    async begin(fetchAsync) {
+        const tail = TAIL_CHUNKS * this.chunkBytes;
+        // The head stops where the suffix starts, in a file shorter than the two.
+        const head = { start: 0, end: HEAD_CHUNKS * this.chunkBytes, yieldTail: tail };
+        const requests = [head, { suffix: tail }];
+        const answers = await this.#round(requests, (limit, timeoutMs, passesTotal) => fetchAsync
+            ? this.#timedAsync(passesTotal, fetchAsync(requests, timeoutMs, limit))
+            : this.#timed(passesTotal, () => this.#fetch(requests, timeoutMs, limit)));
+        this.#absorb(answers);
+        if (this.length <= 0) {
+            throw new PdfError("invalid-file", "the file is empty");
+        }
+        if (this.#bytesFetched > this.#maxBytes) {
+            throw tooLarge(this.#maxBytes);
+        }
+        // Without the suffix's answer, the head and the last chunk by their offsets, as one round.
+        const totalChunks = Math.ceil(this.length / this.chunkBytes);
+        await this.#fetchRunsAsync([...this.#missing(0, Math.min(HEAD_CHUNKS, totalChunks)), ...this.#missing(Math.max(HEAD_CHUNKS, totalChunks - 1), totalChunks)], fetchAsync);
+        if (totalChunks > HEAD_CHUNKS) {
+            // The tail names the last cross-reference section (`startxref`). Fetch all of it in one
+            // round, rather than letting the parser discover it a chunk at a time.
+            const xrefAt = this.startxref();
+            if (xrefAt !== null && this.length - xrefAt <= MAX_READ_AHEAD_BYTES) {
+                await this.#fetchChunksAsync(Math.floor(xrefAt / this.chunkBytes), totalChunks, fetchAsync);
+            }
+        }
+    }
+    /**
+     * The runs of bytes in chunks `firstChunk..endChunk` not held yet. A chunk a range brought
+     * the start or end of needs only the rest.
+     */
+    #missing(firstChunk, endChunk) {
         const runs = [];
-        let wanted = 0;
         for (let chunk = firstChunk; chunk < endChunk; chunk++) {
             if (this.#chunks[chunk]) {
                 continue;
             }
-            const start = chunk * this.chunkBytes;
-            const end = this.length > 0
+            let start = chunk * this.chunkBytes;
+            let end = this.length > 0
                 ? Math.min(this.length, start + this.chunkBytes)
                 : start + this.chunkBytes;
+            for (const piece of this.#pieces.get(chunk) ?? []) {
+                const pieceEnd = piece.start + piece.bytes.byteLength;
+                if (piece.start <= start) {
+                    start = Math.max(start, pieceEnd);
+                }
+                else {
+                    end = Math.min(end, piece.start);
+                }
+            }
             const last = runs.at(-1);
             if (last && last.end === start) {
                 last.end = end;
@@ -92,39 +164,59 @@ class RangeLoader {
             else {
                 runs.push({ start, end });
             }
-            wanted += end - start;
-        }
-        if (runs.length === 0) {
-            return;
         }
+        return runs;
+    }
+    /**
+     * One round trip for `requests`: the signal, the budget and the deadline checked first, then
+     * `fetch` with what's left of each.
+     */
+    #round(requests, fetch) {
         if (this.#signal?.aborted) {
             throw new PdfError("aborted", "the signal was aborted", this.#signal.reason);
         }
         // Before the length is known the head's size is a guess, and the file may be far smaller;
         // the fetch itself stops at the budget.
+        const wanted = requests.reduce((sum, request) => sum + ("suffix" in request ? request.suffix : request.end - request.start), 0);
         if (this.length > 0 && this.#bytesFetched + wanted > this.#maxBytes) {
             throw tooLarge(this.#maxBytes);
         }
-        const passedTotal = `the ranged read passed its ${this.#totalTimeoutMs} ms (totalTimeoutMs)`;
         const left = this.#deadline - performance.now();
         if (left <= 0) {
-            throw new PdfError("timeout", passedTotal);
+            throw new PdfError("timeout", this.#passedTotal());
         }
         this.#rounds += 1;
         const passesTotal = left < this.#timeoutMs;
-        let answers;
+        return fetch(this.#maxBytes - this.#bytesFetched, passesTotal ? Math.ceil(left) : this.#timeoutMs, passesTotal);
+    }
+    #passedTotal() {
+        return `the ranged read passed its ${this.#totalTimeoutMs} ms (totalTimeoutMs)`;
+    }
+    /** A round's timeout, when it's the deadline's, says so. */
+    #timed(passesTotal, fetch) {
         try {
-            answers = this.#fetch(runs, passesTotal ? Math.ceil(left) : this.#timeoutMs, this.#maxBytes - this.#bytesFetched);
+            return fetch();
         }
         catch (error) {
             if (passesTotal && error.code === "timeout") {
-                throw new PdfError("timeout", passedTotal, error);
+                throw new PdfError("timeout", this.#passedTotal(), error);
             }
             throw error;
         }
+    }
+    async #timedAsync(passesTotal, fetch) {
+        return await fetch.catch((error) => {
+            throw passesTotal && error.code === "timeout" ? new PdfError("timeout", this.#passedTotal(), error) : error;
+        });
+    }
+    /** Checks and keeps a round's answers; a suffix nobody answered is skipped. */
+    #absorb(answers) {
         for (const answer of answers) {
+            if (!answer) {
+                continue;
+            }
             this.#requests += 1;
-            this.#bytesFetched += answer.bytes.byteLength;
+            this.#bytesFetched += answer.received;
             if (this.length > 0 && answer.length !== this.length) {
                 throw new PdfError("fetch-failed", `the file changed size during the ranged read (${this.length} bytes, now ${answer.length})`, undefined, answer.status);
             }
@@ -141,16 +233,48 @@ class RangeLoader {
         }
     }
     #store(answer) {
-        // Answers start on a chunk boundary (we asked for one). Views, not copies.
-        const { bytes } = answer;
+        // Whole chunks are kept as views, not copies; a chunk the answer has only part of is kept
+        // as a piece until the rest arrives.
+        const { bytes, start } = answer;
         if (this.#chunks.length === 0) {
             this.#chunks = Array.from({
                 length: Math.ceil(answer.length / this.chunkBytes),
             });
         }
-        for (let at = 0; at < bytes.byteLength; at += this.chunkBytes) {
-            const chunk = (answer.start + at) / this.chunkBytes;
-            this.#chunks[chunk] ??= bytes.subarray(at, Math.min(bytes.byteLength, at + this.chunkBytes));
+        const end = start + bytes.byteLength;
+        for (let chunk = Math.floor(start / this.chunkBytes); chunk * this.chunkBytes < end; chunk++) {
+            if (this.#chunks[chunk]) {
+                continue;
+            }
+            const from = chunk * this.chunkBytes;
+            const to = Math.min(from + this.chunkBytes, answer.length);
+            const part = bytes.subarray(Math.max(from, start) - start, Math.min(to, end) - start);
+            if (from >= start && to <= end) {
+                this.#chunks[chunk] = part;
+                continue;
+            }
+            const pieces = this.#pieces.get(chunk) ?? [];
+            pieces.push({ start: Math.max(from, start), bytes: part });
+            pieces.sort((a, b) => a.start - b.start);
+            // Whole once its pieces meet end to end.
+            let at = from;
+            for (const piece of pieces) {
+                if (piece.start > at) {
+                    break;
+                }
+                at = Math.max(at, piece.start + piece.bytes.byteLength);
+            }
+            if (at >= to) {
+                const whole = new Uint8Array(to - from);
+                for (const piece of pieces) {
+                    whole.set(piece.bytes.subarray(0, Math.min(piece.bytes.byteLength, to - piece.start)), piece.start - from);
+                }
+                this.#chunks[chunk] = whole;
+                this.#pieces.delete(chunk);
+            }
+            else {
+                this.#pieces.set(chunk, pieces);
+            }
         }
     }
     /**
@@ -170,8 +294,11 @@ class RangeLoader {
         const offset = match ? Number(match[1]) : Number.NaN;
         return offset >= 0 && offset < this.length ? offset : null;
     }
-    /** The chunk window to fetch for a miss at `chunk`, with read-ahead. */
-    #window(chunk, lastNeeded) {
+    /**
+     * The chunk window to fetch for a miss at `chunk`, with read-ahead, and at least to `lastAhead`:
+     * what the engine said it's likely to read next.
+     */
+    #window(chunk, lastNeeded, lastAhead) {
         const start = chunk * this.chunkBytes;
         const sequential = this.#lastFetchEnd >= 0 &&
             start >= this.#lastFetchEnd - this.chunkBytes &&
@@ -180,16 +307,17 @@ class RangeLoader {
             ? Math.min(MAX_READ_AHEAD_BYTES, this.#readAhead * 2)
             : this.chunkBytes;
         const totalChunks = Math.ceil(this.length / this.chunkBytes);
-        const end = Math.min(totalChunks, Math.max(lastNeeded + 1, chunk + this.#readAhead / this.chunkBytes));
+        const end = Math.min(totalChunks, Math.max(lastNeeded + 1, lastAhead + 1, chunk + this.#readAhead / this.chunkBytes));
         this.#lastFetchEnd = end * this.chunkBytes;
         return [chunk, end];
     }
     /**
-     * Copies [offset, offset + out.length) into `out`, fetching what is missing first. On a
-     * failed fetch it records the failure and fails the read; the call that made it then
-     * throws the failure.
+     * Copies [offset, offset + out.length) into `out`, fetching what is missing first, and if it
+     * fetches, `ahead` bytes past it too, as far as the budget allows: the engine's guess at what
+     * it reads next, which then costs no round trip of its own. On a failed fetch it records the
+     * failure and fails the read; the call that made it then throws the failure.
      */
-    read(offset, out) {
+    read(offset, out, ahead = 0) {
         this.#reads += 1;
         this.#readBytes += out.byteLength;
         const end = offset + out.byteLength;
@@ -201,10 +329,12 @@ class RangeLoader {
         }
         const first = Math.floor(offset / this.chunkBytes);
         const last = Math.floor((end - 1) / this.chunkBytes);
+        const spare = Math.max(0, this.#maxBytes - this.#bytesFetched - out.byteLength);
+        const lastAhead = Math.floor((Math.min(this.length, end + Math.min(ahead, spare)) - 1) / this.chunkBytes);
         for (let chunk = first; chunk <= last; chunk++) {
             if (!this.#chunks[chunk]) {
                 try {
-                    this.fetchChunks(...this.#window(chunk, last));
+                    this.fetchChunks(...this.#window(chunk, last, lastAhead));
                 }
                 catch (error) {
                     this.failure =
@@ -231,10 +361,11 @@ class RangeLoader {
     }
 }
 /**
- * Starts a ranged read of `source`: the head, then (for a larger file) the tail and its last
- * cross-reference section. Blocks while it fetches.
+ * Starts a ranged read of `source`: the head and tail, then the last cross-reference section
+ * if the tail didn't hold it. Blocks while it fetches, except in a browser, where these
+ * rounds are `fetch` calls.
  */
-export function startRangeLoader(source, options = {}) {
+export async function startRangeLoader(source, options = {}) {
     const positive = (name, value) => {
         if (value !== undefined && !(typeof value === "number" && value > 0)) {
             throw new RangeError(`${name} must be above 0 (got ${value})`);
@@ -250,29 +381,14 @@ export function startRangeLoader(source, options = {}) {
     if (options.signal?.aborted) {
         throw new PdfError("aborted", "the signal was aborted", options.signal.reason);
     }
-    const chunkBytes = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;
     const loader = new RangeLoader(fetcherFor(source), {
-        chunkBytes,
+        chunkBytes: options.chunkBytes ?? DEFAULT_CHUNK_BYTES,
         maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
         timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
         totalTimeoutMs: options.totalTimeoutMs ?? Number.POSITIVE_INFINITY,
         signal: options.signal,
     });
-    loader.fetchChunks(0, HEAD_CHUNKS);
-    if (loader.length <= 0) {
-        throw new PdfError("invalid-file", "the file is empty");
-    }
-    // A file the head covered is read whole; any other one gets its tail.
-    const totalChunks = Math.ceil(loader.length / chunkBytes);
-    if (totalChunks > HEAD_CHUNKS) {
-        loader.fetchChunks(Math.max(HEAD_CHUNKS, totalChunks - 1), totalChunks);
-        // The tail names the last cross-reference section (`startxref`). Fetch all of it in one
-        // round, rather than letting the parser discover it a chunk at a time.
-        const xrefAt = loader.startxref();
-        if (xrefAt !== null && loader.length - xrefAt <= MAX_READ_AHEAD_BYTES) {
-            loader.fetchChunks(Math.floor(xrefAt / chunkBytes), totalChunks);
-        }
-    }
+    await loader.begin(asyncFetcherFor(source));
     return loader;
 }
 /**
@@ -297,20 +413,52 @@ export function ownedSource(source) {
 function fetcherFor(source) {
     if (typeof source !== "string") {
         const bytes = source;
-        return (ranges) => ranges.map(({ start, end }) => ({
-            start,
-            bytes: bytes.subarray(start, Math.min(end, bytes.byteLength)),
-            length: bytes.byteLength,
-            etag: null,
-            status: 206,
-        }));
+        return (requests) => requests.map((request) => {
+            const { start, end } = asked(request, bytes.byteLength);
+            return { start, bytes: bytes.subarray(start, end), length: bytes.byteLength, etag: null, status: 206, received: end - start };
+        });
     }
     const url = source;
     // Node's fetch cannot run under a blocked thread; in a browser worker a synchronous
     // XMLHttpRequest needs no second thread.
-    return globalThis.process?.getBuiltinModule?.("node:worker_threads")
-        ? (ranges, timeoutMs, limit) => fetchOverThread(url, ranges, timeoutMs, limit)
-        : (ranges, timeoutMs, limit) => fetchOverXhr(url, ranges, timeoutMs, limit);
+    return isNode()
+        ? (requests, timeoutMs, limit) => fetchOverThread(url, requests, timeoutMs, limit)
+        : (requests, timeoutMs, limit) => fetchOverXhr(url, requests, timeoutMs, limit);
+}
+/**
+ * How the rounds before the parse fetch, if not as the parse's do: in a browser, `fetch`, so a
+ * round's requests run in parallel, where synchronous requests run one after another. Node's
+ * fetcher thread already runs them in parallel.
+ */
+function asyncFetcherFor(source) {
+    if (typeof source !== "string" || isNode()) {
+        return null;
+    }
+    return (requests, timeoutMs, limit) => fetchOverFetch(source, requests, timeoutMs, limit);
+}
+function isNode() {
+    return Boolean(globalThis.process?.getBuiltinModule?.("node:worker_threads"));
+}
+/** The bytes `request` asks for of a file of `length`, or of a range with `yieldTail`, those it reads. */
+function asked(request, length) {
+    if ("suffix" in request) {
+        return { start: Math.max(0, length - request.suffix), end: length };
+    }
+    const end = Math.min(request.end, length);
+    return { start: request.start, end: request.yieldTail === undefined ? end : Math.min(end, Math.max(request.start, length - request.yieldTail)) };
+}
+/** How much of a 206 answer to `request` to read, from its total; past it is the suffix's. */
+function readsOf(request, contentRange) {
+    const size = "suffix" in request ? request.suffix : request.end - request.start;
+    const total = Number(/\/(\d+)$/u.exec(contentRange?.trim() ?? "")?.[1] ?? Number.NaN);
+    if ("suffix" in request || request.yieldTail === undefined || !(total >= 0)) {
+        return { most: size, exact: false };
+    }
+    const most = Math.max(0, Math.min(size, asked(request, total).end - request.start));
+    return { most, exact: most < size };
+}
+function rangeHeader(request) {
+    return "suffix" in request ? `bytes=-${request.suffix}` : `bytes=${request.start}-${request.end - 1}`;
 }
 function tooLarge(maxBytes) {
     return new PdfError("too-large", `the ranged read would pass ${maxBytes} bytes (maxBytes); raise it or fetch the file whole`);
@@ -319,13 +467,13 @@ function tooLarge(maxBytes) {
  * A server's answer as chunks to store, or a clear failure. Messages never carry the URL: a
  * presigned query is a credential.
  */
-function answerOf(range, status, contentRange, etag, bytes, limit) {
-    if (status === 200) {
+function answerOf(range, status, contentRange, etag, bytes, limit, received = bytes.byteLength) {
+    if (status === 200 && !("suffix" in range)) {
         // The server ignored Range and sent the whole file: use it, while the budget allows.
         if (bytes.byteLength > limit) {
             throw new PdfError("too-large", `the server does not answer Range requests, and the whole file is past the ${limit} bytes left of maxBytes`);
         }
-        return { start: 0, bytes, length: bytes.byteLength, etag, status };
+        return { start: 0, bytes, length: bytes.byteLength, etag, status, received };
     }
     if (status !== 206) {
         throw new PdfError("fetch-failed", `the ranged read failed (HTTP ${status})`, undefined, status);
@@ -338,10 +486,25 @@ function answerOf(range, status, contentRange, etag, bytes, limit) {
     const start = Number(match[1]);
     const length = Number(match[2]);
     // A short or shifted answer (a proxy capping ranges) would store a partial chunk.
-    if (start !== range.start || bytes.byteLength !== Math.min(range.end, length) - range.start) {
-        throw new PdfError("fetch-failed", `the server answered a different range than asked (asked ${range.start}-${range.end - 1}, got ${bytes.byteLength} bytes from ${start})`, undefined, status);
+    const want = asked(range, length);
+    // A range that would stop where the suffix starts runs on to its end when the suffix failed.
+    const whole = "suffix" in range ? want : asked({ start: range.start, end: range.end }, length);
+    if (start !== want.start || (bytes.byteLength !== want.end - want.start && bytes.byteLength !== whole.end - whole.start)) {
+        throw new PdfError("fetch-failed", `the server answered a different range than asked (asked ${want.start}-${want.end - 1}, got ${bytes.byteLength} bytes from ${start})`, undefined, status);
+    }
+    return { start, bytes, length, etag, status, received };
+}
+/** A suffix's answer, or null if it isn't one: the tail is then asked for by its offset. */
+function suffixAnswerOf(suffix, status, contentRange, etag, bytes, received = bytes.byteLength) {
+    if (status !== 206) {
+        return null;
+    }
+    try {
+        return answerOf(suffix, status, contentRange, etag, bytes, Number.POSITIVE_INFINITY, received);
+    }
+    catch {
+        return null;
     }
-    return { start, bytes, length, etag, status };
 }
 const NO_ANSWER = "the ranged read failed: the network, or a cross-origin server that does not allow it";
 function fetchOverXhr(url, ranges, timeoutMs, limit) {
@@ -351,7 +514,7 @@ function fetchOverXhr(url, ranges, timeoutMs, limit) {
         xhr.open("GET", url, false);
         xhr.responseType = "arraybuffer";
         xhr.timeout = Math.max(1, deadline - performance.now());
-        xhr.setRequestHeader("Range", `bytes=${range.start}-${range.end - 1}`);
+        xhr.setRequestHeader("Range", rangeHeader(range));
         try {
             xhr.send();
         }
@@ -365,9 +528,205 @@ function fetchOverXhr(url, ranges, timeoutMs, limit) {
         if (xhr.status === 0) {
             throw new PdfError("fetch-failed", NO_ANSWER);
         }
+        if ("suffix" in range) {
+            return suffixAnswerOf(range, xhr.status, xhr.getResponseHeader("Content-Range"), xhr.getResponseHeader("ETag"), new Uint8Array(xhr.response));
+        }
         return answerOf(range, xhr.status, xhr.getResponseHeader("Content-Range"), xhr.getResponseHeader("ETag"), new Uint8Array(xhr.response), limit);
     });
 }
+/**
+ * The XMLHttpRequest path's answers and failures, from `fetch`, with a round's requests in
+ * parallel. Used before the parse starts, when this thread may await. A suffix still out when the
+ * ranges are in gets as long again as they took, then counts as unanswered.
+ */
+async function fetchOverFetch(url, requests, timeoutMs, limit) {
+    const started = performance.now();
+    const controllers = requests.map(() => new AbortController());
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        for (const controller of controllers) {
+            controller.abort();
+        }
+    }, timeoutMs);
+    const failure = (error) => timedOut
+        ? new PdfError("timeout", `the ranged read timed out after ${timeoutMs} ms`, error)
+        : new PdfError("fetch-failed", NO_ANSWER, error);
+    // What the suffix came to, for a head that stopped where it starts: kept short only if it's good.
+    let suffixDone;
+    const suffixAnswer = new Promise((resolve) => (suffixDone = resolve));
+    const suffixAt = requests.findIndex((request) => "suffix" in request);
+    const one = async (request, signal) => {
+        const suffix = "suffix" in request;
+        try {
+            const response = await fetch(url, { headers: { Range: rangeHeader(request) }, signal });
+            const contentRange = response.headers.get("Content-Range");
+            const etag = response.headers.get("ETag");
+            if (suffix && response.status !== 206) {
+                // Not a suffix: a whole file, or a refusal. Read none of it.
+                await response.body?.cancel();
+                suffixDone(null);
+                return null;
+            }
+            const reader = byteReader(response.body);
+            try {
+                if (response.status !== 206) {
+                    // A whole file, used if it fits the budget: read no further than one byte past it.
+                    const bytes = await reader.read(limit + 1);
+                    return answerOf(request, response.status, contentRange, etag, bytes, limit, reader.received);
+                }
+                const { most, exact } = readsOf(request, contentRange);
+                let bytes = await reader.read(exact ? most : most + 1);
+                if (suffix) {
+                    const answer = suffixAnswerOf(request, response.status, contentRange, etag, bytes, reader.received);
+                    suffixDone(answer);
+                    return answer;
+                }
+                if (exact && !("suffix" in request)) {
+                    // Stopped where the suffix starts: the rest too, unless the suffix brings it.
+                    const total = Number(contentRange?.trim().split("/").pop());
+                    const answer = await Promise.race([suffixAnswer, delay(suffixGrace(performance.now() - started), null)]);
+                    if (answer?.length !== total) {
+                        controllers[suffixAt]?.abort();
+                        const rest = await reader.read(request.end - request.start - most + 1);
+                        bytes = concat(bytes, rest);
+                    }
+                }
+                return answerOf(request, response.status, contentRange, etag, bytes, limit, reader.received);
+            }
+            finally {
+                await reader.cancel();
+            }
+        }
+        catch (error) {
+            // A suffix never fails the round: the tail is then asked for by its offset.
+            if (suffix) {
+                suffixDone(null);
+                return null;
+            }
+            throw error instanceof PdfError ? error : failure(error);
+        }
+    };
+    try {
+        const ranges = Promise.all(requests.map((request, i) => ("suffix" in request ? null : one(request, controllers[i].signal))));
+        const suffixes = requests.map((request, i) => {
+            if (!("suffix" in request)) {
+                return null;
+            }
+            return one(request, controllers[i].signal);
+        });
+        const answers = await ranges;
+        const grace = suffixGrace(performance.now() - started);
+        return await Promise.all(requests.map(async (request, i) => {
+            const pending = suffixes[i];
+            if (!pending) {
+                return answers[i];
+            }
+            let late;
+            const giveUp = new Promise((resolve) => {
+                late = setTimeout(() => {
+                    controllers[i].abort();
+                    resolve(null);
+                }, grace);
+            });
+            try {
+                return await Promise.race([pending, giveUp]);
+            }
+            finally {
+                clearTimeout(late);
+            }
+        }));
+    }
+    finally {
+        clearTimeout(timer);
+        // A round that failed leaves nothing downloading.
+        for (const controller of controllers) {
+            controller.abort();
+        }
+    }
+}
+/**
+ * How long a suffix may still take once the round's ranges are in, `took` after they went out:
+ * as long again, and at least a quarter second, since both went out together. Past it the tail
+ * is asked for by its offset, a round later, as a server that refuses suffixes gets it.
+ */
+function suffixGrace(took) {
+    return Math.max(took, 250);
+}
+function delay(ms, value) {
+    return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+}
+function concat(a, b) {
+    const out = new Uint8Array(a.byteLength + b.byteLength);
+    out.set(a);
+    out.set(b, a.byteLength);
+    return out;
+}
+/**
+ * A body read a given number of bytes at a time: exactly, by a reader that fills a buffer where the
+ * stream has one, or by parts, keeping what a part held past the count for the next read.
+ * `received` counts every byte taken off the stream.
+ */
+function byteReader(body) {
+    let byob = null;
+    try {
+        byob = body?.getReader({ mode: "byob" }) ?? null;
+    }
+    catch {
+        // Not a byte stream: read by parts.
+    }
+    const plain = byob || !body ? null : body.getReader();
+    let spare = new Uint8Array(0);
+    let done = !body;
+    let received = 0;
+    return {
+        get received() {
+            return received;
+        },
+        async read(n) {
+            // In parts of at most 1 MiB, so a large `n` (a budget) allocates only what arrives.
+            const parts = [spare.subarray(0, n)];
+            let got = parts[0].byteLength;
+            spare = spare.subarray(got);
+            while (got < n && !done) {
+                if (byob) {
+                    const { value, done: end } = await byob.read(new Uint8Array(Math.min(n - got, 1 << 20)));
+                    if (value) {
+                        parts.push(value);
+                        got += value.byteLength;
+                        received += value.byteLength;
+                    }
+                    done = end;
+                }
+                else {
+                    const { value, done: end } = await plain.read();
+                    if (end) {
+                        done = true;
+                        break;
+                    }
+                    received += value.byteLength;
+                    const take = Math.min(n - got, value.byteLength);
+                    parts.push(value.subarray(0, take));
+                    got += take;
+                    spare = value.subarray(take);
+                }
+            }
+            if (parts.length === 1) {
+                return parts[0];
+            }
+            const out = new Uint8Array(got);
+            let at = 0;
+            for (const part of parts) {
+                out.set(part, at);
+                at += part.byteLength;
+            }
+            return out;
+        },
+        async cancel() {
+            await (byob ?? plain)?.cancel().catch(() => undefined);
+        },
+    };
+}
 // The fetcher thread: plain JS (eval), so it needs no loader or bundler entry. It answers
 // each request on the port, then bumps `flag` so the waiting thread wakes. The body is read
 // up to `limit`, for a server that answers a small range with a huge whole file.
@@ -375,9 +734,22 @@ const FETCHER_SOURCE = `
 const { workerData } = require("node:worker_threads");
 const { port, flag } = workerData;
 const controllers = new Map();
+const suffixes = new Map();
+// What a group's suffix came to: its file's total if it's a good suffix, null otherwise.
+function outcome(group) {
+  let entry = suffixes.get(group);
+  if (!entry) {
+    let resolve;
+    entry = { promise: new Promise((r) => (resolve = r)) };
+    entry.resolve = resolve;
+    suffixes.set(group, entry);
+  }
+  return entry;
+}
 async function get(m, signal) {
+  const started = performance.now();
   const response = await fetch(m.url, {
-    headers: { Range: "bytes=" + m.start + "-" + (m.end - 1), "Accept-Encoding": "identity" },
+    headers: { Range: m.range, "Accept-Encoding": "identity" },
     signal,
   });
   const reply = {
@@ -385,19 +757,61 @@ async function get(m, signal) {
     contentRange: response.headers.get("content-range"),
     etag: response.headers.get("etag"),
   };
-  if (!response.ok) {
+  // A suffix answered with anything else (a whole file) isn't read.
+  if (!response.ok || (m.suffix && response.status !== 206)) {
     if (response.body) await response.body.cancel();
-    return { ...reply, bytes: new ArrayBuffer(0) };
+    if (m.suffix) outcome(m.group).resolve(null);
+    return { ...reply, bytes: new ArrayBuffer(0), received: 0 };
   }
-  const parts = [];
-  let size = 0;
-  for await (const part of response.body ?? []) {
-    size += part.byteLength;
-    if (size > m.limit) return { ...reply, overLimit: true, bytes: new ArrayBuffer(0) };
-    parts.push(part);
+  const reader = response.body ? response.body.getReader({ mode: "byob" }) : null;
+  let received = 0;
+  let done = !reader;
+  const read = async (n) => {
+    const parts = [];
+    let got = 0;
+    while (got < n && !done) {
+      const { value, done: end } = await reader.read(new Uint8Array(Math.min(n - got, 1 << 20)));
+      if (value) { parts.push(value); got += value.byteLength; received += value.byteLength; }
+      done = end;
+    }
+    return Buffer.concat(parts, got);
+  };
+  try {
+    // A 206 is read as far as the range runs (see readsOf), and a byte past to catch a longer one;
+    // a whole file, to a byte past the limit.
+    if (response.status !== 206) {
+      const bytes = await read(m.limit + 1);
+      if (received > m.limit) return { ...reply, overLimit: true, bytes: new ArrayBuffer(0), received };
+      return { ...reply, bytes: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength), received };
+    }
+    const total = Number((reply.contentRange || "").trim().split("/").pop());
+    let most = m.size;
+    let exact = false;
+    if (m.yieldTail !== undefined && total >= 0) {
+      most = Math.max(0, Math.min(m.size, Math.min(m.end, Math.max(m.start, total - m.yieldTail)) - m.start));
+      exact = most < m.size;
+    }
+    let bytes = await read(exact ? most : most + 1);
+    if (m.suffix) {
+      const [from, , length] = (reply.contentRange || "").trim().replace("bytes ", "").split(/[-/]/).map(Number);
+      const good = from === Math.max(0, length - m.size) && bytes.byteLength === length - from;
+      outcome(m.group).resolve(good ? length : null);
+    } else if (exact) {
+      // Stopped where the suffix starts: the rest too, unless the suffix brings it.
+      const grace = Math.max(performance.now() - started, 250);
+      const late = new Promise((r) => setTimeout(() => r(null), grace));
+      if ((await Promise.race([outcome(m.group).promise, late])) !== total) {
+        const suffix = controllers.get(m.suffixId);
+        if (suffix) suffix.abort();
+        bytes = Buffer.concat([bytes, await read(m.size - most + 1)]);
+      }
+    }
+    return { ...reply, bytes: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength), received };
+  } finally {
+    if (reader) await reader.cancel().catch(() => {});
+    if (m.suffix) outcome(m.group).resolve(null);
+    if (!m.suffix) suffixes.delete(m.group);
   }
-  const { buffer, byteOffset, byteLength } = Buffer.concat(parts);
-  return { ...reply, bytes: buffer.slice(byteOffset, byteOffset + byteLength) };
 }
 port.on("message", async (m) => {
   if (m.abort) { const c = controllers.get(m.id); if (c) c.abort(); return; }
@@ -443,14 +857,37 @@ function startFetcher() {
 /** Fetches `ranges` in parallel on the fetcher thread; blocks until all answer. */
 function fetchOverThread(url, ranges, timeoutMs, limit) {
     const current = (fetcher ??= startFetcher());
-    const deadline = performance.now() + timeoutMs;
+    const started = performance.now();
+    const deadline = started + timeoutMs;
+    let suffixDeadline = Number.POSITIVE_INFINITY;
+    let expired = false;
     const pending = new Map();
+    const order = new Map();
+    // A round's ranges and its suffix are one group: a range that stops where the suffix starts
+    // waits on what the suffix came to (see FETCHER_SOURCE).
+    const group = current.nextId;
+    const suffixId = current.nextId + ranges.findIndex((range) => "suffix" in range);
     for (const range of ranges) {
         const id = current.nextId++;
         pending.set(id, range);
-        current.port.postMessage({ id, url, start: range.start, end: range.end, limit });
+        order.set(range, order.size);
+        // A suffix's answer is read no further than the suffix: past it, it isn't one.
+        const suffix = "suffix" in range;
+        current.port.postMessage({
+            id,
+            url,
+            range: rangeHeader(range),
+            suffix,
+            limit: suffix ? Math.min(range.suffix, limit) : limit,
+            size: suffix ? Math.min(range.suffix, limit) : range.end - range.start,
+            start: suffix ? 0 : range.start,
+            end: suffix ? 0 : range.end,
+            yieldTail: suffix ? undefined : range.yieldTail,
+            group,
+            suffixId,
+        });
     }
-    const answers = [];
+    const answers = ranges.map(() => null);
     let failure = null;
     let seen = Atomics.load(current.flag, 0);
     while (pending.size > 0) {
@@ -465,6 +902,13 @@ function fetchOverThread(url, ranges, timeoutMs, limit) {
                 continue; // a reply to a request that already timed out
             }
             pending.delete(reply.id);
+            if ("suffix" in range) {
+                answers[order.get(range)] =
+                    reply.failed === undefined && !reply.overLimit
+                        ? suffixAnswerOf(range, reply.status, reply.contentRange, reply.etag, new Uint8Array(reply.bytes), reply.received)
+                        : null;
+                continue;
+            }
             try {
                 if (reply.failed !== undefined) {
                     throw new PdfError("fetch-failed", `the ranged read failed: ${reply.failed}`);
@@ -472,7 +916,7 @@ function fetchOverThread(url, ranges, timeoutMs, limit) {
                 if (reply.overLimit) {
                     throw tooLarge(limit);
                 }
-                answers.push(answerOf(range, reply.status, reply.contentRange, reply.etag, new Uint8Array(reply.bytes), limit));
+                answers[order.get(range)] = answerOf(range, reply.status, reply.contentRange, reply.etag, new Uint8Array(reply.bytes), limit, reply.received);
             }
             catch (error) {
                 failure ??= error;
@@ -481,13 +925,27 @@ function fetchOverThread(url, ranges, timeoutMs, limit) {
         if (pending.size === 0) {
             break;
         }
-        const remaining = deadline - performance.now();
-        if (remaining <= 0 || Atomics.wait(current.flag, 0, seen, remaining) === "timed-out") {
+        // Only suffixes left: they get a grace, then count as unanswered (suffixGrace).
+        const now = performance.now();
+        if (suffixDeadline === Number.POSITIVE_INFINITY && [...pending.values()].every((request) => "suffix" in request)) {
+            suffixDeadline = now + suffixGrace(now - started);
+        }
+        const until = Math.min(suffixDeadline, deadline);
+        if (now < until && Atomics.wait(current.flag, 0, seen, until - now) !== "timed-out") {
+            seen = Atomics.load(current.flag, 0);
+            continue;
+        }
+        if (expired) {
             for (const id of pending.keys()) {
                 current.port.postMessage({ id, abort: true });
             }
+            if ([...pending.values()].every((request) => "suffix" in request)) {
+                break; // the suffixes stay unanswered
+            }
             throw new PdfError("timeout", `the ranged read timed out after ${timeoutMs} ms. This thread is blocked while it waits, so a server running on the same thread can never answer; run the read on a worker thread.`);
         }
+        // Once more through what arrived, then give up.
+        expired = true;
         seen = Atomics.load(current.flag, 0);
     }
     if (failure) {