@2018kguo/recto 0.1.0 → 0.3.0

package/dist/pool.js

@@ -0,0 +1,287 @@
+// Pages read and drawn across worker threads, from one call per page. Each thread has its own
+// engine and, the first time it's given a page of a document, its own copy of the file; a thread
+// starts only when there's work and none is free, so calls made one at a time stay on one thread.
+// No special headers: SharedArrayBuffer only saves a copy, where it's allowed.
+//
+// No call waits for ever on a thread that's gone: a thread reports a failed start, its death fails its
+// call, and one that has said nothing by START_TIMEOUT_MS counts as dead. A call that's running can't be
+// stopped, only the page budgets end it, or `close()`.
+import { PdfError } from "./errors.js";
+/**
+ * The pool's copy of a file. Shared memory where it's allowed (Node, or a page with COOP and COEP), so that
+ * telling each thread about the file doesn't copy it again before the thread copies it into its wasm.
+ */
+function privateCopy(view) {
+    if (typeof SharedArrayBuffer !== "function") {
+        return view.slice();
+    }
+    const copy = new Uint8Array(new SharedArrayBuffer(view.byteLength));
+    copy.set(view);
+    return copy;
+}
+/** Longer than a thread's slowest fetch of its wasm (ASSET_TIMEOUT_MS), and its compile. */
+const START_TIMEOUT_MS = 90_000;
+const MAX_THREADS = 64;
+function defaultThreads() {
+    const cores = globalThis.process?.getBuiltinModule?.("node:os")?.availableParallelism() ?? navigator.hardwareConcurrency ?? 2;
+    return Math.max(1, Math.min(8, cores - 1));
+}
+function failureOf(failure) {
+    if (failure.code) {
+        return new PdfError(failure.code, failure.message);
+    }
+    // A bad argument stays what it is on a single thread.
+    const type = failure.name === "RangeError" ? RangeError : failure.name === "TypeError" ? TypeError : Error;
+    return new type(failure.message);
+}
+const closedError = () => new PdfError("closed", "this document or pool is closed");
+class Pool {
+    #limit;
+    #ceiling;
+    #assetBase;
+    #threads = [];
+    /** Started and not yet ready. */
+    #startingThreads = new Set();
+    #queue = [];
+    #nextFile = 0;
+    #nextId = 0;
+    #closed = false;
+    constructor(limit, assetBase) {
+        this.#limit = limit;
+        this.#ceiling = limit;
+        this.#assetBase = assetBase;
+    }
+    #spawn() {
+        const thread = { worker: null, running: null };
+        this.#startingThreads.add(thread);
+        let dead = false;
+        let waiting;
+        const onMessage = (message) => {
+            if (this.#closed) {
+                void thread.worker.terminate();
+                return;
+            }
+            if (message.startFailed) {
+                onDeath(message.failure.message, failureOf(message.failure));
+                return;
+            }
+            if (message.ready) {
+                clearTimeout(waiting);
+                this.#startingThreads.delete(thread);
+                this.#threads.push(thread);
+                // Idle, a thread doesn't keep a Node process alive; a call under way does.
+                thread.worker.unref?.();
+            }
+            else {
+                const task = thread.running;
+                thread.running = null;
+                thread.worker.unref?.();
+                // It'll need the file again: this was the call that was to open it.
+                if (!message.opened) {
+                    task.file.on.delete(thread);
+                }
+                if (message.failure) {
+                    task.reject(failureOf(message.failure));
+                }
+                else {
+                    task.resolve(message.result);
+                }
+            }
+            this.#pump();
+        };
+        // In Node a failure is an `error` and then an `exit`.
+        const onDeath = (reason, typed) => {
+            if (dead || this.#closed) {
+                return;
+            }
+            dead = true;
+            clearTimeout(waiting);
+            void thread.worker?.terminate();
+            const failure = typed ?? new PdfError("crash", `a pool thread stopped: ${String(reason)}`, reason);
+            if (this.#startingThreads.delete(thread)) {
+                // It couldn't start, so another wouldn't either: run on what's left, or fail what's waiting.
+                this.#limit = this.#threads.length + this.#startingThreads.size;
+                if (this.#limit === 0) {
+                    // The next call tries again: what stopped it, a missing file say, may be back by then.
+                    this.#limit = this.#ceiling;
+                    for (const task of this.#queue.splice(0)) {
+                        task.reject(failure);
+                    }
+                }
+            }
+            else {
+                this.#threads.splice(this.#threads.indexOf(thread), 1);
+            }
+            thread.running?.file.on.delete(thread);
+            thread.running?.reject(failure);
+            thread.running = null;
+            this.#pump();
+        };
+        waiting = setTimeout(() => onDeath(`it hadn't started after ${START_TIMEOUT_MS} ms`), START_TIMEOUT_MS);
+        waiting.unref?.();
+        try {
+            const threads = globalThis.process?.getBuiltinModule?.("node:worker_threads");
+            if (threads) {
+                const worker = new threads.Worker(new URL("./pool-worker.js", import.meta.url), { execArgv: [] });
+                worker.on("message", onMessage);
+                worker.on("messageerror", onDeath);
+                worker.on("error", onDeath);
+                worker.on("exit", onDeath);
+                thread.worker = worker;
+            }
+            else {
+                // Not `new URL("…", import.meta.url)`: a bundler would emit the file as it stands for that.
+                const here = import.meta.url;
+                const worker = new URL(here).origin === location.origin
+                    ? // Written out in full: this is the form bundlers recognise, and they emit the worker for it.
+                        new Worker(new URL("./pool-worker.js", import.meta.url), { type: "module" })
+                    : // A worker's script has to be of this page's origin, so from a CDN it's one line that imports the
+                        // real one, which the CDN has to allow with CORS, as it does the wasm.
+                        // ponytail: the blob's URL lives as long as the page; one per thread started.
+                        new Worker(URL.createObjectURL(new Blob([`import ${JSON.stringify(new URL("./pool-worker.js", here).href)};`], { type: "text/javascript" })), { type: "module" });
+                worker.onmessage = ({ data }) => onMessage(data);
+                worker.onmessageerror = () => onDeath("a message from it could not be read");
+                worker.onerror = (event) => {
+                    event.preventDefault();
+                    onDeath(event.message || "its script did not load");
+                };
+                thread.worker = worker;
+            }
+            const start = { assetBase: this.#assetBase };
+            thread.worker.postMessage(start);
+        }
+        catch (error) {
+            onDeath(error);
+        }
+    }
+    /** Gives each free thread work, the oldest call on a document it has if there is one. */
+    #pump() {
+        for (const thread of this.#threads) {
+            if (thread.running || this.#queue.length === 0) {
+                continue;
+            }
+            let at = this.#queue.findIndex((task) => task.file.on.has(thread));
+            if (at < 0) {
+                // Not a copy of the file for a call that a thread already holding it will take next.
+                const free = this.#threads.filter((other) => !other.running);
+                at = this.#queue.findIndex((task) => !free.some((other) => task.file.on.has(other)));
+            }
+            if (at < 0) {
+                continue;
+            }
+            const [task] = this.#queue.splice(at, 1);
+            thread.running = task;
+            thread.worker.ref?.();
+            const { file } = task;
+            const had = file.on.has(thread);
+            const open = had ? {} : { open: { bytes: file.bytes, password: file.password } };
+            file.on.add(thread);
+            try {
+                thread.worker.postMessage({ ...task.request, id: this.#nextId++, ...open });
+            }
+            catch (error) {
+                // An argument that can't cross. Nothing reached the thread.
+                thread.running = null;
+                thread.worker.unref?.();
+                if (!had) {
+                    file.on.delete(thread);
+                }
+                task.reject(error);
+                // Nothing will come back from the thread to take the next call.
+                this.#pump();
+                return;
+            }
+        }
+        const wanted = Math.min(this.#limit - this.#threads.length, this.#queue.length) - this.#startingThreads.size;
+        for (let i = 0; i < wanted; i++) {
+            this.#spawn();
+        }
+    }
+    #call(file, method, args) {
+        if (file.closed || this.#closed) {
+            return Promise.reject(closedError());
+        }
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ request: { doc: file.id, method, args }, file, resolve, reject });
+            this.#pump();
+        });
+    }
+    async open(input, options = {}) {
+        const view = ArrayBuffer.isView(input) ? input : new Uint8Array(input);
+        const file = {
+            id: this.#nextFile++,
+            bytes: privateCopy(view),
+            password: options.password,
+            closed: false,
+            on: new Set(),
+        };
+        const call = (method, ...args) => this.#call(file, method, args);
+        const pageCount = (await call("pageCount"));
+        const close = async () => {
+            if (file.closed) {
+                return;
+            }
+            file.closed = true;
+            this.#queue = this.#queue.filter((task) => {
+                if (task.file === file) {
+                    task.reject(closedError());
+                }
+                return task.file !== file;
+            });
+            // Each thread frees it when it gets there, past any call of it under way, which still answers.
+            for (const thread of file.on) {
+                thread.worker.postMessage({ id: this.#nextId++, doc: file.id, method: "close", args: [] });
+            }
+            file.on.clear();
+        };
+        return {
+            pageCount,
+            pageInfo: (index) => call("pageInfo", index),
+            text: (index) => call("text", index),
+            objects: (index) => call("objects", index),
+            annotations: (index) => call("annotations", index),
+            outline: () => call("outline"),
+            render: (index, renderOptions) => {
+                if (renderOptions?.signal) {
+                    return Promise.reject(new TypeError("a pool's render takes no signal: a call that's running can't be stopped. pool.close() ends all of them."));
+                }
+                return call("render", index, { width: renderOptions?.width, maxHeight: renderOptions?.maxHeight });
+            },
+            close,
+            [Symbol.asyncDispose]: close,
+        };
+    }
+    stats() {
+        return { threads: this.#threads.length, queued: this.#queue.length };
+    }
+    close() {
+        if (this.#closed) {
+            return;
+        }
+        this.#closed = true;
+        for (const thread of [...this.#threads, ...this.#startingThreads]) {
+            thread.running?.reject(closedError());
+            void thread.worker?.terminate();
+        }
+        for (const task of this.#queue.splice(0)) {
+            task.reject(closedError());
+        }
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+export function startPool(options) {
+    const threads = options.threads ?? defaultThreads();
+    if (!(Number.isInteger(threads) && threads >= 1 && threads <= MAX_THREADS)) {
+        throw new RangeError(`threads must be a whole number from 1 to ${MAX_THREADS}, not ${threads}`);
+    }
+    if (!globalThis.process?.getBuiltinModule?.("node:worker_threads") && typeof Worker === "undefined") {
+        throw new PdfError("wrong-thread", "a pool needs worker threads, which this thread can't start");
+    }
+    // A thread's location isn't this one's, so a relative URL has to be resolved here.
+    const assetBase = options.assetBase !== undefined && typeof location !== "undefined"
+        ? new URL(options.assetBase, location.href).href
+        : options.assetBase;
+    return new Pool(threads, assetBase);
+}

package/dist/ranged.d.ts

@@ -18,6 +18,14 @@ export type PdfRangedOpenOptions = {
     signal?: AbortSignal;
     /** How long one fetch round may block the thread (code "timeout"). Default 30 s. */
     timeoutMs?: number;
+    /**
+     * Wall time for the whole read, from the first fetch on, in place of counting rounds (code "timeout").
+     * A fetch in flight is cut when it runs out, and none starts after; that bounds the network waits, not
+     * the parsing between them. What's already fetched reads until a read fails, after which every call
+     * on the document throws that failure: reopen to go on. In WebKit a response that keeps trickling is
+     * not cut. Default: no limit.
+     */
+    totalTimeoutMs?: number;
 };
 export type PdfRangedStats = {
     /** Bytes received from the source, across every request. */
@@ -44,6 +52,7 @@ type Answer = {
     bytes: Uint8Array;
     length: number;
     etag: string | null;
+    status: number;
 };
 /** Fetches `ranges`; `limit` is how many bytes may still arrive. */
 type Fetch = (ranges: Range[], timeoutMs: number, limit: number) => Answer[];
@@ -58,6 +67,7 @@ declare class RangeLoader {
         chunkBytes: number;
         maxBytes: number;
         timeoutMs: number;
+        totalTimeoutMs: number;
         signal: AbortSignal | undefined;
     });
     stats(): PdfRangedStats;

package/dist/ranged.js

@@ -50,6 +50,8 @@ class RangeLoader {
     #fetch;
     #maxBytes;
     #timeoutMs;
+    #totalTimeoutMs;
+    #deadline;
     #signal;
     constructor(fetch, options) {
         this.#fetch = fetch;
@@ -57,6 +59,8 @@ class RangeLoader {
         this.#readAhead = options.chunkBytes;
         this.#maxBytes = options.maxBytes;
         this.#timeoutMs = options.timeoutMs;
+        this.#totalTimeoutMs = options.totalTimeoutMs;
+        this.#deadline = performance.now() + options.totalTimeoutMs;
         this.#signal = options.signal;
     }
     stats() {
@@ -101,20 +105,35 @@ class RangeLoader {
         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);
+        }
         this.#rounds += 1;
-        const answers = this.#fetch(runs, this.#timeoutMs, this.#maxBytes - this.#bytesFetched);
+        const passesTotal = left < this.#timeoutMs;
+        let answers;
+        try {
+            answers = this.#fetch(runs, passesTotal ? Math.ceil(left) : this.#timeoutMs, this.#maxBytes - this.#bytesFetched);
+        }
+        catch (error) {
+            if (passesTotal && error.code === "timeout") {
+                throw new PdfError("timeout", passedTotal, error);
+            }
+            throw error;
+        }
         for (const answer of answers) {
             this.#requests += 1;
             this.#bytesFetched += answer.bytes.byteLength;
             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})`);
+                throw new PdfError("fetch-failed", `the file changed size during the ranged read (${this.length} bytes, now ${answer.length})`, undefined, answer.status);
             }
             // Before anything is sized from it: the total is whatever the server said.
             if (answer.length > MAX_FILE_BYTES) {
                 throw new PdfError("too-large", `a ranged read holds files up to ${MAX_FILE_BYTES} bytes (this one is ${answer.length}); use open() or a smaller file`);
             }
             if (this.#etag && answer.etag && answer.etag !== this.#etag) {
-                throw new PdfError("fetch-failed", "the file was replaced during the ranged read (its ETag changed)");
+                throw new PdfError("fetch-failed", "the file was replaced during the ranged read (its ETag changed)", undefined, answer.status);
             }
             this.#etag ??= answer.etag;
             this.length = answer.length;
@@ -217,13 +236,14 @@ class RangeLoader {
  */
 export function startRangeLoader(source, options = {}) {
     const positive = (name, value) => {
-        if (value !== undefined && !(value > 0)) {
+        if (value !== undefined && !(typeof value === "number" && value > 0)) {
             throw new RangeError(`${name} must be above 0 (got ${value})`);
         }
     };
     positive("chunkBytes", options.chunkBytes);
     positive("maxBytes", options.maxBytes);
     positive("timeoutMs", options.timeoutMs);
+    positive("totalTimeoutMs", options.totalTimeoutMs);
     if (options.chunkBytes !== undefined && !Number.isSafeInteger(options.chunkBytes)) {
         throw new RangeError(`chunkBytes must be a whole number (got ${options.chunkBytes})`);
     }
@@ -235,6 +255,7 @@ export function startRangeLoader(source, options = {}) {
         chunkBytes,
         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);
@@ -281,6 +302,7 @@ function fetcherFor(source) {
             bytes: bytes.subarray(start, Math.min(end, bytes.byteLength)),
             length: bytes.byteLength,
             etag: null,
+            status: 206,
         }));
     }
     const url = source;
@@ -303,24 +325,25 @@ function answerOf(range, status, contentRange, etag, bytes, limit) {
         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 };
+        return { start: 0, bytes, length: bytes.byteLength, etag, status };
     }
     if (status !== 206) {
-        throw new PdfError("fetch-failed", `the ranged read failed (HTTP ${status})`);
+        throw new PdfError("fetch-failed", `the ranged read failed (HTTP ${status})`, undefined, status);
     }
     const match = /^bytes (\d+)-\d+\/(\d+)$/u.exec(contentRange?.trim() ?? "");
     if (!match) {
         throw new PdfError("fetch-failed", "the server's 206 answer has no usable Content-Range (with a total length). " +
-            "A cross-origin server must also send Access-Control-Expose-Headers: Content-Range.");
+            "A cross-origin server must also send Access-Control-Expose-Headers: Content-Range.", undefined, status);
     }
     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})`);
+        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);
     }
-    return { start, bytes, length, etag };
+    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) {
     const deadline = performance.now() + timeoutMs;
     return ranges.map((range) => {
@@ -336,7 +359,11 @@ function fetchOverXhr(url, ranges, timeoutMs, limit) {
             const timedOut = error.name === "TimeoutError";
             throw new PdfError(timedOut ? "timeout" : "fetch-failed", timedOut
                 ? `the ranged read timed out after ${timeoutMs} ms`
-                : "the ranged read failed: the network, or a cross-origin server that does not allow it", error);
+                : NO_ANSWER, error);
+        }
+        // Firefox reports a refused cross-origin read as status 0, not a throw.
+        if (xhr.status === 0) {
+            throw new PdfError("fetch-failed", NO_ANSWER);
         }
         return answerOf(range, xhr.status, xhr.getResponseHeader("Content-Range"), xhr.getResponseHeader("ETag"), new Uint8Array(xhr.response), limit);
     });
@@ -364,7 +391,7 @@ async function get(m, signal) {
   }
   const parts = [];
   let size = 0;
-  for await (const part of response.body) {
+  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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2018kguo/recto",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A PDF engine for JavaScript: text with boxes, page objects, annotations and rendering, in Rust compiled to WebAssembly.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,7 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./wasm/*": "./wasm/*",
     "./package.json": "./package.json"
   },
   "files": [