knitting 0.1.46

package/src/worker/rx-queue.js

@@ -0,0 +1,124 @@
+import RingQueue from "../ipc/tools/ring-queue.js";
+import { TaskFlag, TaskIndex, } from "../memory/lock.js";
+import { composeWorkerRunner } from "./composable-runners.js";
+// Create and manage a working queue.
+export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, }) => {
+    const PLACE_HOLDER = (_) => {
+        throw ("UNREACHABLE FROM PLACE HOLDER (thread)");
+    };
+    let hasAnythingFinished = 0;
+    let awaiting = 0;
+    const jobs = listOfFunctions.reduce((acc, fixed) => (acc.push(fixed.run), acc), []);
+    const toWork = new RingQueue();
+    const pendingFrames = new RingQueue();
+    const toWorkPush = (slot) => toWork.push(slot);
+    const toWorkShift = () => toWork.shiftNoClear();
+    const pendingShift = () => pendingFrames.shiftNoClear();
+    const pendingUnshift = (slot) => pendingFrames.unshift(slot);
+    const pendingPush = (slot) => pendingFrames.push(slot);
+    const recyclePush = (slot) => lock.recyclecList.push(slot);
+    const FUNCTION_ID_MASK = 0xFFFF;
+    const IDX_FLAGS = TaskIndex.FlagsToHost;
+    const FLAG_REJECT = TaskFlag.Reject;
+    const runByIndex = listOfFunctions.reduce((acc, fixed, idx) => {
+        const job = jobs[idx];
+        acc.push(composeWorkerRunner({
+            job,
+            timeout: fixed.timeout,
+            hasAborted,
+            now,
+        }));
+        return acc;
+    }, []);
+    const hasCompleted = workerOptions?.resolveAfterFinishingAll === true
+        ? () => hasAnythingFinished !== 0 && toWork.size === 0
+        : () => hasAnythingFinished !== 0;
+    const { decode, resolved } = lock;
+    const resolvedShift = () => resolved.shiftNoClear();
+    const enqueueLock = () => {
+        if (!decode())
+            return false;
+        let task = resolvedShift();
+        while (task) {
+            task.resolve = PLACE_HOLDER;
+            task.reject = PLACE_HOLDER;
+            toWorkPush(task);
+            task = resolvedShift();
+        }
+        return true;
+    };
+    const encodeReturnSafe = (slot) => {
+        if (!returnLock.encode(slot))
+            return false;
+        return true;
+    };
+    const sendReturn = (slot, shouldReject) => {
+        slot[IDX_FLAGS] = shouldReject ? FLAG_REJECT : 0;
+        if (!encodeReturnSafe(slot))
+            return false;
+        hasAnythingFinished--;
+        recyclePush(slot);
+        return true;
+    };
+    const settleNow = (slot, isError, value, wasAwaited) => {
+        slot.value = value;
+        hasAnythingFinished++;
+        if (wasAwaited && awaiting > 0)
+            awaiting--;
+        const shouldReject = isError ||
+            slot[IDX_FLAGS] === FLAG_REJECT;
+        if (!sendReturn(slot, shouldReject))
+            pendingPush(slot);
+    };
+    const writeOne = () => {
+        const slot = pendingShift();
+        if (!slot)
+            return false;
+        if (!sendReturn(slot, slot[IDX_FLAGS] === FLAG_REJECT)) {
+            pendingUnshift(slot);
+            return false;
+        }
+        return true;
+    };
+    return {
+        hasCompleted,
+        hasPending: () => toWork.size !== 0,
+        writeBatch: (max) => {
+            let wrote = 0;
+            while (wrote < max) {
+                if (!writeOne())
+                    break;
+                wrote++;
+            }
+            return wrote;
+        },
+        serviceBatchImmediate: () => {
+            let processed = 0;
+            while (processed < 5 && toWork.size !== 0) {
+                const slot = toWorkShift();
+                try {
+                    const fnIndex = slot[TaskIndex.FunctionID] & FUNCTION_ID_MASK;
+                    const result = runByIndex[fnIndex](slot);
+                    // Slot 0 is reused for response flags; clear request FunctionID value.
+                    slot[IDX_FLAGS] = 0;
+                    slot.value = null;
+                    if (result instanceof Promise) {
+                        awaiting++;
+                        result.then((value) => settleNow(slot, false, value, true), (err) => settleNow(slot, true, err, true));
+                    }
+                    else {
+                        settleNow(slot, false, result, false);
+                    }
+                }
+                catch (err) {
+                    settleNow(slot, true, err, false);
+                }
+                ++processed;
+            }
+            return processed;
+        },
+        enqueueLock,
+        hasAwaiting: () => awaiting > 0,
+        getAwaiting: () => awaiting,
+    };
+};

