knitting 0.1.56 → 0.1.60

package/src/runtime/compiled-builder.js

@@ -0,0 +1,42 @@
+import { getNodeBuiltinModule, getNodeProcess } from "../common/node-compat.js";
+const filePath = (href) => {
+    const converter = getNodeBuiltinModule("node:url")?.fileURLToPath;
+    if (converter !== undefined)
+        return converter(href);
+    return decodeURIComponent(new URL(href).pathname);
+};
+const runtimeExecutable = () => {
+    const process = getNodeProcess();
+    return process?.versions?.bun !== undefined && process.execPath !== undefined
+        ? process.execPath
+        : "bun";
+};
+export const buildCompiledWorkerArtifact = ({ inspection, source, tasks, options, }) => {
+    const childProcess = getNodeBuiltinModule("node:child_process");
+    if (childProcess === undefined) {
+        throw new Error("automatic compilation requires Bun or Node child processes");
+    }
+    const builder = filePath(new URL("../../scripts/build-compiled-worker.ts", import.meta.url).href);
+    const args = [
+        builder,
+        "--module",
+        filePath(source),
+        "--out",
+        filePath(inspection.artifactHref),
+        "--manifest",
+        filePath(inspection.manifestHref),
+        "--tasks",
+        tasks.join(","),
+    ];
+    if (options?.compiler !== undefined) {
+        args.push("--porf", options.compiler);
+    }
+    const result = childProcess.spawnSync(runtimeExecutable(), args, {
+        stdio: "inherit",
+    });
+    if (result.error !== undefined)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error("compiled worker build exited with code " + result.status);
+    }
+};

package/src/runtime/compiled-worker.d.ts

@@ -0,0 +1,27 @@
+import { type SignalAbortStore } from "../shared/abortSignal.js";
+import type { WorkerContext, WorkerSettings } from "../types.js";
+type CompiledAbortChannel = SignalAbortStore & {
+    /** Passed to the child so it can map the same bitmap. */
+    environment: Record<string, string>;
+    close: () => void;
+};
+/**
+ * Host half of the abort bitmap. Slot bookkeeping is the same allocator every
+ * other lane uses; only the backing store differs, because a compiled child is
+ * a separate process and reads the words through named POSIX shared memory.
+ */
+export declare const createCompiledAbortChannel: (requestedMax?: number) => CompiledAbortChannel;
+type CompiledWorkerContext = WorkerContext & {
+    dispatcherCheck?: never;
+    laneWake?: never;
+    bindSend?: never;
+};
+export declare const spawnCompiledWorkerContext: ({ list, names, workerOptions, hostDebug, abortSignalCapacity, usesAbortSignal, }: {
+    list: string[];
+    names: string[];
+    workerOptions: WorkerSettings;
+    hostDebug?: (message: string) => void;
+    abortSignalCapacity?: number;
+    usesAbortSignal?: boolean;
+}) => CompiledWorkerContext;
+export {};

package/src/runtime/compiled-worker.js

