knitting 0.1.55 → 0.1.60

package/src/runtime/balancer.js

@@ -0,0 +1,149 @@
+const selectStrategy = (contexts, handlers, strategy) => {
+    switch (strategy ?? "roundRobin") {
+        case "roundRobin":
+        case "robinRound": // legacy alias
+            return roundRobin(contexts)(handlers)(handlers.length);
+        case "firstIdle":
+            return firstIdle(contexts)(handlers)(handlers.length);
+        case "randomLane":
+            return randomLane(contexts)(handlers)(handlers.length);
+        case "firstIdleOrRandom":
+            return firstIdleRandom(contexts)(handlers)(handlers.length);
+    }
+    // Unreachable code, but guarded for safety.
+    throw new Error(`Unknown balancer: ${strategy}`);
+};
+export const managerMethod = ({ contexts, balancer, handlers, inlinerGate, }) => {
+    const strategy = typeof balancer === "object" && balancer != null
+        ? balancer.strategy
+        : balancer;
+    if (contexts.length < 2) {
+        throw new Error(contexts.length === 0
+            ? "No threads available."
+            : "Cannot rotate with a single thread.");
+    }
+    if (handlers.length === 0) {
+        throw new Error("No handlers provided.");
+    }
+    const allInvoker = selectStrategy(contexts, handlers, strategy);
+    if (!inlinerGate) {
+        return allInvoker;
+    }
+    const inlinerIndex = inlinerGate.index | 0;
+    const threshold = Number.isFinite(inlinerGate.threshold)
+        ? Math.max(1, Math.floor(inlinerGate.threshold))
+        : 1;
+    if (threshold <= 1 || inlinerIndex < 0 || inlinerIndex >= handlers.length) {
+        return allInvoker;
+    }
+    const workerLaneCount = handlers.length - 1;
+    if (workerLaneCount <= 0) {
+        return allInvoker;
+    }
+    const workerHandlers = new Array(workerLaneCount);
+    const workerContexts = new Array(workerLaneCount);
+    for (let source = 0, lane = 0; source < handlers.length; source += 1) {
+        if (source === inlinerIndex)
+            continue;
+        workerHandlers[lane] = handlers[source];
+        workerContexts[lane] = contexts[source];
+        lane += 1;
+    }
+    const workerOnlyInvoker = selectStrategy(workerContexts, workerHandlers, strategy);
+    let inFlight = 0;
+    const releaseResolved = (value) => {
+        inFlight -= 1;
+        return value;
+    };
+    const releaseRejected = (error) => {
+        inFlight -= 1;
+        throw error;
+    };
+    return (args) => {
+        inFlight += 1;
+        const invoker = inFlight >= threshold ? allInvoker : workerOnlyInvoker;
+        try {
+            return invoker(args).then(releaseResolved, releaseRejected);
+        }
+        catch (error) {
+            inFlight -= 1;
+            throw error;
+        }
+    };
+};
+export function roundRobin(_contexts) {
+    return (handlers) => {
+        return (max) => {
+            const top = Math.min(max, handlers.length);
+            if (top <= 1) {
+                return (args) => handlers[0](args);
+            }
+            let rrCursor = 0;
+            return (args) => {
+                const lane = rrCursor;
+                rrCursor += 1;
+                if (rrCursor === top)
+                    rrCursor = 0;
+                return handlers[lane](args);
+            };
+        };
+    };
+}
+export function firstIdle(contexts) {
+    const isSolved = contexts.map((ctx) => ctx.txIdle);
+    return (handlers) => {
+        return (max) => {
+            const laneCount = Math.min(max, handlers.length);
+            if (laneCount <= 1) {
+                return (args) => handlers[0](args);
+            }
+            let rrCursor = 0;
+            return (args) => {
+                for (let lane = 0; lane < laneCount; lane += 1) {
+                    if (isSolved[lane]()) {
+                        return handlers[lane](args);
+                    }
+                }
+                const fallback = rrCursor;
+                rrCursor += 1;
+                if (rrCursor === laneCount)
+                    rrCursor = 0;
+                return handlers[fallback](args);
+            };
+        };
+    };
+}
+export const randomLane = (_) => {
+    return (handlers) => {
+        return (max) => {
+            const laneCount = Math.min(max, handlers.length);
+            if (laneCount <= 1) {
+                return (args) => handlers[0](args);
+            }
+            return (args) => {
+                const lane = (Math.random() * laneCount) | 0;
+                return handlers[lane](args);
+            };
+        };
+    };
+};
+export function firstIdleRandom(contexts) {
+    const isSolved = contexts.map((ctx) => ctx.txIdle);
+    return (handlers) => {
+        return (max) => {
+            const laneCount = Math.min(max, handlers.length);
+            if (laneCount <= 1) {
+                return (args) => handlers[0](args);
+            }
+            return (args) => {
+                for (let lane = 0; lane < laneCount; lane += 1) {
+                    if (isSolved[lane]()) {
+                        return handlers[lane](args);
+                    }
+                }
+                const fallback = (Math.random() * laneCount) | 0;
+                return handlers[fallback](args);
+            };
+        };
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { CompiledWorkerCheck, CompiledWorkerOptions } from "../types.js";
+export declare const COMPILED_WORKER_FORMAT = "knitting-compiled-worker";
+export declare const COMPILED_WORKER_FORMAT_VERSION = 1;
+export declare const COMPILED_WORKER_PROTOCOL = "knitting-number-v1";
+export declare const COMPILED_WORKER_JSON_PROTOCOL = "knitting-json-v1";
+export declare const COMPILED_WORKER_EXTENSION = ".knt";
+export type CompiledWorkerTask = {
+    index: number;
+    exportName: string;
+};
+export type ArtifactInspection = CompiledWorkerCheck & {
+    artifactHref: string;
+    manifestHref: string;
+    taskEntries?: CompiledWorkerTask[];
+};
+export declare const defaultCompiledWorkerArtifact: (source: string | URL) => string;
+export declare const inspectCompiledWorkerArtifact: ({ source, options, requiredTasks, }: {
+    source: string | URL;
+    options?: CompiledWorkerOptions;
+    requiredTasks?: readonly string[];
+}) => ArtifactInspection;

package/src/runtime/compiled-artifact.js

@@ -0,0 +1,260 @@
+import { getNodeBuiltinModule, getNodeProcess } from "../common/node-compat.js";
+import { toModuleUrl } from "../common/module-url.js";
+export const COMPILED_WORKER_FORMAT = "knitting-compiled-worker";
+export const COMPILED_WORKER_FORMAT_VERSION = 1;
+export const COMPILED_WORKER_PROTOCOL = "knitting-number-v1";
+export const COMPILED_WORKER_JSON_PROTOCOL = "knitting-json-v1";
+export const COMPILED_WORKER_EXTENSION = ".knt";
+const deno = globalThis.Deno;
+const normalizeArch = (arch) => {
+    if (arch === "x86_64")
+        return "x64";
+    if (arch === "aarch64")
+        return "arm64";
+    return arch ?? "unknown";
+};
+const runtimeTarget = () => {
+    const process = getNodeProcess();
+    if (process !== undefined) {
+        return {
+            platform: process.platform ?? "unknown",
+            arch: normalizeArch(process.arch),
+        };
+    }
+    return {
+        platform: deno?.build?.os ?? "unknown",
+        arch: normalizeArch(deno?.build?.arch),
+    };
+};
+const normalizeSourceHref = (source) => source instanceof URL ? source.href : toModuleUrl(source);
+const resolveHref = (value, base) => {
+    try {
+        return new URL(value).href;
+    }
+    catch {
+        return new URL(value, base).href;
+    }
+};
+export const defaultCompiledWorkerArtifact = (source) => {
+    const url = new URL(normalizeSourceHref(source));
+    url.search = "";
+    url.hash = "";
+    url.pathname = url.pathname.replace(/\.[^./]+$/, "") +
+        COMPILED_WORKER_EXTENSION;
+    return url.href;
+};
+const artifactHrefs = (source, options = {}) => {
+    const sourceHref = normalizeSourceHref(source);
+    const artifactHref = options.artifact === undefined
+        ? defaultCompiledWorkerArtifact(sourceHref)
+        : resolveHref(options.artifact, sourceHref);
+    const manifestHref = options.manifest === undefined
+        ? artifactHref + ".json"
+        : resolveHref(options.manifest, artifactHref);
+    return { artifactHref, manifestHref };
+};
+const filePath = (href) => {
+    const converter = getNodeBuiltinModule("node:url")?.fileURLToPath;
+    if (converter !== undefined)
+        return converter(href);
+    const url = new URL(href);
+    if (url.protocol !== "file:") {
+        throw new Error("Compiled worker artifact must use file:, got " + url.protocol);
+    }
+    return decodeURIComponent(url.pathname);
+};
+const readTextFile = (path) => {
+    const fs = getNodeBuiltinModule("node:fs");
+    if (fs !== undefined)
+        return fs.readFileSync(path, "utf8");
+    if (deno?.readTextFileSync !== undefined)
+        return deno.readTextFileSync(path);
+    throw new Error("Synchronous filesystem access is unavailable");
+};
+const inspectExecutable = (path) => {
+    try {
+        const fs = getNodeBuiltinModule("node:fs");
+        if (fs !== undefined) {
+            const stat = fs.statSync(path);
+            if (!stat.isFile())
+                return "artifact is not a file";
+            if (runtimeTarget().platform !== "win32" && (stat.mode & 0o111) === 0) {
+                return "artifact is not executable";
+            }
+            return undefined;
+        }
+        if (deno?.statSync !== undefined) {
+            const stat = deno.statSync(path);
+            if (!stat.isFile)
+                return "artifact is not a file";
+            if (stat.mode !== null && (stat.mode & 0o111) === 0) {
+                return "artifact is not executable";
+            }
+            return undefined;
+        }
+        return "filesystem metadata is unavailable";
+    }
+    catch (error) {
+        const message = String(error?.message ?? error);
+        return "artifact is unavailable: " + message;
+    }
+};
+const compilerLabel = (compiler) => {
+    if (typeof compiler === "string" && compiler.length > 0)
+        return compiler;
+    if (compiler !== null && typeof compiler === "object" &&
+        typeof compiler.name === "string" &&
+        compiler.name.length > 0 &&
+        typeof compiler.version === "string") {
+        const value = compiler;
+        return (value.name + " " + value.version).trim();
+    }
+    return undefined;
+};
+export const inspectCompiledWorkerArtifact = ({ source, options, requiredTasks, }) => {
+    const sourceHref = normalizeSourceHref(source);
+    const { artifactHref, manifestHref } = artifactHrefs(sourceHref, options);
+    let artifact;
+    let manifest;
+    try {
+        artifact = filePath(artifactHref);
+        manifest = filePath(manifestHref);
+    }
+    catch (error) {
+        const message = String(error?.message ?? error);
+        return {
+            compiled: false,
+            artifact: artifactHref,
+            manifest: manifestHref,
+            artifactHref,
+            manifestHref,
+            reason: message,
+        };
+    }
+    const base = {
+        compiled: false,
+        artifact,
+        manifest,
+        artifactHref,
+        manifestHref,
+    };
+    const executableProblem = inspectExecutable(artifact);
+    if (executableProblem !== undefined) {
+        return { ...base, reason: executableProblem };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readTextFile(manifest));
+    }
+    catch (error) {
+        const message = String(error?.message ?? error);
+        return {
+            ...base,
+            reason: "manifest is unavailable or invalid: " + message,
+        };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ...base, reason: "manifest root must be an object" };
+    }
+    const workerManifest = parsed;
+    const compiler = compilerLabel(workerManifest.compiler);
+    const details = {
+        compiler,
+        protocol: typeof workerManifest.protocol === "string"
+            ? workerManifest.protocol
+            : undefined,
+    };
+    if (workerManifest.format !== COMPILED_WORKER_FORMAT ||
+        workerManifest.version !== COMPILED_WORKER_FORMAT_VERSION) {
+        return { ...base, ...details, reason: "unsupported manifest format" };
+    }
+    if (workerManifest.protocol !== COMPILED_WORKER_PROTOCOL &&
+        workerManifest.protocol !== COMPILED_WORKER_JSON_PROTOCOL) {
+        return { ...base, ...details, reason: "unsupported worker protocol" };
+    }
+    if (compiler === undefined) {
+        return { ...base, ...details, reason: "manifest compiler is invalid" };
+    }
+    const target = runtimeTarget();
+    if (workerManifest.target?.platform !== target.platform ||
+        normalizeArch(workerManifest.target?.arch) !== target.arch) {
+        return {
+            ...base,
+            ...details,
+            reason: "artifact target " +
+                (workerManifest.target?.platform ?? "unknown") + "/" +
+                (workerManifest.target?.arch ?? "unknown") + " does not match " +
+                target.platform + "/" + target.arch,
+        };
+    }
+    if (!Array.isArray(workerManifest.tasks) || workerManifest.tasks.length === 0) {
+        return { ...base, ...details, reason: "manifest has no tasks" };
+    }
+    const indices = new Set();
+    const taskNames = new Set();
+    for (const task of workerManifest.tasks) {
+        if (!Number.isSafeInteger(task?.index) || task.index < 0 ||
+            task.index > 0x7fff_ffff ||
+            typeof task.exportName !== "string" || task.exportName.length === 0 ||
+            indices.has(task.index) || taskNames.has(task.exportName)) {
+            return { ...base, ...details, reason: "manifest task table is invalid" };
+        }
+        indices.add(task.index);
+        taskNames.add(task.exportName);
+    }
+    if (typeof workerManifest.source !== "string" ||
+        workerManifest.source.length === 0) {
+        return { ...base, ...details, reason: "manifest source is invalid" };
+    }
+    let manifestSource;
+    try {
+        manifestSource = resolveHref(workerManifest.source.replace(/\\/g, "/"), artifactHref);
+    }
+    catch {
+        return { ...base, ...details, reason: "manifest source is invalid" };
+    }
+    if (manifestSource !== sourceHref) {
+        return {
+            ...base,
+            ...details,
+            tasks: [...taskNames],
+            reason: "manifest was built for a different task module",
+        };
+    }
+    if (Number.isFinite(workerManifest.sourceMtimeMs)) {
+        try {
+            const sourcePath = filePath(sourceHref);
+            const fs = getNodeBuiltinModule("node:fs");
+            const currentMtime = fs?.statSync(sourcePath).mtimeMs ??
+                deno?.statSync?.(sourcePath).mtime?.getTime();
+            if (currentMtime !== undefined &&
+                currentMtime > workerManifest.sourceMtimeMs + 0.5) {
+                return {
+                    ...base,
+                    ...details,
+                    tasks: [...taskNames],
+                    reason: "task module changed after the artifact was built",
+                };
+            }
+        }
+        catch {
+            return { ...base, ...details, reason: "task module is unavailable" };
+        }
+    }
+    const missing = requiredTasks?.filter((name) => !taskNames.has(name)) ?? [];
+    if (missing.length > 0) {
+        return {
+            ...base,
+            ...details,
+            tasks: [...taskNames],
+            reason: "compiled artifact is missing tasks: " + missing.join(", "),
+        };
+    }
+    return {
+        ...base,
+        ...details,
+        compiled: true,
+        tasks: [...taskNames],
+        taskEntries: workerManifest.tasks,
+    };
+};

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

@@ -0,0 +1,8 @@
+import type { CompiledWorkerOptions } from "../types.js";
+import type { ArtifactInspection } from "./compiled-artifact.js";
+export declare const buildCompiledWorkerArtifact: ({ inspection, source, tasks, options, }: {
+    inspection: ArtifactInspection;
+    source: string;
+    tasks: readonly string[];
+    options?: CompiledWorkerOptions;
+}) => void;

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 {};