package/src/worker/safety/index.d.ts

@@ -0,0 +1,4 @@
+export { installTerminationGuard, installUnhandledRejectionSilencer, } from "./process.js";
+export { installPerformanceNowGuard } from "./performance.js";
+export { scrubWorkerDataSensitiveBuffers } from "./worker-data.js";
+export { assertWorkerSharedMemoryBootData, assertWorkerImportsResolved, } from "./startup.js";

package/src/worker/safety/index.js

@@ -0,0 +1,4 @@
+export { installTerminationGuard, installUnhandledRejectionSilencer, } from "./process.js";
+export { installPerformanceNowGuard } from "./performance.js";
+export { scrubWorkerDataSensitiveBuffers } from "./worker-data.js";
+export { assertWorkerSharedMemoryBootData, assertWorkerImportsResolved, } from "./startup.js";

package/src/worker/safety/performance.d.ts

@@ -0,0 +1 @@
+export declare const installPerformanceNowGuard: () => void;

package/src/worker/safety/performance.js

@@ -0,0 +1,17 @@
+export const installPerformanceNowGuard = () => {
+    const g = globalThis;
+    if (g.__knittingPerformanceNowGuardInstalled === true)
+        return;
+    g.__knittingPerformanceNowGuardInstalled = true;
+    const perf = globalThis.performance;
+    if (!perf || typeof perf.now !== "function")
+        return;
+    // Non-intrusive guard: ensure a high-resolution clock exists.
+    // Internal timing paths capture a bound `performance.now` reference and
+    // do not require freezing global objects.
+    try {
+        void perf.now();
+    }
+    catch {
+    }
+};

package/src/worker/safety/process.d.ts

@@ -0,0 +1,2 @@
+export declare const installTerminationGuard: () => void;
+export declare const installUnhandledRejectionSilencer: () => void;

package/src/worker/safety/process.js

@@ -0,0 +1,79 @@
+import { getNodeProcess } from "../../common/node-compat.js";
+const toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+const failProcessGuardInstall = (target, reason, cause) => {
+    const suffix = cause === undefined ? "" : `: ${toErrorMessage(cause)}`;
+    throw new Error(`KNT_ERROR_PROCESS_GUARD_INSTALL: ${target} ${reason}${suffix}`);
+};
+export const installTerminationGuard = () => {
+    const proc = getNodeProcess();
+    if (!proc)
+        return;
+    if (proc.__knittingTerminationGuard === true)
+        return;
+    const blocked = (name) => {
+        throw new Error(`KNT_ERROR_PROCESS_GUARD: ${name} is disabled in worker tasks`);
+    };
+    const guardMethod = (name) => {
+        try {
+            Object.defineProperty(proc, name, {
+                configurable: false,
+                writable: false,
+                value: (..._args) => blocked(`process.${name}`),
+            });
+        }
+        catch (defineError) {
+            try {
+                proc[name] = (..._args) => blocked(`process.${name}`);
+            }
+            catch (assignError) {
+                failProcessGuardInstall(`process.${name}`, "install failed", [
+                    toErrorMessage(defineError),
+                    toErrorMessage(assignError),
+                ].join("; "));
+            }
+        }
+        if (typeof proc[name] !== "function") {
+            failProcessGuardInstall(`process.${name}`, "install verification failed");
+        }
+    };
+    guardMethod("exit");
+    guardMethod("kill");
+    guardMethod("abort");
+    guardMethod("reallyExit");
+    const globalScope = globalThis;
+    if (globalScope.Deno && typeof globalScope.Deno.exit === "function") {
+        try {
+            Object.defineProperty(globalScope.Deno, "exit", {
+                configurable: false,
+                writable: false,
+                value: (_code) => blocked("Deno.exit"),
+            });
+        }
+        catch (defineError) {
+            try {
+                globalScope.Deno.exit = (_code) => blocked("Deno.exit");
+            }
+            catch (assignError) {
+                failProcessGuardInstall("Deno.exit", "install failed", [
+                    toErrorMessage(defineError),
+                    toErrorMessage(assignError),
+                ].join("; "));
+            }
+        }
+        if (typeof globalScope.Deno.exit !== "function") {
+            failProcessGuardInstall("Deno.exit", "install verification failed");
+        }
+    }
+    proc.__knittingTerminationGuard = true;
+};
+export const installUnhandledRejectionSilencer = () => {
+    const proc = getNodeProcess();
+    if (!proc || typeof proc.on !== "function") {
+        return;
+    }
+    if (proc.__knittingUnhandledRejectionSilencer === true)
+        return;
+    proc.__knittingUnhandledRejectionSilencer = true;
+    // Worker task code may create detached promises; keep workers alive.
+    proc.on("unhandledRejection", () => { });
+};

