@2018kguo/recto 0.1.0 → 0.5.0

package/dist/pool.js

@@ -0,0 +1,295 @@
+// 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;
+    #maxDecodedBytes;
+    #threads = [];
+    /** Started and not yet ready. */
+    #startingThreads = new Set();
+    #queue = [];
+    #nextFile = 0;
+    #nextId = 0;
+    #closed = false;
+    constructor(limit, assetBase, maxDecodedBytes) {
+        this.#limit = limit;
+        this.#ceiling = limit;
+        this.#assetBase = assetBase;
+        this.#maxDecodedBytes = maxDecodedBytes;
+    }
+    #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, maxDecodedBytes: this.#maxDecodedBytes };
+            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),
+            links: (index) => call("links", 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."));
+                }
+                const { width, maxHeight, region } = renderOptions ?? {};
+                return call("render", index, region === undefined ? { width, maxHeight } : { width, maxHeight, region });
+            }),
+            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;
+    const maxDecodedBytes = options.maxDecodedBytes;
+    if (maxDecodedBytes !== undefined && !(typeof maxDecodedBytes === "number" && maxDecodedBytes >= 0)) {
+        throw new RangeError("maxDecodedBytes must be a number of bytes, 0 or more");
+    }
+    return new Pool(threads, assetBase, maxDecodedBytes);
+}

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. */
@@ -35,18 +43,36 @@ export type PdfRangedStats = {
 export type PdfRangedDocument = PdfDocument & {
     stats(): PdfRangedStats;
 };
+/**
+ * Bytes `start..end`. With `yieldTail`, read no further than that many bytes before the file's
+ * end, where a suffix asked for beside it starts, so no byte comes twice.
+ */
 type Range = {
     start: number;
     end: number;
+    yieldTail?: number;
+};
+/** The file's last `suffix` bytes (`bytes=-n`), asked for before its size is known. */
+type Suffix = {
+    suffix: number;
 };
+type Request = Range | Suffix;
+/** `received`: the bytes read off the response, `bytes` and any read past it. */
 type Answer = {
     start: number;
     bytes: Uint8Array;
     length: number;
     etag: string | null;
+    status: number;
+    received: number;
 };
-/** Fetches `ranges`; `limit` is how many bytes may still arrive. */
-type Fetch = (ranges: Range[], timeoutMs: number, limit: number) => Answer[];
+/**
+ * Fetches `requests` in parallel; `limit` is how many bytes may still arrive. A range that
+ * fails throws. A suffix that isn't answered as one (a server that ignores or refuses it)
+ * gives null, and isn't counted: the caller asks for the tail by its offset instead.
+ */
+type Fetch = (requests: Request[], timeoutMs: number, limit: number) => (Answer | null)[];
+type FetchAsync = (requests: Request[], timeoutMs: number, limit: number) => Promise<(Answer | null)[]>;
 /** Fetched chunks of one file and the policy for fetching more. */
 declare class RangeLoader {
     #private;
@@ -58,28 +84,37 @@ declare class RangeLoader {
         chunkBytes: number;
         maxBytes: number;
         timeoutMs: number;
+        totalTimeoutMs: number;
         signal: AbortSignal | undefined;
     });
     stats(): PdfRangedStats;
     /** Fetches chunks `firstChunk..endChunk`, keeping only those not held yet. */
     fetchChunks(firstChunk: number, endChunk: number): void;
+    /**
+     * 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.
+     */
+    begin(fetchAsync: FetchAsync | null): Promise<void>;
     /**
      * The `startxref` offset in the fetched last chunk, if it names one. Null for a linearized
      * file, whose trailer points at the first-page section near the head.
      */
     startxref(): number | null;
     /**
-     * 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: number, out: Uint8Array): boolean;
+    read(offset: number, out: Uint8Array, ahead?: number): boolean;
 }
 /**
- * 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 declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): RangeLoader;
+export declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): Promise<RangeLoader>;
 /**
  * The caller's source in a form that stays valid across an await: bytes copied, a URL as an
  * absolute http(s) string. Runs before anything asynchronous.