@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/core/data.ts

@@ -0,0 +1,273 @@
+import { dataBytesMax, dataDepthMax, dataNodesMax } from "./limits.js";
+
+interface DataFrame {
+    readonly value: unknown;
+    readonly depth: number;
+    readonly leaving?: boolean;
+}
+
+interface DataOptions {
+    readonly allowArrays: boolean;
+    readonly allowUndefined: boolean;
+}
+
+const frozenData = new WeakSet();
+
+export function isFrozenData(value: unknown): boolean {
+    return value !== null && typeof value === "object" && frozenData.has(value);
+}
+
+/** Validate before native cloning/serialization, which can otherwise overflow on deep input. */
+export function assertDataTree(
+    value: unknown,
+    options = { allowArrays: true, allowUndefined: true },
+): void {
+    if (options.allowArrays && options.allowUndefined && isFrozenData(value)) {
+        return;
+    }
+
+    new DataValidator(options).validate(value);
+}
+
+/** JSON.parse owns every property, so this boundary does not need accessor/prototype inspection. */
+export function parseFrozenJson(text: string): unknown {
+    const value: unknown = JSON.parse(text);
+    const targets: object[] = [];
+    new DataValidator({ allowArrays: true, allowUndefined: false }, true).validate(value, targets);
+
+    for (const target of targets) {
+        Object.freeze(target);
+        frozenData.add(target);
+    }
+
+    return value;
+}
+
+class DataValidator {
+    private readonly pending: DataFrame[] = [];
+    private readonly ancestors = new Set<object>();
+    private nodes = 0;
+    private bytes = 0;
+
+    constructor(
+        private readonly options: DataOptions,
+        private readonly parsedJson = false,
+    ) {}
+
+    validate(value: unknown, freezeTargets?: object[]): void {
+        this.pending.push({ value, depth: 0 });
+
+        while (this.pending.length > 0) {
+            const frame = this.pending.pop();
+
+            if (!frame) {
+                throw new Error("A data frame must exist while traversal is pending.");
+            }
+
+            if (frame.leaving && frame.value !== null && typeof frame.value === "object") {
+                this.ancestors.delete(frame.value);
+
+                freezeTargets?.push(frame.value);
+
+                continue;
+            }
+
+            this.nodes += 1;
+
+            if (this.nodes > dataNodesMax || frame.depth > dataDepthMax) {
+                throw new TypeError("Data exceeds the supported node or nesting limit.");
+            }
+
+            if (frame.value === undefined && !this.options.allowUndefined) {
+                throw new TypeError("Data cannot contain undefined values.");
+            }
+
+            this.addBytes(scalarBytes(frame.value));
+
+            if (frame.value !== null && typeof frame.value === "object") {
+                if (this.parsedJson) {
+                    this.enterParsedObject(frame.value, frame.depth);
+                } else {
+                    this.enterObject(frame.value, frame.depth, freezeTargets !== undefined);
+                }
+            }
+        }
+    }
+
+    private enterParsedObject(value: object, depth: number): void {
+        this.pending.push({ value, depth, leaving: true });
+
+        for (const [name, child] of Object.entries(value)) {
+            this.addBytes(name.length * 3);
+
+            if (this.pending.length >= dataNodesMax) {
+                throw new TypeError("Data exceeds the supported node limit.");
+            }
+
+            this.pending.push({ value: child, depth: depth + 1 });
+        }
+    }
+
+    private enterObject(value: object, depth: number, freezing: boolean): void {
+        if (Array.isArray(value) && !this.options.allowArrays) {
+            throw new TypeError("Data cannot contain arrays.");
+        }
+
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError("Data cannot contain symbol properties.");
+        }
+
+        if (this.ancestors.has(value)) {
+            throw new TypeError("Data cannot contain circular references.");
+        }
+
+        const prototype: unknown = Object.getPrototypeOf(value);
+
+        if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Data must contain plain objects and arrays.");
+        }
+
+        this.ancestors.add(value);
+        this.pending.push({ value, depth, leaving: true });
+        const entries = Object.entries(Object.getOwnPropertyDescriptors(value));
+        let arrayIndexCount = 0;
+
+        for (const [name, descriptor] of entries) {
+            if (freezing && (descriptor.get || descriptor.set)) {
+                throw new TypeError("Data cannot contain accessors.");
+            }
+
+            if (!descriptor.enumerable) {
+                continue;
+            }
+
+            if (descriptor.get || descriptor.set) {
+                throw new TypeError("Data cannot contain accessors.");
+            }
+
+            if (Array.isArray(value)) {
+                if (!/^(0|[1-9][0-9]*)$/.test(name) || Number(name) >= value.length) {
+                    throw new TypeError("Data arrays must contain only indexed values.");
+                }
+
+                arrayIndexCount += 1;
+            }
+
+            this.addBytes(name.length * 3);
+
+            if (this.pending.length >= dataNodesMax) {
+                throw new TypeError("Data exceeds the supported node limit.");
+            }
+
+            const child: unknown = descriptor.value;
+            this.pending.push({ value: child, depth: depth + 1 });
+        }
+
+        if (Array.isArray(value) && arrayIndexCount !== value.length) {
+            throw new TypeError("Data arrays must be dense.");
+        }
+    }
+
+    private addBytes(bytes: number): void {
+        this.bytes += bytes;
+
+        if (this.bytes > dataBytesMax) {
+            throw new TypeError("Data exceeds the supported byte limit.");
+        }
+    }
+}
+
+function scalarBytes(value: unknown): number {
+    if (value === null || value === undefined || typeof value === "boolean") {
+        return 5;
+    }
+
+    if (typeof value === "string") {
+        return value.length * 3 + 2;
+    }
+
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return 24;
+    }
+
+    if (typeof value === "object") {
+        return 2;
+    }
+
+    throw new TypeError("Data contains a non-serializable value.");
+}
+
+export function cloneData<Value>(value: Value): Value {
+    if (!isFrozenData(value)) {
+        assertDataTree(value);
+    }
+
+    return structuredClone(value);
+}
+
+/** Validate at the boundary, then freeze the detached native copy without revalidating it. */
+export function cloneFrozenData<Value>(value: Value): Value {
+    const copied = cloneData(value);
+    const pending: unknown[] = [copied];
+    const visited = new Set<object>();
+
+    while (pending.length > 0) {
+        const current = pending.pop();
+
+        if (current === null || typeof current !== "object" || visited.has(current)) {
+            continue;
+        }
+
+        visited.add(current);
+
+        if (visited.size > dataNodesMax) {
+            throw new Error("A validated clone cannot exceed its source node budget.");
+        }
+
+        for (const child of Object.values(current)) {
+            pending.push(child);
+        }
+
+        Object.freeze(current);
+        frozenData.add(current);
+    }
+
+    return copied;
+}
+
+/** Freeze only data properties; never evaluate a user getter while recording diagnostics. */
+export function freezeData<Value>(value: Value): Value {
+    if (isFrozenData(value)) {
+        return value;
+    }
+
+    const targets: object[] = [];
+    new DataValidator({ allowArrays: true, allowUndefined: true }).validate(value, targets);
+
+    for (const target of targets) {
+        Object.freeze(target);
+        frozenData.add(target);
+    }
+
+    return value;
+}
+
+export function setOwn<Value>(record: Record<string, Value>, name: string, value: Value): void {
+    Object.defineProperty(record, name, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+
+export function getOwn<Value>(
+    record: Readonly<Record<string, Value>>,
+    name: string,
+): Value | undefined {
+    if (!Object.hasOwn(record, name)) {
+        return undefined;
+    }
+
+    return record[name];
+}

package/src/core/deadline.ts

@@ -0,0 +1,47 @@
+/** A deadline settles framework work; late extension callbacks still need their context checked. */
+export class Deadline implements Disposable {
+    private readonly controller = new AbortController();
+    private readonly timer: ReturnType<typeof setTimeout>;
+    private readonly expired: Promise<never>;
+
+    constructor(timeoutMs: number, error: () => Error) {
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647) {
+            throw new TypeError("A deadline requires a positive integer timeout in milliseconds.");
+        }
+
+        this.expired = new Promise<never>((_resolve, reject) => {
+            this.controller.signal.addEventListener(
+                "abort",
+                () => {
+                    const reason: unknown = this.controller.signal.reason;
+                    reject(reason);
+                },
+                {
+                    once: true,
+                },
+            );
+        });
+        this.timer = setTimeout(() => this.cancel(error()), timeoutMs);
+        // A synchronous owner can dispose without ever waiting on the deadline.
+        void this.expired.catch(() => {
+            // Disposal can precede the first waiter; wait() still observes this rejection.
+        });
+    }
+
+    get signal(): AbortSignal {
+        return this.controller.signal;
+    }
+
+    wait<Value>(work: PromiseLike<Value>): Promise<Value> {
+        return Promise.race([work, this.expired]);
+    }
+
+    cancel(reason: unknown): void {
+        this.controller.abort(reason);
+    }
+
+    [Symbol.dispose](): void {
+        clearTimeout(this.timer);
+        this.cancel(new Error("The deadline owner has finished."));
+    }
+}

package/src/core/errors.ts

@@ -0,0 +1,32 @@
+export type RuntimeErrorCode =
+    | "InvalidModule"
+    | "DuplicateModule"
+    | "MissingModule"
+    | "ModuleCycle"
+    | "DuplicateOperation"
+    | "InvalidOperation"
+    | "InvalidTransactionBoundary"
+    | "UnknownOperation"
+    | "AsyncOperationInSyncExecution"
+    | "UnfinishedExecution"
+    | "ExpiredExecutionContext"
+    | "WorldBusy"
+    | "RuntimeClosed";
+
+export class RuntimeError extends Error {
+    readonly code: RuntimeErrorCode;
+
+    constructor(code: RuntimeErrorCode, message: string) {
+        super(message);
+        this.name = "RuntimeError";
+        this.code = code;
+    }
+}
+
+export function errorMessage(error: unknown): string {
+    if (error instanceof Error) {
+        return error.message;
+    }
+
+    return String(error);
+}

package/src/core/files.ts

@@ -0,0 +1,45 @@
+import { Deadline } from "./deadline.js";
+import { dataBytesMax } from "./limits.js";
+
+export class TextEncodingError extends TypeError {
+    override readonly name = "TextEncodingError";
+}
+
+/** Read a bounded slice even if the file grows between discovery and the actual read. */
+export async function readTextFile(path: string, bytesMax = dataBytesMax): Promise<string> {
+    const bytes = await readBinaryFile(path, bytesMax);
+
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch (error) {
+        throw new TextEncodingError(`File '${path}' is not valid UTF-8.`, { cause: error });
+    }
+}
+
+export async function readBinaryFile(path: string, bytesMax = dataBytesMax): Promise<Uint8Array> {
+    if (!Number.isSafeInteger(bytesMax) || bytesMax < 1) {
+        throw new TypeError("A file byte limit must be a positive safe integer.");
+    }
+
+    using deadline = new Deadline(30_000, () => new Error(`Reading '${path}' timed out.`));
+    const file = Bun.file(path);
+    const status = await deadline.wait(file.stat());
+
+    if (!status.isFile()) {
+        throw new TypeError(`Input '${path}' must be a regular file.`);
+    }
+
+    const bytes = await deadline.wait(file.slice(0, bytesMax + 1).bytes());
+
+    if (bytes.length > bytesMax) {
+        throw new TypeError(`File '${path}' exceeds the ${bytesMax}-byte input limit.`);
+    }
+
+    return bytes;
+}
+
+export async function readJsonFile(path: string): Promise<unknown> {
+    const text = await readTextFile(path);
+
+    return JSON.parse(text.replace(/^\uFEFF/u, ""));
+}

package/src/core/index.ts

@@ -0,0 +1,17 @@
+export { RuntimeError } from "./errors.js";
+export type { RuntimeErrorCode } from "./errors.js";
+export { defineOperation } from "./operation.js";
+export type { Operation } from "./operation.js";
+export { createRuntime, Runtime } from "./runtime.js";
+export type {
+    AsyncHandler,
+    ExecutionContext,
+    HarnessModule,
+    ModuleRegistrar,
+    RuntimeOptions,
+    RuntimeObserver,
+    RuntimeExecution,
+    SyncHandler,
+    TraceEvent,
+    TransactionBoundary,
+} from "./types.js";

package/src/core/limits.ts

@@ -0,0 +1,14 @@
+/** Internal work budgets keep malformed input and accidental cycles from exhausting the host. */
+export const dataDepthMax = 256;
+export const dataNodesMax = 1_000_000;
+export const dataBytesMax = 64 * 1024 * 1024;
+export const setupFilesMax = 20_000;
+export const setupBytesMax = 512 * 1024 * 1024;
+export const importFramesMax = 4096;
+export const workUnitsMax = 50_000_000;
+export const requestDepthMax = 128;
+export const requestOperationsMax = 20_000;
+export const queuedRequestsMax = 1000;
+export const requestTimeoutMs = 300_000;
+export const traceEventsMax = 100_000;
+export const traceBytesMax = 64 * 1024 * 1024;

package/src/core/modules.ts

@@ -0,0 +1,102 @@
+import { RuntimeError } from "./errors.js";
+import { setupFilesMax } from "./limits.js";
+import type { HarnessModule } from "./types.js";
+
+export function orderModules(modules: readonly HarnessModule[]): readonly HarnessModule[] {
+    if (modules.length > setupFilesMax) {
+        throw new RuntimeError("InvalidModule", "Too many modules were supplied.");
+    }
+
+    const byId = new Map<string, HarnessModule>();
+
+    for (const module of modules) {
+        if (module.id.trim().length === 0) {
+            throw new RuntimeError("InvalidModule", "A module needs a non-empty ID.");
+        }
+
+        if (byId.has(module.id)) {
+            throw new RuntimeError(
+                "DuplicateModule",
+                `Module "${module.id}" was supplied more than once.`,
+            );
+        }
+
+        byId.set(
+            module.id,
+            Object.freeze({
+                id: module.id,
+                ...(module.requires === undefined
+                    ? {}
+                    : { requires: Object.freeze([...module.requires]) }),
+                setup: module.setup.bind(module),
+                ...(module.reset === undefined ? {} : { reset: module.reset.bind(module) }),
+                ...(module.dispose === undefined ? {} : { dispose: module.dispose.bind(module) }),
+            }),
+        );
+    }
+
+    return visitModules(byId);
+}
+
+interface ModuleFrame {
+    readonly module: HarnessModule;
+    next: number;
+}
+
+function visitModules(byId: ReadonlyMap<string, HarnessModule>): readonly HarnessModule[] {
+    const ordered: HarnessModule[] = [];
+    const completed = new Set<string>();
+    const active = new Set<string>();
+
+    for (const module of byId.values()) {
+        if (completed.has(module.id)) {
+            continue;
+        }
+
+        const pending: ModuleFrame[] = [{ module, next: 0 }];
+        active.add(module.id);
+
+        while (pending.length > 0) {
+            const frame = pending.at(-1);
+
+            if (!frame) {
+                throw new Error("A module frame must exist while ordering is pending.");
+            }
+
+            const id = frame.module.requires?.[frame.next];
+
+            if (id === undefined) {
+                pending.pop();
+                active.delete(frame.module.id);
+                completed.add(frame.module.id);
+                ordered.push(frame.module);
+                continue;
+            }
+
+            frame.next += 1;
+            const dependency = byId.get(id);
+
+            if (!dependency) {
+                throw new RuntimeError(
+                    "MissingModule",
+                    `Module "${frame.module.id}" requires missing module "${id}".`,
+                );
+            }
+
+            if (completed.has(id)) {
+                continue;
+            }
+
+            if (active.has(id)) {
+                const chain = [...pending.map((frame) => frame.module.id), id].join(" -> ");
+
+                throw new RuntimeError("ModuleCycle", `Module dependency cycle: ${chain}.`);
+            }
+
+            active.add(id);
+            pending.push({ module: dependency, next: 0 });
+        }
+    }
+
+    return ordered;
+}

package/src/core/operation.ts

@@ -0,0 +1,43 @@
+import { RuntimeError } from "./errors.js";
+import type { AsyncHandler, SyncHandler } from "./types.js";
+
+const bindings = Symbol("operation bindings");
+
+export type OperationBinding<Input, Output> =
+    | { readonly mode: "sync"; readonly handler: SyncHandler<Input, Output> }
+    | { readonly mode: "async"; readonly handler: AsyncHandler<Input, Output> };
+
+export interface Operation<Input, Output> {
+    readonly name: string;
+    readonly [bindings]: WeakMap<object, OperationBinding<Input, Output>>;
+}
+
+export function defineOperation<Input, Output>(name: string): Operation<Input, Output> {
+    if (typeof name !== "string" || name.trim().length === 0 || name.length > 1024) {
+        throw new RuntimeError("InvalidOperation", "An operation needs a non-empty name.");
+    }
+
+    return Object.freeze({
+        name,
+        [bindings]: new WeakMap<object, OperationBinding<Input, Output>>(),
+    });
+}
+
+export function bindOperation<Input, Output>(
+    operation: Operation<Input, Output>,
+    owner: object,
+    binding: OperationBinding<Input, Output>,
+): () => void {
+    operation[bindings].set(owner, binding);
+
+    return () => {
+        operation[bindings].delete(owner);
+    };
+}
+
+export function getOperationBinding<Input, Output>(
+    operation: Operation<Input, Output>,
+    owner: object,
+): OperationBinding<Input, Output> | undefined {
+    return operation[bindings].get(owner);
+}

package/src/core/process.ts

@@ -0,0 +1,55 @@
+const outputBytesMax = 1_048_576;
+
+/** Drain pipes while retaining bounded diagnostics; a full buffer must not deadlock the child. */
+export async function readProcessOutput(
+    stream: ReadableStream<Uint8Array>,
+    signal?: AbortSignal,
+): Promise<string> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    const chunks: string[] = [];
+    let bytes = 0;
+    let truncated = false;
+    const cancel = (): void => {
+        void reader.cancel(signal?.reason).catch(() => {
+            // The pipe may already be closed; the owner still receives the abort below.
+        });
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+
+    if (signal?.aborted) {
+        cancel();
+    }
+
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            signal?.throwIfAborted();
+
+            if (chunk.done) {
+                break;
+            }
+
+            const available = outputBytesMax - bytes;
+            const captured = chunk.value.subarray(0, Math.max(0, available));
+
+            if (captured.length > 0) {
+                chunks.push(decoder.decode(captured, { stream: true }));
+            }
+
+            bytes += captured.length;
+            truncated ||= captured.length !== chunk.value.length;
+        }
+
+        chunks.push(decoder.decode());
+    } finally {
+        signal?.removeEventListener("abort", cancel);
+        reader.releaseLock();
+    }
+
+    if (truncated) {
+        chunks.push("\n[Build output truncated at the diagnostic byte limit.]\n");
+    }
+
+    return chunks.join("");
+}

package/src/core/resources.ts

@@ -0,0 +1,34 @@
+import { mkdtemp, rm } from "node:fs/promises";
+
+/** Preserve both failures when temporary work and filesystem cleanup fail together. */
+export async function withTemporaryDirectory<Value>(
+    prefix: string,
+    work: (directory: string) => Promise<Value>,
+): Promise<Value> {
+    const directory = await mkdtemp(prefix);
+    let outcome: { ok: true; value: Value } | { ok: false; error: unknown };
+
+    try {
+        outcome = { ok: true, value: await work(directory) };
+    } catch (error) {
+        outcome = { ok: false, error };
+    }
+
+    try {
+        await rm(directory, { recursive: true, force: true });
+    } catch (error) {
+        if (!outcome.ok) {
+            throw new AggregateError([outcome.error, error], "Work and cleanup failed.", {
+                cause: error,
+            });
+        }
+
+        throw error;
+    }
+
+    if (!outcome.ok) {
+        throw outcome.error;
+    }
+
+    return outcome.value;
+}