package/src/worker/safety/startup.d.ts

@@ -0,0 +1,16 @@
+import { type SharedBufferSource } from "../../common/shared-buffer-region.js";
+import type { DebugOptions, LockBuffers } from "../../types.js";
+type SharedMemoryBootData = {
+    sab: SharedBufferSource | undefined;
+    lock: LockBuffers | undefined;
+    returnLock: LockBuffers | undefined;
+};
+type ImportedFunctionsState = {
+    debug: DebugOptions | undefined;
+    list: string[];
+    ids: number[];
+    listOfFunctions: readonly unknown[];
+};
+export declare const assertWorkerSharedMemoryBootData: ({ sab, lock, returnLock }: SharedMemoryBootData) => void;
+export declare const assertWorkerImportsResolved: ({ debug, list, ids, listOfFunctions }: ImportedFunctionsState) => void;
+export {};

package/src/worker/safety/startup.js

@@ -0,0 +1,30 @@
+import { isSharedBufferSource, } from "../../common/shared-buffer-region.js";
+import { isLockBufferTextCompat } from "../../common/shared-buffer-text.js";
+const hasLockBuffers = (value) => isSharedBufferSource(value?.headers) &&
+    isSharedBufferSource(value?.lockSector) &&
+    isSharedBufferSource(value?.payload) &&
+    isSharedBufferSource(value?.payloadSector) &&
+    (value?.textCompat === undefined ||
+        isLockBufferTextCompat(value.textCompat));
+export const assertWorkerSharedMemoryBootData = ({ sab, lock, returnLock }) => {
+    if (!isSharedBufferSource(sab)) {
+        throw new Error("worker missing transport SAB");
+    }
+    if (!hasLockBuffers(lock)) {
+        throw new Error("worker missing lock SABs");
+    }
+    if (!hasLockBuffers(returnLock)) {
+        throw new Error("worker missing return lock SABs");
+    }
+};
+export const assertWorkerImportsResolved = ({ debug, list, ids, listOfFunctions }) => {
+    if (debug?.logImportedUrl === true) {
+        console.log(list);
+    }
+    if (listOfFunctions.length > 0)
+        return;
+    console.log(list);
+    console.log(ids);
+    console.log(listOfFunctions);
+    throw new Error("No imports were found.");
+};

package/src/worker/safety/worker-data.d.ts

@@ -0,0 +1,2 @@
+import type { WorkerData } from "../../types.js";
+export declare const scrubWorkerDataSensitiveBuffers: (value: WorkerData) => void;

package/src/worker/safety/worker-data.js

@@ -0,0 +1,36 @@
+export const scrubWorkerDataSensitiveBuffers = (value) => {
+    const data = value;
+    try {
+        data.sab = undefined;
+        data.lock = undefined;
+        data.returnLock = undefined;
+        data.permission = undefined;
+    }
+    catch {
+    }
+    try {
+        delete data.sab;
+    }
+    catch {
+    }
+    try {
+        delete data.lock;
+    }
+    catch {
+    }
+    try {
+        delete data.returnLock;
+    }
+    catch {
+    }
+    try {
+        delete data.permission;
+    }
+    catch {
+    }
+    try {
+        Object.freeze(data);
+    }
+    catch {
+    }
+};

