@oliphaunt/wasix-ts 0.1.0

package/lib/native-server.d.ts

@@ -0,0 +1,21 @@
+import type { OpenConfig } from './types.js';
+export type ServerListen = Readonly<{
+    transport: 'tcp';
+    port?: number;
+}> | Readonly<{
+    transport: 'unix';
+    directory: string;
+    port?: number;
+}>;
+export type ServerOpenConfig = OpenConfig & Readonly<{
+    listen?: ServerListen;
+}>;
+export type OliphauntServer = Readonly<{
+    connectionString: string;
+    /** True after the one terminal close attempt settles, including on failure. */
+    readonly closed: boolean;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}>;
+/** Open the Rust WASIX local server without a JavaScript socket/protocol relay. */
+export declare function openServer(config?: ServerOpenConfig): Promise<OliphauntServer>;

package/lib/native-server.js

@@ -0,0 +1,109 @@
+import { resolve } from 'node:path';
+import { serializeOpenConfig } from './client-common.js';
+import { mapNativeError, nativeWasixOpenOptions, requireCompatibleNativeWasixAddon, } from './native-session.js';
+import { requireNodeStorage } from './node-client-common.js';
+/** Open the Rust WASIX local server without a JavaScript socket/protocol relay. */
+export async function openServer(config = {}) {
+    const { listen: requestedListen, ...databaseConfig } = config;
+    const options = serializeOpenConfig(databaseConfig);
+    requireNodeStorage(options);
+    const addon = requireCompatibleNativeWasixAddon(options);
+    const listen = nativeListen(requestedListen ?? { transport: 'tcp' });
+    let storage;
+    if (options.storage.kind === 'memory') {
+        storage = { kind: 'memory' };
+    }
+    else if (options.storage.kind === 'directory') {
+        storage = { kind: 'directory', path: options.storage.path };
+    }
+    else {
+        throw new TypeError('Oliphaunt WASIX native server requires memory or directory storage');
+    }
+    let handle;
+    let connectionString;
+    try {
+        handle = await addon.NativeWasixServer.open({
+            ...nativeWasixOpenOptions(options, storage),
+            listen,
+        });
+        connectionString = validateServerHandle(handle);
+    }
+    catch (error) {
+        throw mapNativeError(error);
+    }
+    return new NativeServerState(handle, connectionString).publicHandle();
+}
+class NativeServerState {
+    #handle;
+    #connectionString;
+    #closed = false;
+    #closeAttempt;
+    constructor(handle, connectionString) {
+        this.#handle = handle;
+        this.#connectionString = connectionString;
+    }
+    publicHandle() {
+        const state = this;
+        return Object.freeze({
+            connectionString: this.#connectionString,
+            get closed() {
+                return state.#closed || state.#handle.closed;
+            },
+            close: () => state.close(),
+            [Symbol.asyncDispose]: () => state.close(),
+        });
+    }
+    close() {
+        if (this.#closeAttempt !== undefined)
+            return this.#closeAttempt;
+        this.#closeAttempt = this.#close();
+        return this.#closeAttempt;
+    }
+    async #close() {
+        try {
+            await this.#handle.close();
+        }
+        catch (error) {
+            throw mapNativeError(error);
+        }
+        finally {
+            this.#closed = true;
+        }
+    }
+}
+function nativeListen(listen) {
+    if (listen.transport === 'tcp') {
+        if (listen.port !== undefined &&
+            (!Number.isSafeInteger(listen.port) || listen.port < 1 || listen.port > 65_535)) {
+            throw new TypeError('Oliphaunt WASIX TCP port must be an integer in 1..=65535');
+        }
+        return listen.port === undefined
+            ? { transport: 'tcp' }
+            : { transport: 'tcp', port: listen.port };
+    }
+    if (process.platform === 'win32') {
+        throw new Error('Unix-domain server listeners are not supported on Windows');
+    }
+    if (typeof listen.directory !== 'string' ||
+        listen.directory.trim().length === 0 ||
+        listen.directory.includes('\0')) {
+        throw new TypeError('WASIX server Unix socket directory must be non-empty without NUL bytes');
+    }
+    const port = listen.port ?? 5432;
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+        throw new TypeError('Oliphaunt WASIX Unix socket port must be an integer in 1..=65535');
+    }
+    const directory = resolve(listen.directory);
+    return { transport: 'unix', directory, port };
+}
+function validateServerHandle(handle) {
+    if (typeof handle !== 'object' ||
+        handle === null ||
+        typeof handle.closed !== 'boolean' ||
+        typeof handle.connectionString !== 'string' ||
+        handle.connectionString.length === 0 ||
+        typeof handle.close !== 'function') {
+        throw new Error('Oliphaunt WASIX native addon returned an invalid server handle');
+    }
+    return handle.connectionString;
+}

