@oliphaunt/wasix-ts 0.1.0

package/lib/worker-dispatch.js

@@ -0,0 +1,174 @@
+import { WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES, } from './database.js';
+import { restoreWasixSerialized } from './client-common.js';
+import { serializeWorkerError, } from './rpc.js';
+import { prepareTransferableBytes } from './worker-transfer.js';
+class WorkerStreamCallbackAborted extends Error {
+}
+/** @internal One request state machine shared by browser and server worker realms. */
+export function createWorkerSessionDispatcher(openSession, respond, restore = restoreWasixSerialized, lifecycle = {}) {
+    let process;
+    let terminal = false;
+    return async (request) => {
+        let quiescentClose = false;
+        try {
+            if (terminal) {
+                throw new Error('Oliphaunt WASIX worker session is closed');
+            }
+            switch (request.method) {
+                case 'open':
+                    if (process !== undefined) {
+                        throw new Error('this worker already owns an Oliphaunt WASIX process');
+                    }
+                    process = await openSession(request.options);
+                    respond({ id: request.id, ok: true });
+                    return;
+                case 'restore':
+                    if (process !== undefined) {
+                        throw new Error('this worker already owns an Oliphaunt WASIX process');
+                    }
+                    await restore(request.storage, request.bytes);
+                    respond({ id: request.id, ok: true });
+                    return;
+                case 'exec': {
+                    const response = prepareTransferableBytes(await requireProcess(process).exec(request.input, request.persistence));
+                    respond({ id: request.id, ok: true, value: response.value }, response.transfer);
+                    return;
+                }
+                case 'execStream': {
+                    const session = requireProcess(process);
+                    const control = new Int32Array(request.control);
+                    let sequence = 0;
+                    const onChunk = (chunk) => {
+                        if (Atomics.load(control, 1) !== 0) {
+                            throw new WorkerStreamCallbackAborted('protocol stream consumer failed');
+                        }
+                        sequence += 1;
+                        const prepared = prepareTransferableBytes(chunk);
+                        respond({
+                            id: request.id,
+                            kind: 'chunk',
+                            sequence,
+                            value: prepared.value,
+                        }, prepared.transfer);
+                        while (Atomics.load(control, 0) < sequence) {
+                            Atomics.wait(control, 0, sequence - 1);
+                        }
+                        if (Atomics.load(control, 1) !== 0) {
+                            throw new WorkerStreamCallbackAborted('protocol stream consumer failed');
+                        }
+                        return undefined;
+                    };
+                    let outcome;
+                    if (session.execStream === undefined) {
+                        const response = await session.exec(request.input, request.persistence);
+                        outcome = 'complete';
+                        try {
+                            for (let offset = 0; offset < response.length; offset += WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES) {
+                                onChunk(response.slice(offset, offset + WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES));
+                            }
+                        }
+                        catch (error) {
+                            if (!(error instanceof WorkerStreamCallbackAborted))
+                                throw error;
+                            outcome = 'callbackAborted';
+                        }
+                    }
+                    else {
+                        outcome = await session.execStream(request.input, onChunk, request.persistence);
+                    }
+                    respond({ id: request.id, ok: true, streamOutcome: outcome });
+                    return;
+                }
+                case 'sync':
+                    await requireProcess(process).sync(request.boundary);
+                    respond({ id: request.id, ok: true });
+                    return;
+                case 'backup': {
+                    const session = requireProcess(process);
+                    if (session.backup === undefined) {
+                        throw new Error('this WASIX worker session does not support physical backup');
+                    }
+                    const archive = prepareTransferableBytes(await session.backup());
+                    respond({ id: request.id, ok: true, value: archive.value }, archive.transfer);
+                    return;
+                }
+                case 'runPgDump': {
+                    const session = requireProcess(process);
+                    if (session.runPgDump === undefined) {
+                        throw new Error('this WASIX worker session does not support pg_dump');
+                    }
+                    const result = await session.runPgDump({ tool: request.tool, args: request.args });
+                    const stdout = prepareTransferableBytes(result.stdout);
+                    const stderr = prepareTransferableBytes(result.stderr);
+                    respond({
+                        id: request.id,
+                        ok: true,
+                        value: {
+                            exitCode: result.exitCode,
+                            stdout: stdout.value,
+                            stderr: stderr.value,
+                        },
+                    }, [...new Set([...stdout.transfer, ...stderr.transfer])]);
+                    return;
+                }
+                case 'runTool': {
+                    const session = requireProcess(process);
+                    if (session.runTool === undefined) {
+                        throw new Error('this WASIX worker session does not support native tools');
+                    }
+                    const result = await session.runTool(request.options);
+                    const stdout = prepareTransferableBytes(result.stdout);
+                    const stderr = prepareTransferableBytes(result.stderr);
+                    respond({
+                        id: request.id,
+                        ok: true,
+                        value: {
+                            exitCode: result.exitCode,
+                            stdout: stdout.value,
+                            stderr: stderr.value,
+                        },
+                    }, [...new Set([...stdout.transfer, ...stderr.transfer])]);
+                    return;
+                }
+                case 'serve': {
+                    const session = requireProcess(process);
+                    if (session.serve === undefined) {
+                        throw new Error('this WASIX worker session does not support protocol connections');
+                    }
+                    await session.serve(request.connection, request.mode);
+                    respond({ id: request.id, ok: true });
+                    return;
+                }
+                case 'close': {
+                    const closing = requireProcess(process);
+                    // Retire the dispatcher before awaiting guest/provider teardown. A
+                    // rejected close cannot make a Worker whose transport will be
+                    // destroyed by its owner safe to reopen or use again.
+                    process = undefined;
+                    terminal = true;
+                    quiescentClose = true;
+                    await closing.close();
+                    respond({ id: request.id, ok: true });
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            respond({
+                id: request.id,
+                ok: false,
+                error: serializeWorkerError(error),
+            });
+        }
+        finally {
+            if (quiescentClose)
+                lifecycle.onQuiescentClose?.();
+        }
+    };
+}
+function requireProcess(process) {
+    if (process === undefined) {
+        throw new Error('Oliphaunt WASIX process is not open');
+    }
+    return process;
+}

package/lib/worker-entry.bun.d.ts

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-node-client.js';
+export * from './public.js';

package/lib/worker-entry.bun.js

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-node-client.js';
+export * from './public.js';

package/lib/worker-entry.d.ts

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-client.js';
+export * from './public.js';

package/lib/worker-entry.deno.d.ts

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-node-client.js';
+export * from './public.js';

package/lib/worker-entry.deno.js

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-node-client.js';
+export * from './public.js';

package/lib/worker-entry.js

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-client.js';
+export * from './public.js';

package/lib/worker-entry.node.d.ts

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-node-client.js';
+export * from './public.js';

package/lib/worker-entry.node.js

@@ -0,0 +1,2 @@
+export { Oliphaunt, Oliphaunt as default } from './worker-node-client.js';
+export * from './public.js';

package/lib/worker-node-client.d.ts

@@ -0,0 +1,4 @@
+import type { OliphauntClient, OliphauntDatabase, OpenConfig } from './types.js';
+/** Open PostgreSQL in a package-owned Node-compatible Worker realm. */
+export declare function openWasix(config?: OpenConfig): Promise<OliphauntDatabase>;
+export declare const Oliphaunt: OliphauntClient;

package/lib/worker-node-client.js

@@ -0,0 +1,55 @@
+import { Worker } from 'node:worker_threads';
+import { serializeOpenConfig } from './client-common.js';
+import { hostRuntimeName } from './host-runtime.js';
+import { requireNodeStorage } from './node-client-common.js';
+import { nodeWorkerExecArgv } from './node-worker-options.js';
+import { nodeWorkerPort } from './node-worker-port.js';
+import { openWasixWithWorker, restoreWasixWithWorker } from './worker-rpc.js';
+/** Open PostgreSQL in a package-owned Node-compatible Worker realm. */
+export async function openWasix(config = {}) {
+    // The native Worker owns release-embedded runtime assets. Do not structured-
+    // clone caller-provided WebAssembly archives that the N-API path will never
+    // read; retain their exact identity metadata for compatibility validation.
+    const openOptions = withoutNativeAssetPayloads(serializeOpenConfig(config));
+    return openWasixWithWorker(createNodeWorker, openOptions, requireNodeStorage, false);
+}
+export const Oliphaunt = {
+    open: openWasix,
+    restore: restoreNodeWasixWithWorker,
+};
+async function restoreNodeWasixWithWorker(storage, bytes) {
+    return restoreWasixWithWorker(createNodeWorker, storage, bytes, requireNodeStorage);
+}
+function createNodeWorker(_options) {
+    return nodeWorkerPort(new Worker(new URL('./node-worker.js', import.meta.url), {
+        execArgv: nodeWorkerExecArgv(),
+        name: 'oliphaunt-wasix',
+    }), hostRuntimeName());
+}
+function withoutNativeAssetPayloads(options) {
+    const source = 'oliphaunt:wasix-napi-embedded';
+    return {
+        ...options,
+        runtime: {
+            ...options.runtime,
+            runtimeArchive: { ...options.runtime.runtimeArchive, source },
+            standardSeedArchive: { ...options.runtime.standardSeedArchive, source },
+            standardSeedManifest: { ...options.runtime.standardSeedManifest, source },
+            manifest: { ...options.runtime.manifest, source },
+        },
+        ...(options.icu === undefined
+            ? {}
+            : {
+                icu: {
+                    ...options.icu,
+                    dataArchive: { ...options.icu.dataArchive, source },
+                    clusterSeedArchive: { ...options.icu.clusterSeedArchive, source },
+                    clusterSeedManifest: { ...options.icu.clusterSeedManifest, source },
+                },
+            }),
+        extensionCarriers: Object.fromEntries(Object.entries(options.extensionCarriers).map(([sqlName, carrier]) => [
+            sqlName,
+            { ...carrier, source },
+        ])),
+    };
+}

package/lib/worker-rpc.d.ts

@@ -0,0 +1,36 @@
+import { type WasixDatabaseSessionTerminalState, type WasixPersistenceMode, type WasixProtocolStreamOutcome } from './database.js';
+import type { SerializedOpenOptions, WorkerRequest, WorkerResponse } from './rpc.js';
+import type { BinaryInput, OliphauntDatabase, OpenConfig } from './types.js';
+import type { WasixToolProcessResult } from './tool-runtime.js';
+type WorkerResponseValue = Uint8Array | WasixToolProcessResult | WasixProtocolStreamOutcome | undefined;
+type WorkerRequestWithoutId = WorkerRequest extends infer Request ? Request extends {
+    id: number;
+} ? Omit<Request, 'id'> : never : never;
+export type WasixWorkerPort = {
+    /** Shared memory is available only for a same-process Worker transport. */
+    readonly supportsSharedMemory?: boolean;
+    postMessage(message: WorkerRequest, transfer: readonly Transferable[]): void;
+    /** Mark and await a Worker-initiated exit after its quiescent close reply. */
+    expectSelfExit?(): Promise<void>;
+    terminate(): void | Promise<void>;
+    onMessage(listener: (message: WorkerResponse) => void): void;
+    onFatal(listener: (error: Error) => void): void;
+};
+/** @internal Open through a package-owned isolated host without burdening the direct graph. */
+export declare function openWasixWithWorker(createWorker: (options: SerializedOpenOptions) => WasixWorkerPort, openOptions: SerializedOpenOptions, validate?: (options: SerializedOpenOptions) => void, transferAssets?: boolean): Promise<OliphauntDatabase>;
+/** @internal Restore through a temporary package-owned isolated host. */
+export declare function restoreWasixWithWorker(createWorker: (options: SerializedOpenOptions) => WasixWorkerPort, storage: OpenConfig['storage'], bytes: BinaryInput, validate?: (options: SerializedOpenOptions) => void): Promise<void>;
+/** @internal Correlates worker requests and fails them as one unit if the worker exits. */
+export declare class WorkerRpc {
+    #private;
+    readonly terminalState: WasixDatabaseSessionTerminalState;
+    constructor(worker: WasixWorkerPort);
+    get supportsSharedMemory(): boolean;
+    request(request: WorkerRequestWithoutId, transfer?: Transferable[]): Promise<WorkerResponseValue>;
+    stream(input: Uint8Array, persistence: WasixPersistenceMode, onChunk: (chunk: Uint8Array) => void): Promise<WasixProtocolStreamOutcome>;
+    terminate(): Promise<void>;
+    expectSelfExit(): Promise<void> | undefined;
+}
+/** @internal Opens exactly one database and guarantees worker cleanup on failure. */
+export declare function openWorkerDatabase(worker: WasixWorkerPort, options: SerializedOpenOptions, transfer?: Transferable[]): Promise<OliphauntDatabase>;
+export {};