package/src/worker/task-loader.d.ts

@@ -0,0 +1,26 @@
+import type { ComposedWithKey } from "../types.js";
+import type { ResolvedPermissionProtocol } from "../permission/protocol.js";
+type GetFunctionParams = {
+    list: string[];
+    ids: number[];
+    at: number[];
+    isWorker: boolean;
+    permission?: ResolvedPermissionProtocol;
+};
+type WorkerCallable = (args: unknown, abortToolkit?: unknown) => unknown;
+export declare const enum TimeoutKind {
+    Reject = 0,
+    Resolve = 1
+}
+export type TimeoutSpec = {
+    ms: number;
+    kind: TimeoutKind;
+    value: unknown;
+};
+export type WorkerComposedWithKey = ComposedWithKey & {
+    run: WorkerCallable;
+    timeout?: TimeoutSpec;
+};
+export declare const getFunctions: ({ list, ids, at, permission }: GetFunctionParams) => Promise<WorkerComposedWithKey[]>;
+export type GetFunctions = ReturnType<typeof getFunctions>;
+export {};

package/src/worker/task-loader.js

@@ -0,0 +1,66 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { endpointSymbol } from "../common/task-symbol.js";
+import { toModuleUrl } from "../common/module-url.js";
+const normalizeTimeout = (timeout) => {
+    if (timeout == null)
+        return undefined;
+    if (typeof timeout === "number") {
+        const ms = Math.floor(timeout);
+        return ms >= 0
+            ? { ms, kind: 0 /* TimeoutKind.Reject */, value: new Error("Task timeout") }
+            : undefined;
+    }
+    const ms = Math.floor(timeout.time);
+    if (!(ms >= 0))
+        return undefined;
+    if ("default" in timeout) {
+        return { ms, kind: 1 /* TimeoutKind.Resolve */, value: timeout.default };
+    }
+    if (timeout.maybe === true) {
+        return { ms, kind: 1 /* TimeoutKind.Resolve */, value: undefined };
+    }
+    if ("error" in timeout) {
+        return { ms, kind: 0 /* TimeoutKind.Reject */, value: timeout.error };
+    }
+    return { ms, kind: 0 /* TimeoutKind.Reject */, value: new Error("Task timeout") };
+};
+const composeWorkerCallable = (fixed, _permission) => {
+    return fixed.f;
+};
+export const getFunctions = async ({ list, ids, at, permission }) => {
+    const modules = list.map((specifier) => toModuleUrl(specifier));
+    const results = await Promise.all(modules.map(async (imports) => {
+        const module = (await import(__rewriteRelativeImportExtension(imports)));
+        return Object.entries(module)
+            .filter(([_, value]) => value != null && typeof value === "object" &&
+            //@ts-ignore Reason -> trust me
+            value?.[endpointSymbol] === true)
+            .map(([name, value]) => ({
+            //@ts-ignore Reason -> trust me
+            ...value,
+            name,
+        }));
+    }));
+    // Flatten the results, filter by IDs, and sort
+    const flattened = results.flat();
+    const useAtFilter = modules.length === 1 && at.length > 0;
+    const atSet = useAtFilter ? new Set(at) : null;
+    const targetModule = useAtFilter ? modules[0] : null;
+    const flattenedResults = flattened
+        .filter((obj) => useAtFilter
+        ? obj.importedFrom === targetModule && atSet.has(obj.at)
+        : ids.includes(obj.id))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return flattenedResults.map((fixed) => ({
+        ...fixed,
+        run: composeWorkerCallable(fixed, permission),
+        timeout: normalizeTimeout(fixed.timeout),
+    }));
+};

package/src/worker/timers.d.ts

