@oliphaunt/wasix-ts 0.1.0

package/lib/descriptor-validation.d.ts

@@ -0,0 +1,10 @@
+import type { SerializedAssetSource } from './rpc.js';
+import type { WasixAssetSource } from './types.js';
+export declare function requireExactObject(value: unknown, fields: readonly string[], label: string): Record<string, unknown>;
+export declare function requireString(value: unknown, label: string): string;
+export declare function requireVersion(value: unknown, label: string): string;
+export declare function requireSha256(value: unknown, label: string): string;
+export declare function requireSize(value: unknown, label: string): number;
+export declare function requireAssetSource(value: unknown, label: string, size: number, sizeKind?: 'asset' | 'carrier'): WasixAssetSource;
+export declare function serializeAssetSource(source: WasixAssetSource): SerializedAssetSource;
+export declare function requireSafeRelativeAssetPath(value: unknown, label: string): string;

package/lib/descriptor-validation.js

@@ -0,0 +1,75 @@
+const SHA256 = /^[a-f0-9]{64}$/;
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export function requireExactObject(value, fields, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    const actual = Object.keys(value).sort();
+    if (actual.length !== fields.length || actual.some((field, index) => field !== fields[index])) {
+        throw new Error(`${label} fields must be exactly ${fields.join(', ')}`);
+    }
+    return value;
+}
+export function requireString(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\0')) {
+        throw new Error(`${label} must be a non-empty string without NUL bytes`);
+    }
+    return value;
+}
+export function requireVersion(value, label) {
+    const version = requireString(value, label);
+    if (!SEMVER.test(version)) {
+        throw new Error(`${label} must be a SemVer version`);
+    }
+    return version;
+}
+export function requireSha256(value, label) {
+    const sha256 = requireString(value, label);
+    if (!SHA256.test(sha256)) {
+        throw new Error(`${label} must be 64 lowercase hexadecimal characters`);
+    }
+    return sha256;
+}
+export function requireSize(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive safe integer`);
+    }
+    return value;
+}
+export function requireAssetSource(value, label, size, sizeKind = 'asset') {
+    if (typeof value === 'string') {
+        return requireString(value, label);
+    }
+    if (value instanceof URL) {
+        return value;
+    }
+    if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+        if (value.byteLength !== size) {
+            throw new Error(`${label} byte length must match declared ${sizeKind} size ${size}`);
+        }
+        return value;
+    }
+    throw new Error(`${label} must be a URL, string, ArrayBuffer, or Uint8Array`);
+}
+export function serializeAssetSource(source) {
+    if (typeof source === 'string') {
+        return source;
+    }
+    if (source instanceof URL) {
+        return source.href;
+    }
+    if (source instanceof Uint8Array) {
+        return source.slice();
+    }
+    return new Uint8Array(source.slice(0));
+}
+export function requireSafeRelativeAssetPath(value, label) {
+    const path = requireString(value, label);
+    const segments = path.split('/');
+    if (path.startsWith('/') ||
+        path.includes('\\') ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`${label} must be a safe relative asset path`);
+    }
+    return path;
+}

package/lib/direct-client-common.d.ts

@@ -0,0 +1,50 @@
+import { type WasixDatabaseIdentity, type WasixDatabaseSession, type WasixPersistenceMode, type WasixProtocolStreamOutcome, type WasixProtocolConnectionMode } from './database.js';
+import { type PreparedWasixRuntime } from './extensions.js';
+import type { Directory, OliphauntDirectInstance, OliphauntPreparedTool, OliphauntToolOutput, RunWasixOptions, WasmerInitOptions } from './host/index.mjs';
+import type { SerializedOpenOptions } from './rpc.js';
+import { type WasixClusterSeedLoader, type WasixStorageLease, type WasixStorageSyncBoundary } from './storage-provider.js';
+import type { OliphauntDatabase } from './types.js';
+import { type WasixProtocolConnection } from './pgwire-connection.js';
+import { type WasixPgDumpProcessOptions, type WasixToolProcessResult } from './tool-runtime.js';
+/** @internal Narrow caller-realm host contract. */
+export type DirectWasixHost = Readonly<{
+    Directory: typeof Directory;
+    init(options?: WasmerInitOptions): Promise<unknown>;
+    instantiateOliphauntDirect(module: WebAssembly.Module, moduleBytes: Uint8Array, options: RunWasixOptions): Promise<OliphauntDirectInstance>;
+    prepareOliphauntTool?(module: WebAssembly.Module, moduleBytes: Uint8Array): OliphauntPreparedTool;
+    runOliphauntToolDirect?(prepared: OliphauntPreparedTool, options: RunWasixOptions, protocolRead: (maximumBytes: number) => Uint8Array, 
+    /** Borrowed bytes: synchronously copy; never mutate or retain this view. */
+    protocolWrite: (chunk: Uint8Array) => void): Promise<OliphauntToolOutput>;
+}>;
+/** @internal Dependency seam for deterministic direct-lifecycle qualification. */
+export type DirectWasixDependencies = Readonly<{
+    prepareRuntime(options: SerializedOpenOptions): Promise<PreparedWasixRuntime>;
+    acquireStorage(storage: SerializedOpenOptions['storage'], loadClusterSeed: WasixClusterSeedLoader, identity: PreparedWasixRuntime['physicalIdentity']): Promise<WasixStorageLease>;
+    compileModule(module: Uint8Array, sha256: string): Promise<WebAssembly.Module>;
+}>;
+export type DirectWasixEnvironment = 'browser-main' | 'browser-worker' | 'node';
+/** @internal Open PostgreSQL in the caller realm; guest calls are synchronous after setup. */
+export declare function openWasixDirect(options: SerializedOpenOptions, host: DirectWasixHost, environment?: DirectWasixEnvironment): Promise<OliphauntDatabase>;
+/** @internal Open a direct-memory session inside the dedicated browser worker realm. */
+export declare function openBrowserWorkerSession(options: SerializedOpenOptions, host: DirectWasixHost): Promise<DirectWasixSession>;
+/**
+ * Owns the caller-realm guest, its mounted PGDATA, and one terminal teardown.
+ * A rejected close still retires the session after attempting provider and
+ * allocation release; destroyed guest state is never advertised as reusable.
+ */
+/** @internal */
+export declare class DirectWasixSession implements WasixDatabaseSession {
+    #private;
+    readonly identity: WasixDatabaseIdentity;
+    private constructor();
+    static open(options: SerializedOpenOptions, host: DirectWasixHost, dependencies?: DirectWasixDependencies, environment?: DirectWasixEnvironment): Promise<DirectWasixSession>;
+    exec(input: Uint8Array, persistence?: WasixPersistenceMode): Promise<Uint8Array>;
+    execStream(input: Uint8Array, onChunk: (chunk: Uint8Array) => void, persistence?: WasixPersistenceMode): Promise<WasixProtocolStreamOutcome>;
+    runPgDump(options: WasixPgDumpProcessOptions): Promise<WasixToolProcessResult>;
+    serve(connection: WasixProtocolConnection, mode: WasixProtocolConnectionMode): Promise<void>;
+    sync(boundary: WasixStorageSyncBoundary): Promise<void>;
+    backup(): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+/** @internal Cache verified runtime materialization without caching transient failures. */
+export declare function prepareRuntimeCached(options: SerializedOpenOptions, prepare?: (options: SerializedOpenOptions) => Promise<PreparedWasixRuntime>): Promise<PreparedWasixRuntime>;