package/lib/native-session.d.ts

@@ -0,0 +1,60 @@
+import { type NativeWasixAddon, type NativeWasixOpenOptions } from './native-addon.js';
+import { type WasixDatabaseIdentity, type WasixDatabaseSession, type WasixDatabaseSessionTerminalState, type WasixPersistenceMode, type WasixProtocolStreamOutcome } from './database.js';
+import type { SerializedOpenOptions } from './rpc.js';
+import type { WasixStorageSyncBoundary } from './storage-provider.js';
+import type { WasixPgDumpProcessOptions, WasixToolProcessOptions, WasixToolProcessResult } from './tool-runtime.js';
+/** @internal A synchronous Rust Oliphaunt owned by the importing JavaScript realm. */
+export declare class NativeWasixSession implements WasixDatabaseSession {
+    #private;
+    readonly identity: WasixDatabaseIdentity;
+    readonly terminalState: NativeHandleTerminalState;
+    private constructor();
+    static open(options: SerializedOpenOptions): Promise<NativeWasixSession>;
+    exec(input: Uint8Array, _persistence?: WasixPersistenceMode): Promise<Uint8Array>;
+    execStream(input: Uint8Array, onChunk: (chunk: Uint8Array) => void, _persistence?: WasixPersistenceMode): Promise<WasixProtocolStreamOutcome>;
+    sync(_boundary: WasixStorageSyncBoundary): Promise<void>;
+    backup(): Promise<Uint8Array>;
+    runPgDump(options: WasixPgDumpProcessOptions): Promise<WasixToolProcessResult>;
+    runTool(options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;
+    close(): Promise<void>;
+}
+/** @internal A Rust-owner actor whose Promise completions return to the importing realm. */
+export declare class NativeWasixActorSession implements WasixDatabaseSession {
+    #private;
+    readonly identity: WasixDatabaseIdentity;
+    readonly terminalState: NativeHandleTerminalState;
+    private constructor();
+    static open(options: SerializedOpenOptions): Promise<NativeWasixActorSession>;
+    exec(input: Uint8Array, _persistence?: WasixPersistenceMode): Promise<Uint8Array>;
+    execStream(input: Uint8Array, onChunk: (chunk: Uint8Array) => void, _persistence?: WasixPersistenceMode): Promise<WasixProtocolStreamOutcome>;
+    sync(_boundary: WasixStorageSyncBoundary): Promise<void>;
+    backup(): Promise<Uint8Array>;
+    runPgDump(options: WasixPgDumpProcessOptions): Promise<WasixToolProcessResult>;
+    runTool(options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;
+    close(): Promise<void>;
+}
+/** @internal Stable observation of a native owner which can retire below TypeScript. */
+declare class NativeHandleTerminalState implements WasixDatabaseSessionTerminalState {
+    #private;
+    constructor(isClosed: () => boolean, ownerLossMessage: string);
+    get terminal(): boolean;
+    get failure(): Error | undefined;
+    assertActive(): void;
+    beginOrderlyClose(): void;
+    recordFailure(error: unknown): void;
+}
+/** @internal Restore through the synchronous Rust archive validator. */
+export declare function restoreNativeWasix(options: SerializedOpenOptions, bytes: Uint8Array): Promise<void>;
+/** @internal Worker-side restore after the parent has validated package config. */
+export declare function restoreNativeWasixStorage(storage: SerializedOpenOptions['storage'], bytes: Uint8Array, addon?: NativeWasixAddon): Promise<void>;
+/** @internal Restore synchronously inside `/direct` or its dedicated Worker realm. */
+export declare function restoreNativeWasixDirect(options: SerializedOpenOptions, bytes: Uint8Array): Promise<void>;
+/** @internal Worker-side synchronous restore after the parent validates config. */
+export declare function restoreNativeWasixStorageDirect(storage: SerializedOpenOptions['storage'], bytes: Uint8Array, addon?: NativeWasixAddon): Promise<void>;
+/** @internal Validate serialized package descriptors against the selected addon. */
+export declare function requireCompatibleNativeWasixAddon(options: SerializedOpenOptions): NativeWasixAddon;
+/** @internal Project already-validated TS config onto the narrow native ABI. */
+export declare function nativeWasixOpenOptions(options: SerializedOpenOptions, storage: NativeWasixOpenOptions['storage']): NativeWasixOpenOptions;
+/** @internal Translate only the exact tagged native storage contract. */
+export declare function mapNativeError(error: unknown): unknown;
+export {};