@2018kguo/recto 0.0.0-stage → 0.3.0

package/dist/pool-worker.d.ts

@@ -0,0 +1,14 @@
+export type PoolRequest = {
+    id: number;
+    doc: number;
+    /** Only until this thread has the document. */
+    open?: {
+        bytes: Uint8Array;
+        password: string | undefined;
+    };
+    method: string;
+    args: unknown[];
+};
+export type PoolStart = {
+    assetBase: string | undefined;
+};

package/dist/pool-worker.js

@@ -0,0 +1,65 @@
+// One thread of a pool: opens what it's sent on demand, and answers each call with its result.
+import { createPdfEngine } from "./engine.js";
+const parent = globalThis.process?.getBuiltinModule?.("node:worker_threads")?.parentPort;
+const port = (parent ?? self);
+const docs = new Map();
+let engine;
+/** Every column in a result, so it moves rather than being copied. */
+function buffersIn(value, found) {
+    if (ArrayBuffer.isView(value)) {
+        found.add(value.buffer);
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const inner of Object.values(value)) {
+            buffersIn(inner, found);
+        }
+    }
+}
+async function answer({ doc: id, open, method, args }) {
+    let doc = docs.get(id);
+    if (!doc) {
+        doc = await engine.open(open.bytes, open.password === undefined ? {} : { password: open.password });
+        docs.set(id, doc);
+    }
+    if (method === "pageCount") {
+        return doc.pageCount;
+    }
+    return doc[method](...args);
+}
+function failureOf(error) {
+    const { name, code, message } = error;
+    return { name, code, message: message ?? String(error) };
+}
+async function handle(message) {
+    if (!("id" in message)) {
+        const { assetBase } = message;
+        try {
+            engine = await createPdfEngine(assetBase ? { assetBase } : {});
+            port.postMessage({ ready: true }, []);
+        }
+        catch (error) {
+            port.postMessage({ startFailed: true, failure: failureOf(error) }, []);
+        }
+        return;
+    }
+    if (message.method === "close") {
+        docs.get(message.doc)?.close();
+        docs.delete(message.doc);
+        return;
+    }
+    try {
+        const result = await answer(message);
+        const buffers = new Set();
+        buffersIn(result, buffers);
+        port.postMessage({ result, opened: docs.has(message.doc) }, [...buffers]);
+    }
+    catch (error) {
+        port.postMessage({ failure: failureOf(error), opened: docs.has(message.doc) }, []);
+    }
+}
+if (parent) {
+    parent.on("message", (message) => void handle(message));
+}
+else {
+    self.onmessage = ({ data }) => void handle(data);
+}

package/dist/pool.d.ts

@@ -0,0 +1,36 @@
+import type { PdfAnnotation, PdfBitmap, PdfOutlineItem, PdfPageInfo, PdfPageObjects, PdfPageText, PdfRenderOptions } from "./document.ts";
+export type PdfPoolOptions = {
+    /** At most this many threads, up to 64. Default: one less than the machine's cores, up to 8. */
+    threads?: number;
+    /** As for `createPdfEngine`. A string: it crosses to the threads. */
+    assetBase?: string;
+};
+export type PdfPoolOpenOptions = {
+    password?: string;
+};
+/** A `PdfDocument` whose calls run on the pool's threads, each a promise. */
+export interface PdfPoolDocument {
+    readonly pageCount: number;
+    pageInfo(index: number): Promise<PdfPageInfo>;
+    text(index: number): Promise<PdfPageText>;
+    objects(index: number): Promise<PdfPageObjects>;
+    annotations(index: number): Promise<PdfAnnotation[]>;
+    outline(): Promise<PdfOutlineItem[]>;
+    /** Takes no `signal`: a call that's running can't be stopped. */
+    render(index: number, options: PdfRenderOptions): Promise<PdfBitmap>;
+    /** Frees it on every thread, and fails its calls still waiting with `closed`. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export interface PdfPool {
+    open(bytes: Uint8Array | ArrayBuffer, options?: PdfPoolOpenOptions): Promise<PdfPoolDocument>;
+    /** Threads started so far, and calls waiting for one. */
+    stats(): {
+        threads: number;
+        queued: number;
+    };
+    /** Stops every thread now: anything unfinished fails with `closed`. */
+    close(): void;
+    [Symbol.dispose](): void;
+}
+export declare function startPool(options: PdfPoolOptions): PdfPool;

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

@@ -0,0 +1,98 @@
+import { PdfError } from "./errors.ts";
+import type { PdfDocument } from "./document.ts";
+/**
+ * Where a ranged document's bytes come from: an HTTP(S) URL, or bytes in memory (copied, so
+ * the caller may reuse the buffer).
+ */
+export type PdfRangeSource = string | URL | Uint8Array;
+export type PdfRangedOpenOptions = {
+    password?: string;
+    /** Smallest fetch and the cache's unit, above 0. Default 64 KiB. */
+    chunkBytes?: number;
+    /** Fail (code "too-large") rather than fetch more than this in total. Default 64 MiB. */
+    maxBytes?: number;
+    /**
+     * Checked before the open and before every fetch. The thread is blocked during a fetch, so
+     * an abort cannot interrupt one; `timeoutMs` bounds that.
+     */
+    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. */
+    bytesFetched: number;
+    requests: number;
+    /** Fetch rounds (round trips); a round's requests run in parallel. */
+    rounds: number;
+    /** The engine's reads, and the bytes they asked for: the parse work. */
+    reads: number;
+    readBytes: number;
+    /** The file's full size, from the first response. */
+    fileBytes: number;
+};
+/** A document opened over byte ranges. Use and close it like any other. */
+export type PdfRangedDocument = PdfDocument & {
+    stats(): PdfRangedStats;
+};
+type Range = {
+    start: number;
+    end: number;
+};
+type Answer = {
+    start: number;
+    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[];
+/** Fetched chunks of one file and the policy for fetching more. */
+declare class RangeLoader {
+    #private;
+    length: number;
+    readonly chunkBytes: number;
+    /** Set once a fetch failed; every later read fails and every call throws it. */
+    failure: PdfError | null;
+    constructor(fetch: Fetch, options: {
+        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 `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.
+     */
+    read(offset: number, out: Uint8Array): 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.
+ */
+export declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): 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.
+ */
+export declare function ownedSource(source: PdfRangeSource): string | Uint8Array;
+export {};