@lix-js/sdk 0.16.1 → 0.17.0

package/dist/component-host/dispatch.js

@@ -0,0 +1,364 @@
+/** One isolated handle registry per engine runtime, shared by Node and browsers. */
+export function createComponentDispatch() {
+    const factories = new Map();
+    const guests = new Map();
+    const pending = new Map();
+    const begin = (requestId) => {
+        if (requestId == null)
+            return undefined;
+        const key = String(requestId);
+        let entry = pending.get(key);
+        if (!entry) {
+            entry = { canceled: false, completed: false };
+            pending.set(key, entry);
+        }
+        return { key, entry };
+    };
+    const complete = (token, dispose) => {
+        if (!token)
+            return;
+        token.entry.completed = true;
+        token.entry.dispose = dispose;
+        if (token.entry.canceled) {
+            dispose();
+            pending.delete(token.key);
+        }
+    };
+    let sequence = 0;
+    const allocate = () => {
+        if (++sequence > Number.MAX_SAFE_INTEGER)
+            throw new Error("Component handle space exhausted");
+        return sequence;
+    };
+    return async (request) => {
+        const data = JSON.parse(request.data);
+        switch (request.operation) {
+            case "compile": {
+                const token = begin(data.requestId);
+                try {
+                    if (!(request.bytes instanceof Uint8Array))
+                        throw new Error("Missing component bytes");
+                    const { compileComponent } = await import("./index.js");
+                    const factory = await compileComponent(request.bytes, data.limits);
+                    const id = allocate();
+                    factories.set(id, factory);
+                    complete(token, () => {
+                        factories.delete(id);
+                    });
+                    return JSON.stringify({ id });
+                }
+                catch (error) {
+                    complete(token, () => { });
+                    throw error;
+                }
+            }
+            case "instantiate": {
+                const token = begin(data.requestId);
+                try {
+                    const factory = factories.get(data.id);
+                    if (!factory)
+                        throw new Error("Unknown component factory");
+                    const resources = resourceTypes();
+                    const instance = await factory.instantiate({
+                        ...wasiImports(),
+                        "lix:plugin-v2/host": resources,
+                        // Previously published v2 components retain their original identity.
+                        "lix:plugin/host": resources,
+                    });
+                    const id = allocate();
+                    guests.set(id, { instance, resources, busy: false });
+                    complete(token, () => {
+                        guests.delete(id);
+                    });
+                    return JSON.stringify({ id });
+                }
+                catch (error) {
+                    complete(token, () => { });
+                    throw error;
+                }
+            }
+            case "invoke": {
+                const guest = guests.get(data.id);
+                if (!guest || guest.busy)
+                    throw new Error("Unknown or busy component guest");
+                if (!request.host)
+                    throw new Error("Missing component host");
+                guest.busy = true;
+                const scope = { host: request.host, active: true };
+                try {
+                    guest.instance.setDeadline(Number(data.limits.timeoutMs ?? 5000));
+                    const { input, output } = data.input;
+                    const r = guest.resources;
+                    const wrap = (kind, id) => new r[kind](scope, id);
+                    let argument;
+                    let sink;
+                    let iface;
+                    if (data.operation === "merge") {
+                        argument = wrap("ColumnMergeSource", input);
+                        sink = wrap("ColumnMergeSink", output);
+                        iface = guest.instance.exports.columnMerger;
+                    }
+                    else {
+                        argument = decode(input);
+                        sink = wrap("Transition", output);
+                        iface = guest.instance.exports.fileProjection;
+                        switch (data.operation) {
+                            case "parse":
+                                argument.file = wrap("Snapshot", input.file);
+                                break;
+                            case "parseChanges":
+                                argument.before = wrap("Snapshot", input.before);
+                                argument.rows =
+                                    input.rows == null
+                                        ? undefined
+                                        : wrap("RowSource", input.rows);
+                                break;
+                            case "serialize":
+                                argument.rows = wrap("RowSource", input.rows);
+                                argument.before =
+                                    input.before == null
+                                        ? undefined
+                                        : wrap("Snapshot", input.before);
+                                break;
+                            case "serializeChanges":
+                                argument.before = wrap("Snapshot", input.before);
+                                argument.rowChanges = wrap("RowSource", input.rowChanges);
+                                break;
+                            default:
+                                throw new Error(`Unknown component operation ${data.operation}`);
+                        }
+                    }
+                    const fn = iface?.[data.operation];
+                    if (typeof fn !== "function")
+                        throw new Error(`Component does not export ${data.operation}`);
+                    await fn(argument, sink);
+                    const memory = JSON.parse(scope.host.call("runtime.memoryHighWater", JSON.stringify({ bytes: String(guest.instance.memoryBytes()) })));
+                    if (memory.error)
+                        throw memory.error;
+                    return "null";
+                }
+                catch (error) {
+                    const payload = error?.payload;
+                    if (payload?.tag &&
+                        ["invalid-input", "limit-exceeded", "internal"].includes(payload.tag))
+                        return JSON.stringify({ pluginError: payload });
+                    throw error;
+                }
+                finally {
+                    scope.active = false;
+                    request.host.free?.();
+                    guest.busy = false;
+                }
+            }
+            case "cancelRequest": {
+                const token = begin(data.requestId ?? data.id);
+                if (token) {
+                    token.entry.canceled = true;
+                    token.entry.dispose?.();
+                    if (token.entry.completed)
+                        pending.delete(token.key);
+                }
+                return "null";
+            }
+            case "finishRequest":
+                pending.delete(String(data.requestId ?? data.id));
+                return "null";
+            case "disposeFactory":
+                factories.delete(data.id);
+                return "null";
+            case "disposeGuest":
+                guests.delete(data.id);
+                return "null";
+            default:
+                throw new Error(`Unknown component dispatch operation ${request.operation}`);
+        }
+    };
+}
+const u64Fields = new Set([
+    "high",
+    "offset",
+    "deleteLen",
+    "totalLen",
+    "totalLength",
+    "baseLen",
+    "aLen",
+    "bLen",
+    "baseRowLen",
+    "aRowLen",
+    "bRowLen",
+]);
+const byteFields = new Set(["bytes", "payload", "schemaFingerprint", "insert"]);
+function decode(value, key = "") {
+    if (value == null)
+        return undefined;
+    if (u64Fields.has(key))
+        return BigInt(value);
+    if (byteFields.has(key))
+        return Uint8Array.from(value);
+    if (key === "primaryKey" || key === "attachments")
+        return value.map((bytes) => Uint8Array.from(bytes));
+    if (Array.isArray(value))
+        return value.map((item) => decode(item));
+    if (typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, decode(v, k)]));
+    return value;
+}
+function encode(_key, value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Uint8Array)
+        return Array.from(value);
+    return value;
+}
+function resourceTypes() {
+    class Resource {
+        scope;
+        id;
+        constructor(scope, id) {
+            this.scope = scope;
+            this.id = id;
+        }
+        invoke(type, method, names, values) {
+            if (!this.scope.active)
+                throw new Error("Component resource invocation has ended");
+            const args = {
+                resource: this.id,
+                ...Object.fromEntries(names.map((name, i) => [name, values[i]])),
+            };
+            const result = JSON.parse(this.scope.host.call(`${type}.${method}`, JSON.stringify(args, encode)));
+            if (result.error)
+                throw result.error;
+            if (method === "fileLen")
+                return BigInt(result.ok);
+            if (method === "readFile" ||
+                method === "readRow" ||
+                method === "readValue")
+                return result.ok == null ? undefined : Uint8Array.from(result.ok);
+            return decode(result.ok);
+        }
+    }
+    const define = (type, methods) => {
+        class Handle extends Resource {
+        }
+        for (const [method, names] of Object.entries(methods))
+            Object.defineProperty(Handle.prototype, method, {
+                value: function (...values) {
+                    return this.invoke(type, method, names, values);
+                },
+            });
+        Object.defineProperty(Handle.prototype, Symbol.dispose || Symbol.for("dispose"), {
+            value: function () {
+                if (this.scope.active)
+                    this.invoke(type, "drop", [], []);
+            },
+        });
+        return Handle;
+    };
+    return {
+        Snapshot: define("snapshot", {
+            fileLen: [],
+            readFile: ["offset", "length"],
+            readState: ["key", "offset", "maxBytes"],
+        }),
+        RowSource: define("rowSource", { nextPage: ["maxBytes"] }),
+        Transition: define("transition", {
+            maxBatchBytes: [],
+            putState: ["key", "value"],
+            deleteState: ["key"],
+            deleteStatePrefix: ["prefix"],
+            emitRows: ["page"],
+            replaceAllRows: [],
+            emitFileEdit: ["edit"],
+            beginFileReplacement: ["totalLength"],
+            writeFileReplacement: ["chunk"],
+            finishFileReplacement: [],
+        }),
+        ColumnMergeSource: define("columnMergeSource", {
+            len: [],
+            get: ["index"],
+            readValue: ["index", "side", "offset", "length"],
+            readRow: ["index", "side", "offset", "length"],
+        }),
+        ColumnMergeSink: define("columnMergeSink", {
+            maxBatchBytes: [],
+            useLww: ["ordinal"],
+            beginReplace: ["ordinal", "totalLength"],
+            writeReplacement: ["chunk"],
+            finishReplace: [],
+        }),
+    };
+}
+/** Closed input, discarded output, and no ambient filesystem/network grants. */
+function wasiImports() {
+    class Pollable {
+        ready() {
+            return true;
+        }
+        block() { }
+    }
+    class InputStream {
+        read() {
+            throw { tag: "closed" };
+        }
+        blockingRead() {
+            return this.read();
+        }
+        subscribe() {
+            return new Pollable();
+        }
+    }
+    class OutputStream {
+        checkWrite() {
+            return 65536n;
+        }
+        write() { }
+        flush() { }
+        blockingFlush() { }
+        blockingWriteAndFlush() { }
+        subscribe() {
+            return new Pollable();
+        }
+    }
+    class TerminalInput {
+    }
+    class TerminalOutput {
+    }
+    class IoError {
+        toDebugString() {
+            return "Component stream error";
+        }
+    }
+    return {
+        "wasi:cli/environment": {
+            getEnvironment: () => [],
+            getArguments: () => [],
+            initialCwd: () => undefined,
+        },
+        "wasi:cli/exit": {
+            exit() {
+                throw new Error("Component requested process exit");
+            },
+        },
+        "wasi:cli/stdin": { getStdin: () => new InputStream() },
+        "wasi:cli/stdout": { getStdout: () => new OutputStream() },
+        "wasi:cli/stderr": { getStderr: () => new OutputStream() },
+        "wasi:cli/terminal-input": { TerminalInput },
+        "wasi:cli/terminal-output": { TerminalOutput },
+        "wasi:cli/terminal-stdin": { getTerminalStdin: () => undefined },
+        "wasi:cli/terminal-stdout": { getTerminalStdout: () => undefined },
+        "wasi:cli/terminal-stderr": { getTerminalStderr: () => undefined },
+        "wasi:clocks/monotonic-clock": {
+            now: () => BigInt(Math.floor(performance.now() * 1e6)),
+            resolution: () => 1000000n,
+            subscribeDuration: () => new Pollable(),
+            subscribeInstant: () => new Pollable(),
+        },
+        "wasi:io/error": { Error: IoError },
+        "wasi:io/poll": {
+            Pollable,
+            poll: (items) => Uint32Array.from(items.map((_, i) => i)),
+        },
+        "wasi:io/streams": { InputStream, OutputStream },
+        "wasi:random/insecure-seed": { insecureSeed: () => [0n, 0n] },
+    };
+}