@@ -0,0 +1,18 @@
+type PauseOptions = {
+    pauseInNanoseconds?: number;
+};
+export type NativeWaitU32 = (buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, expected: number, timeoutMs?: number) => unknown;
+export declare const whilePausing: ({ pauseInNanoseconds }: PauseOptions) => () => void;
+export declare const pauseGeneric: () => void;
+export declare const sleepUntilChanged: ({ at, opView, pauseInNanoseconds, rxStatus, txStatus, enqueueLock, write, nativeWaitU32, useSharedMemoryWait, }: {
+    opView: Int32Array;
+    rxStatus: Int32Array;
+    txStatus: Int32Array;
+    pauseInNanoseconds?: number;
+    at: number;
+    enqueueLock: () => boolean;
+    write?: () => number | boolean;
+    nativeWaitU32?: NativeWaitU32;
+    useSharedMemoryWait?: boolean;
+}) => (value: number, spinMicroseconds: number, parkMs?: number) => void;
+export {};

package/src/worker/timers.js

@@ -0,0 +1,97 @@
+var Comment;
+(function (Comment) {
+    Comment[Comment["thisIsAHint"] = 0] = "thisIsAHint";
+})(Comment || (Comment = {}));
+const maybeGc = (() => {
+    const host = globalThis;
+    const gc = typeof host.gc === "function"
+        ? (() => host.gc())
+        : undefined;
+    if (gc) {
+        try {
+            delete host.gc;
+        }
+        catch {
+            host.gc = undefined;
+        }
+        if (host.global) {
+            try {
+                delete host.global.gc;
+            }
+            catch {
+                host.global.gc = undefined;
+            }
+        }
+    }
+    return gc ?? (() => { });
+})();
+const DEFAULT_PAUSE_TIME = 250;
+const a_load = Atomics.load;
+const a_store = Atomics.store;
+const a_wait = typeof Atomics.wait === "function" ? Atomics.wait : undefined;
+const p_now = performance.now.bind(performance);
+const waitFallbackView = a_wait === undefined
+    ? undefined
+    : new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+const a_pause = "pause" in Atomics
+    ? Atomics.pause
+    : undefined;
+export const whilePausing = ({ pauseInNanoseconds }) => {
+    const forNanoseconds = pauseInNanoseconds ?? DEFAULT_PAUSE_TIME;
+    if (!a_pause || forNanoseconds <= 0)
+        return () => { };
+    return () => a_pause(forNanoseconds);
+};
+export const pauseGeneric = whilePausing({});
+export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, txStatus, enqueueLock, write, nativeWaitU32, useSharedMemoryWait = true, }) => {
+    const pause = pauseInNanoseconds
+        !== undefined
+        ? whilePausing({ pauseInNanoseconds })
+        : pauseGeneric;
+    const tryProgress = () => {
+        let progressed = false;
+        if (enqueueLock())
+            progressed = true;
+        if (write) {
+            const wrote = write();
+            if (typeof wrote === "number") {
+                if (wrote > 0)
+                    progressed = true;
+            }
+            else if (wrote === true) {
+                progressed = true;
+            }
+        }
+        return progressed;
+    };
+    return (value, spinMicroseconds, parkMs) => {
+        const until = p_now() + (spinMicroseconds / 1000);
+        maybeGc();
+        let spinChecks = 0;
+        while (true) {
+            if (a_load(opView, at) !== value ||
+                txStatus[Comment.thisIsAHint] === 1)
+                return;
+            if (tryProgress())
+                return;
+            pause();
+            if ((spinChecks++ & 63) === 0 && p_now() >= until)
+                break;
+        }
+        if (tryProgress())
+            return;
+        a_store(rxStatus, 0, 0);
+        if (nativeWaitU32 !== undefined) {
+            nativeWaitU32(opView.buffer, opView.byteOffset + (at * Int32Array.BYTES_PER_ELEMENT), value >>> 0, parkMs ?? 60);
+        }
+        else if (useSharedMemoryWait &&
+            a_wait &&
+            opView.buffer instanceof SharedArrayBuffer) {
+            a_wait(opView, at, value, parkMs ?? 60);
+        }
+        else if (a_wait && waitFallbackView) {
+            a_wait(waitFallbackView, 0, 0, parkMs ?? 1);
+        }
+        a_store(rxStatus, 0, 1);
+    };
+};