@@ -0,0 +1,562 @@
+import { getNodeBuiltinModule, getNodeProcess } from "../common/node-compat.js";
+import { ProcessSharedBuffer, getDefaultProcessSharedBufferPrimitives, isProcessSharedBufferValue, } from "../connections/process-shared-buffer.js";
+import { withResolvers } from "../common/with-resolvers.js";
+import { AbortSignalPoolExhausted, OneShotDeferred, signalAbortFactory, } from "../shared/abortSignal.js";
+import { COMPILED_WORKER_JSON_PROTOCOL, inspectCompiledWorkerArtifact, } from "./compiled-artifact.js";
+import { buildCompiledWorkerArtifact } from "./compiled-builder.js";
+/** Matches the `abortSignalCapacity` default documented on pool options. */
+const DEFAULT_ABORT_SLOTS = 258;
+/** Both directions of the JSON protocols share this frame budget. */
+const MAX_PAYLOAD_BYTES = 1024 * 1024;
+/** Sentinel written to the slot field when a task is not abort-aware. */
+const NO_ABORT_SLOT = -1;
+/** Requests carry i32 task, i32 abort slot, then either a length or an f64. */
+const JSON_HEADER_BYTES = 12;
+const NUMBER_FRAME_BYTES = 16;
+const NUMBER_ARGUMENT_OFFSET = 8;
+const EMPTY_PAYLOAD = new Uint8Array(0);
+const deno = globalThis.Deno;
+const spawnNodeProcess = (artifact, environment) => {
+    const childProcess = getNodeBuiltinModule("node:child_process");
+    if (childProcess === undefined)
+        return undefined;
+    const child = childProcess.spawn(artifact, [], {
+        stdio: ["pipe", "pipe", "inherit"],
+        env: environment === undefined
+            ? undefined
+            : { ...(getNodeProcess()?.env ?? {}), ...environment },
+    });
+    let dataListener = () => { };
+    let errorListener = () => { };
+    child.stdout.on("data", (data) => dataListener(data));
+    child.on("error", (error) => errorListener(error));
+    const exited = new Promise((resolve) => {
+        child.on("exit", (code) => resolve(code ?? -1));
+    });
+    return {
+        write: async (data) => {
+            child.stdin.write(data);
+        },
+        closeInput: () => new Promise((resolve) => {
+            child.stdin.end(resolve);
+        }),
+        kill: () => void child.kill("SIGTERM"),
+        exited,
+        onData: (listener) => void (dataListener = listener),
+        onError: (listener) => void (errorListener = listener),
+    };
+};
+const spawnDenoProcess = (artifact, environment) => {
+    if (deno?.Command === undefined)
+        return undefined;
+    const child = new deno.Command(artifact, {
+        stdin: "piped",
+        stdout: "piped",
+        stderr: "inherit",
+        ...(environment === undefined ? {} : { env: environment }),
+    }).spawn();
+    const writer = child.stdin.getWriter();
+    const reader = child.stdout.getReader();
+    let dataListener = () => { };
+    let errorListener = () => { };
+    void (async () => {
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                dataListener(next.value);
+            }
+        }
+        catch (error) {
+            errorListener(error);
+        }
+    })();
+    return {
+        write: async (data) => {
+            await writer.write(data);
+        },
+        closeInput: async () => {
+            await writer.close();
+        },
+        kill: () => child.kill("SIGTERM"),
+        exited: child.status.then((status) => status.code),
+        onData: (listener) => void (dataListener = listener),
+        onError: (listener) => void (errorListener = listener),
+    };
+};
+const spawnNativeProcess = (artifact, environment) => {
+    const process = spawnNodeProcess(artifact, environment) ??
+        spawnDenoProcess(artifact, environment);
+    if (process === undefined) {
+        throw new Error("Compiled workers require child-process support");
+    }
+    return process;
+};
+const compiledAbortName = () => {
+    const pid = getNodeProcess()?.pid ?? deno?.pid ?? 0;
+    const nonce = Math.floor(Math.random() * 0x1000000).toString(36);
+    return `knit_abort_${Math.abs(pid).toString(36)}_${nonce}`.slice(0, 30);
+};
+/**
+ * Host half of the abort bitmap. Slot bookkeeping is the same allocator every
+ * other lane uses; only the backing store differs, because a compiled child is
+ * a separate process and reads the words through named POSIX shared memory.
+ */
+export const createCompiledAbortChannel = (requestedMax = DEFAULT_ABORT_SLOTS) => {
+    const max = Number.isFinite(requestedMax) && requestedMax > 0
+        ? Math.floor(requestedMax)
+        : DEFAULT_ABORT_SLOTS;
+    const byteLength = Math.max(1, Math.ceil(max / 32)) *
+        Uint32Array.BYTES_PER_ELEMENT;
+    const primitives = getDefaultProcessSharedBufferPrimitives();
+    const name = compiledAbortName();
+    const shared = ProcessSharedBuffer.create({ mode: "create", name, size: byteLength }, primitives);
+    let closed = false;
+    return {
+        ...signalAbortFactory({
+            sab: shared.subbuffer(0, byteLength).getRegion(primitives),
+            maxSignals: max,
+        }),
+        environment: {
+            KNITTING_COMPILED_ABORT_SHM: name.startsWith("/") ? name : `/${name}`,
+            KNITTING_COMPILED_ABORT_BYTES: String(byteLength),
+        },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            shared.descriptor.mapping?.close?.();
+            primitives.unlinkSharedMemory?.(name);
+        },
+    };
+};
+// One resolved WorkerSettings object is shared by every lane in a pool. This
+// prevents `build: "always"` from recompiling once per lane.
+const forcedBuildPools = new WeakSet();
+const responseError = (status, taskName) => {
+    if (status === 1) {
+        return new RangeError("Unknown compiled task: " + taskName);
+    }
+    if (status === 2) {
+        return new TypeError("Compiled task " + taskName + " returned an unsupported value");
+    }
+    if (status === 3)
+        return new Error("Compiled task " + taskName + " threw");
+    if (status === 4) {
+        return new RangeError("Compiled task " + taskName + " result is too large");
+    }
+    return new Error("Compiled worker returned unknown status " + status);
+};
+/** Reserved wire key: a plain object carrying it would be ambiguous. */
+const COMPILED_VALUE_TAG = "$knitting";
+const ARRAY_BUFFER_TAG = "array-buffer";
+const DATA_VIEW_TAG = "data-view";
+/** Wire tag to view constructor, read by both directions of the codec. */
+const TYPED_ARRAYS = {
+    u8: Uint8Array,
+    u8c: Uint8ClampedArray,
+    i8: Int8Array,
+    u16: Uint16Array,
+    i16: Int16Array,
+    u32: Uint32Array,
+    i32: Int32Array,
+    f32: Float32Array,
+    f64: Float64Array,
+};
+const typedArrayTags = new Map(Object.entries(TYPED_ARRAYS).map(([tag, view]) => [view, tag]));
+const binaryTagOf = (value) => value instanceof ArrayBuffer
+    ? ARRAY_BUFFER_TAG
+    : value instanceof DataView
+        ? DATA_VIEW_TAG
+        : typedArrayTags.get(value.constructor);
+const rawBytes = (value) => value instanceof ArrayBuffer
+    ? new Uint8Array(value)
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+// String.fromCharCode is applied in chunks so a megabyte payload cannot
+// overflow the argument list.
+const BASE64_CHUNK = 0x8000;
+const toBase64 = (bytes) => {
+    let latin1 = "";
+    for (let at = 0; at < bytes.length; at += BASE64_CHUNK) {
+        latin1 += String.fromCharCode(...bytes.subarray(at, at + BASE64_CHUNK));
+    }
+    return btoa(latin1);
+};
+const fromBase64 = (text) => {
+    if (typeof text !== "string") {
+        throw new TypeError("Compiled binary value is not base64 text");
+    }
+    return Uint8Array.from(atob(text), (character) => character.charCodeAt(0));
+};
+/**
+ * Validates a value and rewrites it for the wire: buffers and views travel as
+ * tagged base64, and a named ProcessSharedBuffer travels as a mapping request
+ * the child fulfils by mapping the same shared memory itself.
+ */
+const encodeCompiledValue = (value, ancestors = new Set()) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || Object.is(value, -0)) {
+            throw new TypeError("Compiled workers require lossless JSON numbers");
+        }
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new TypeError("Compiled workers only accept JSON-compatible values");
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError("Compiled workers do not accept cyclic values");
+    }
+    if (isProcessSharedBufferValue(value)) {
+        const name = value.descriptor.name;
+        if (name === undefined) {
+            throw new TypeError("Compiled workers require a named ProcessSharedBuffer");
+        }
+        if (value.size > MAX_PAYLOAD_BYTES) {
+            throw new RangeError("Compiled ProcessSharedBuffer values are limited to 1 MiB");
+        }
+        return {
+            [COMPILED_VALUE_TAG]: "process-shared",
+            name: name.startsWith("/") ? name : `/${name}`,
+            size: value.size,
+            offset: value.byteOffset,
+            length: value.byteLength,
+        };
+    }
+    const tag = binaryTagOf(value);
+    if (tag !== undefined) {
+        return {
+            [COMPILED_VALUE_TAG]: tag,
+            data: toBase64(rawBytes(value)),
+        };
+    }
+    if (ArrayBuffer.isView(value)) {
+        throw new TypeError("Compiled workers do not support BigInt typed arrays");
+    }
+    ancestors.add(value);
+    let encoded;
+    if (Array.isArray(value)) {
+        const entries = [];
+        for (let index = 0; index < value.length; index++) {
+            if (!(index in value)) {
+                throw new TypeError("Compiled workers do not accept sparse arrays");
+            }
+            entries.push(encodeCompiledValue(value[index], ancestors));
+        }
+        encoded = entries;
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Compiled workers only accept plain objects");
+        }
+        const record = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === COMPILED_VALUE_TAG) {
+                throw new TypeError("Compiled workers reserve the " + COMPILED_VALUE_TAG + " key");
+            }
+            record[key] = encodeCompiledValue(entry, ancestors);
+        }
+        encoded = record;
+    }
+    ancestors.delete(value);
+    return encoded;
+};
+const decodeCompiledValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(decodeCompiledValue);
+    if (value === null || typeof value !== "object")
+        return value;
+    const record = value;
+    const tag = record[COMPILED_VALUE_TAG];
+    if (typeof tag === "string") {
+        const bytes = fromBase64(record.data);
+        if (tag === ARRAY_BUFFER_TAG)
+            return bytes.buffer;
+        if (tag === DATA_VIEW_TAG)
+            return new DataView(bytes.buffer);
+        const view = TYPED_ARRAYS[tag];
+        if (view === undefined) {
+            throw new TypeError("Compiled worker returned an unknown binary value");
+        }
+        if (bytes.byteLength % view.BYTES_PER_ELEMENT !== 0) {
+            throw new TypeError("Compiled worker returned misaligned binary data");
+        }
+        return new view(bytes.buffer);
+    }
+    const decoded = {};
+    for (const [key, entry] of Object.entries(record)) {
+        decoded[key] = decodeCompiledValue(entry);
+    }
+    return decoded;
+};
+const asciiJson = (value) => {
+    const wireValue = encodeCompiledValue(value);
+    const serialized = JSON.stringify(wireValue);
+    if (serialized !== undefined) {
+        for (let index = 0; index < serialized.length; index++) {
+            const unit = serialized.charCodeAt(index);
+            if (unit >= 0xd800 && unit <= 0xdfff) {
+                throw new TypeError("Compiled workers do not yet support non-BMP Unicode");
+            }
+        }
+    }
+    return serialized?.replace(/[^\x00-\x7f]/g, (character) => "\\u" + character.charCodeAt(0).toString(16).padStart(4, "0"));
+};
+export const spawnCompiledWorkerContext = ({ list, names, workerOptions, hostDebug, abortSignalCapacity, usesAbortSignal, }) => {
+    if (list.length !== 1) {
+        throw new Error("A compiled worker pool must use one task module");
+    }
+    let inspection = inspectCompiledWorkerArtifact({
+        source: list[0],
+        options: workerOptions.compiled,
+        requiredTasks: names,
+    });
+    const forceBuild = workerOptions.compiled?.build === "always" &&
+        !forcedBuildPools.has(workerOptions);
+    if (forceBuild)
+        forcedBuildPools.add(workerOptions);
+    if (forceBuild ||
+        (!inspection.compiled && workerOptions.compiled?.build !== false)) {
+        try {
+            buildCompiledWorkerArtifact({
+                inspection,
+                source: list[0],
+                tasks: names,
+                options: workerOptions.compiled,
+            });
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            throw new Error("Compiled worker could not be built: " + message +
+                ". Initial validation: " + (inspection.reason ?? "unknown reason"));
+        }
+        inspection = inspectCompiledWorkerArtifact({
+            source: list[0],
+            options: workerOptions.compiled,
+            requiredTasks: names,
+        });
+    }
+    if (!inspection.compiled || inspection.taskEntries === undefined) {
+        throw new Error("Compiled worker is unavailable: " +
+            (inspection.reason ?? "unknown reason") + ". Expected " +
+            inspection.artifact + " with " + inspection.manifest);
+    }
+    const artifactIndex = new Map(inspection.taskEntries.map((task) => [task.exportName, task.index]));
+    const taskIndices = names.map((name) => artifactIndex.get(name));
+    hostDebug?.("compiled artifact=" + inspection.artifact +
+        " compiler=" + inspection.compiler);
+    const abortChannel = usesAbortSignal === true
+        ? createCompiledAbortChannel(abortSignalCapacity)
+        : undefined;
+    let native;
+    try {
+        native = spawnNativeProcess(inspection.artifact, abortChannel?.environment);
+    }
+    catch (error) {
+        abortChannel?.close();
+        throw error;
+    }
+    const jsonProtocol = inspection.protocol === COMPILED_WORKER_JSON_PROTOCOL;
+    const requestHeaderBytes = jsonProtocol
+        ? JSON_HEADER_BYTES
+        : NUMBER_FRAME_BYTES;
+    const pending = [];
+    let responseBytes = new Uint8Array(0);
+    let closing = false;
+    let closedReason;
+    let writeTail = Promise.resolve();
+    const rejectPending = (reason) => {
+        while (pending.length > 0)
+            pending.shift().reject(reason);
+    };
+    const fail = (reason) => {
+        if (closedReason !== undefined)
+            return;
+        closedReason = String(reason?.message ?? reason);
+        rejectPending(new Error(closedReason));
+    };
+    native.onError(fail);
+    native.onData((chunk) => {
+        const merged = new Uint8Array(responseBytes.byteLength + chunk.byteLength);
+        merged.set(responseBytes);
+        merged.set(chunk, responseBytes.byteLength);
+        let offset = 0;
+        while (true) {
+            const headerLength = jsonProtocol ? 8 : 16;
+            if (offset + headerLength > merged.byteLength)
+                break;
+            const header = new DataView(merged.buffer, merged.byteOffset + offset, headerLength);
+            const payloadLength = jsonProtocol ? header.getUint32(4, true) : 8;
+            if (payloadLength > 64 * 1024 * 1024) {
+                fail("Compiled worker returned an oversized response");
+                native.kill();
+                return;
+            }
+            const frameLength = jsonProtocol ? headerLength + payloadLength : 16;
+            if (offset + frameLength > merged.byteLength)
+                break;
+            const pendingCall = pending.shift();
+            if (pendingCall === undefined) {
+                fail("Compiled worker returned an unexpected response");
+                native.kill();
+                return;
+            }
+            const status = header.getInt32(0, true);
+            if (status !== 0) {
+                pendingCall.reject(responseError(status, pendingCall.taskName));
+            }
+            else if (jsonProtocol) {
+                try {
+                    const bytes = merged.subarray(offset + 8, offset + frameLength);
+                    const decoded = JSON.parse(new TextDecoder().decode(bytes));
+                    pendingCall.resolve(decodeCompiledValue(decoded));
+                }
+                catch (error) {
+                    pendingCall.reject(new Error("Compiled worker returned invalid JSON", { cause: error }));
+                }
+            }
+            else {
+                pendingCall.resolve(header.getFloat64(8, true));
+            }
+            offset += frameLength;
+        }
+        responseBytes = merged.slice(offset);
+    });
+    void native.exited.then((code) => {
+        if (!closing || code !== 0) {
+            fail("Compiled worker exited with code " + code);
+        }
+    });
+    const queueWrite = (frame) => {
+        writeTail = writeTail.then(() => native.write(frame));
+        void writeTail.catch(fail);
+        return writeTail;
+    };
+    /**
+     * Everything that can reject a call lives here, so it all runs before an
+     * abort slot is claimed and a claimed slot can never leak.
+     */
+    const encodePayload = (taskName, value) => {
+        if (!jsonProtocol) {
+            if (typeof value !== "number") {
+                throw new TypeError("Compiled worker task " + taskName + " only accepts a number");
+            }
+            return EMPTY_PAYLOAD;
+        }
+        // Porffor's JSON parser is reliable with escaped UTF-16 code units;
+        // keeping request bytes ASCII also avoids depending on its internal
+        // string representation for supplementary Unicode code points.
+        const serialized = asciiJson(value);
+        if (serialized === undefined) {
+            throw new TypeError("Compiled worker task " + taskName +
+                " only accepts JSON-compatible values");
+        }
+        const payload = new TextEncoder().encode(serialized);
+        if (payload.byteLength > MAX_PAYLOAD_BYTES) {
+            throw new RangeError("Compiled worker input is too large");
+        }
+        return payload;
+    };
+    const call = ({ fnNumber, abortSignal, }) => {
+        const taskName = names[fnNumber];
+        const targetIndex = taskIndices[fnNumber];
+        const usesSignal = abortSignal !== undefined;
+        return (rawArgs) => {
+            const deferred = withResolvers();
+            const send = (value) => {
+                if (closedReason !== undefined || closing) {
+                    deferred.reject(new Error(closedReason ?? "Compiled worker is shut down"));
+                    return;
+                }
+                if (usesSignal && abortChannel === undefined) {
+                    deferred.reject(new Error("Compiled worker abort channel is unavailable"));
+                    return;
+                }
+                let payload;
+                try {
+                    payload = encodePayload(taskName, value);
+                }
+                catch (error) {
+                    deferred.reject(error);
+                    return;
+                }
+                const signal = usesSignal ? abortChannel.getSignal() : NO_ABORT_SLOT;
+                if (usesSignal && signal === abortChannel.closeNow) {
+                    deferred.reject(AbortSignalPoolExhausted);
+                    return;
+                }
+                if (usesSignal) {
+                    new OneShotDeferred(deferred, () => abortChannel.resetSignal(signal), () => abortChannel.setSignal(signal));
+                }
+                const frame = new Uint8Array(requestHeaderBytes + payload.byteLength);
+                const header = new DataView(frame.buffer);
+                header.setInt32(0, targetIndex, true);
+                header.setInt32(4, signal, true);
+                if (jsonProtocol) {
+                    header.setUint32(8, payload.byteLength, true);
+                    frame.set(payload, requestHeaderBytes);
+                }
+                else {
+                    header.setFloat64(NUMBER_ARGUMENT_OFFSET, value, true);
+                }
+                pending.push({
+                    taskName,
+                    resolve: deferred.resolve,
+                    reject: deferred.reject,
+                });
+                void queueWrite(frame);
+            };
+            if (rawArgs instanceof Promise) {
+                void rawArgs.then(send, deferred.reject);
+            }
+            else {
+                send(rawArgs);
+            }
+            return deferred.promise;
+        };
+    };
+    let closePromise;
+    return {
+        txIdle: () => pending.length === 0,
+        call,
+        kills: () => {
+            if (closePromise !== undefined)
+                return closePromise;
+            closing = true;
+            const hadPendingCalls = pending.length > 0;
+            rejectPending(new Error("Compiled worker is shutting down"));
+            closePromise = (async () => {
+                if (hadPendingCalls) {
+                    native.kill();
+                    await native.exited;
+                    closedReason ??= "Compiled worker is shut down";
+                    abortChannel?.close();
+                    return;
+                }
+                const shutdown = new Uint8Array(requestHeaderBytes);
+                new DataView(shutdown.buffer).setInt32(0, -1, true);
+                try {
+                    await queueWrite(shutdown);
+                    await native.closeInput();
+                    let timeoutId;
+                    const exited = await Promise.race([
+                        native.exited.then(() => true),
+                        new Promise((resolve) => timeoutId = setTimeout(() => resolve(false), 1000)),
+                    ]);
+                    if (timeoutId !== undefined)
+                        clearTimeout(timeoutId);
+                    if (!exited)
+                        native.kill();
+                }
+                finally {
+                    closedReason ??= "Compiled worker is shut down";
+                    abortChannel?.close();
+                }
+            })();
+            return closePromise;
+        },
+    };
+};