package/dist/component-host/index.d.ts

@@ -0,0 +1,15 @@
+export type ComponentImports = Record<string, unknown>;
+export type ComponentLimits = {
+    maxMemoryBytes: string;
+    maxFuel?: string | null;
+    timeoutMs?: string | null;
+};
+export type ComponentInstance = {
+    exports: Record<string, any>;
+    memoryBytes(): number;
+    setDeadline(milliseconds: number): void;
+};
+/** Compile once, instantiate separately for every engine actor. */
+export declare function compileComponent(bytes: Uint8Array, limits: ComponentLimits): Promise<{
+    instantiate(imports: ComponentImports): Promise<ComponentInstance>;
+}>;

package/dist/component-host/index.js

@@ -0,0 +1,84 @@
+import { $init, generate } from "@bytecodealliance/jco-transpile/component";
+import { coreMemoryCount, coreTableCount, instrumentCore, TICK_MODULE, } from "./instrument.js";
+/** Compile once, instantiate separately for every engine actor. */
+export async function compileComponent(bytes, limits) {
+    if (limits.maxFuel != null)
+        throw new Error("Instruction fuel limits are unsupported by the JavaScript Component host");
+    await $init;
+    const output = generate(bytes, {
+        name: "plugin",
+        instantiation: { tag: "async" },
+        noTypescript: true,
+        noNodejsCompat: true,
+        base64Cutoff: 0,
+    });
+    const cores = output.files.filter(([name]) => name.endsWith(".wasm"));
+    const memoryCount = cores.reduce((total, [, core]) => total + coreMemoryCount(core), 0);
+    if (memoryCount > 1)
+        throw new Error("Multiple component memories are unsupported");
+    if (cores.reduce((total, [, core]) => total + coreTableCount(core), 0) > 8)
+        throw new Error("Component table count exceeds limit");
+    const modules = new Map();
+    const tableCounts = new Map();
+    for (const [name, core] of cores) {
+        const compiled = await WebAssembly.compile(instrumentCore(core, Math.floor(Number(limits.maxMemoryBytes) / Math.max(1, memoryCount))));
+        if (WebAssembly.Module.imports(compiled).some((item) => item.kind === "memory"))
+            throw new Error("Imported component memories are unsupported");
+        modules.set(name, compiled);
+        tableCounts.set(compiled, coreTableCount(core));
+    }
+    const js = output.files.find(([name]) => name === "plugin.js")?.[1];
+    if (!js)
+        throw new Error("Component transpiler did not emit JavaScript bindings");
+    const url = `data:text/javascript;charset=utf-8,${encodeURIComponent(new TextDecoder().decode(js))}`;
+    const binding = await import(/* @vite-ignore */ url);
+    return {
+        async instantiate(imports) {
+            const memories = [];
+            let tableCount = 0;
+            let instanceCount = 0;
+            let deadline = performance.now() + Number(limits.timeoutMs ?? 5000);
+            const exports = await binding.instantiate((name) => {
+                const module = modules.get(name);
+                if (!module)
+                    throw new Error(`Unknown component core module ${name}`);
+                return module;
+            }, imports, (module, coreImports) => {
+                // Match Wasmtime's StoreLimitsBuilder::instances limit, including
+                // memoryless/tableless modules and repeated instances of one module.
+                if (++instanceCount > 64)
+                    throw new Error("Component core instance count exceeds limit");
+                if (memories.length &&
+                    WebAssembly.Module.exports(module).some((item) => item.name === "__lix_runtime_memory"))
+                    throw new Error("Multiple component memory instances are unsupported");
+                tableCount += tableCounts.get(module) ?? 0;
+                if (tableCount > 8)
+                    throw new Error("Component table instance count exceeds limit");
+                const instance = new WebAssembly.Instance(module, {
+                    ...coreImports,
+                    [TICK_MODULE]: {
+                        tick() {
+                            if (performance.now() >= deadline)
+                                throw new Error("Component execution deadline exceeded");
+                        },
+                    },
+                });
+                const memory = instance.exports.__lix_runtime_memory;
+                if (memory instanceof WebAssembly.Memory)
+                    memories.push(memory);
+                return instance;
+            });
+            return {
+                exports,
+                memoryBytes: () => memories.reduce((total, memory) => total + memory.buffer.byteLength, 0),
+                setDeadline(milliseconds) {
+                    if (!Number.isFinite(milliseconds) || milliseconds <= 0)
+                        throw new Error("Invalid component deadline");
+                    deadline =
+                        performance.now() +
+                            Math.min(milliseconds, Number(limits.timeoutMs ?? milliseconds));
+                },
+            };
+        },
+    };
+}

package/dist/component-host/instrument.d.ts

@@ -0,0 +1,6 @@
+export declare const TICK_MODULE = "lix:runtime/deadline";
+/** Add checks on every cycle (function/loop entry) and cap memory before compilation. */
+export declare function instrumentCore(bytes: Uint8Array, maxMemoryBytes: number): Uint8Array;
+/** Count defined memories to apportion the component's aggregate ceiling. */
+export declare function coreMemoryCount(bytes: Uint8Array): number;
+export declare function coreTableCount(bytes: Uint8Array): number;