@oliphaunt/wasix-ts 0.1.0

package/lib/storage/indexed-db-provider.js

@@ -0,0 +1,259 @@
+import { WasixStorageError } from '../errors.js';
+import { assertWasixPhysicalIdentity, physicalIdentityMatches, } from '../storage-provider.js';
+import { requireRecord, validateStoredSnapshot, } from '../storage-snapshot.js';
+import { acquireIncrementalStorage } from './incremental-storage.js';
+import { releaseRestoreLock } from './restore-cleanup.js';
+import { acquireExclusiveWebLock } from './web-lock.js';
+const DATABASE_PREFIX = '@oliphaunt/wasix-ts:indexed-db:v1:';
+const DATABASE_VERSION = 1;
+const METADATA_STORE = 'metadata';
+const ENTRY_STORE = 'entries';
+const METADATA_KEY = 'database';
+export async function acquireIndexedDbStorage(name, loadClusterSeed, identity) {
+    return acquireIndexedDbStorageWithBackend(name, loadClusterSeed, identity, browserBackend());
+}
+export async function restoreIndexedDbStorage(name, snapshot, identity) {
+    const lock = await acquireExclusiveWebLock(`@oliphaunt/wasix-ts:indexed-db:${name}`, `IndexedDB storage ${JSON.stringify(name)}`);
+    let database;
+    let failure;
+    let published = false;
+    try {
+        const factory = globalThis.indexedDB;
+        if (factory === undefined) {
+            throw new WasixStorageError('IndexedDB is unavailable in this @oliphaunt/wasix-ts host', {
+                code: 'unavailable',
+                commitState: 'unchanged',
+            });
+        }
+        database = await openStorageDatabase(factory, name);
+        if ((await readStoredDatabase(database, name)) !== undefined) {
+            throw new WasixStorageError(`IndexedDB storage ${JSON.stringify(name)} already exists`, {
+                code: 'incomplete',
+                commitState: 'unchanged',
+            });
+        }
+        await applyStoredDatabaseDelta(database, name, identity, {
+            directories: snapshot.directories,
+            files: snapshot.files,
+            deleted: [],
+        });
+        published = true;
+    }
+    catch (error) {
+        failure = error;
+    }
+    finally {
+        database?.close();
+        failure = await releaseRestoreLock(lock, `IndexedDB storage ${JSON.stringify(name)}`, published ? 'persisted' : 'unchanged', failure);
+    }
+    if (failure !== undefined)
+        throw failure;
+}
+/** @internal Narrow dependency seam for deterministic provider failure tests. */
+export async function acquireIndexedDbStorageWithBackend(name, loadClusterSeed, identity, backend) {
+    return acquireIncrementalStorage(`IndexedDB storage ${JSON.stringify(name)}`, loadClusterSeed, {
+        acquireLock: () => backend.acquireLock(name),
+        async openStore() {
+            const database = await backend.openDatabase(name);
+            return {
+                async read() {
+                    const stored = await database.read();
+                    return stored === undefined ? undefined : validateStoredDatabase(stored, name, identity);
+                },
+                apply: (delta) => database.apply(identity, delta),
+                close: () => database.close(),
+            };
+        },
+    });
+}
+function browserBackend() {
+    return {
+        acquireLock: (name) => acquireExclusiveWebLock(`@oliphaunt/wasix-ts:indexed-db:${name}`, `IndexedDB storage ${JSON.stringify(name)}`),
+        async openDatabase(name) {
+            const factory = globalThis.indexedDB;
+            if (factory === undefined) {
+                throw new WasixStorageError('IndexedDB is unavailable in this @oliphaunt/wasix-ts host', {
+                    code: 'unavailable',
+                    commitState: 'unchanged',
+                });
+            }
+            const database = await openStorageDatabase(factory, name);
+            return {
+                read: () => readStoredDatabase(database, name),
+                apply: (identity, delta) => applyStoredDatabaseDelta(database, name, identity, delta),
+                close: () => database.close(),
+            };
+        },
+    };
+}
+/** @internal Validate IndexedDB rows before any bytes reach Wasmer. */
+export function validateStoredDatabase(value, name, identity) {
+    let stored;
+    try {
+        stored = requireRecord(value, `IndexedDB storage ${JSON.stringify(name)}`);
+    }
+    catch (error) {
+        throw corrupt(name, `has a malformed database record: ${describeError(error)}`, error);
+    }
+    if (stored.schema !== 'oliphaunt-wasix-indexed-db-v1' || stored.name !== name) {
+        throw corrupt(name, 'has an unsupported or mismatched database record');
+    }
+    if (!hasExactKeys(stored, ['entries', 'name', 'physicalIdentity', 'schema'])) {
+        throw corrupt(name, 'has an unsupported or mismatched database record');
+    }
+    try {
+        if (!physicalIdentityMatches(stored.physicalIdentity, identity)) {
+            throw new WasixStorageError(`IndexedDB storage ${JSON.stringify(name)} is incompatible with the selected WASIX runtime`, { code: 'incompatible', commitState: 'unchanged' });
+        }
+    }
+    catch (error) {
+        if (error instanceof WasixStorageError)
+            throw error;
+        throw corrupt(name, `has malformed identity metadata: ${describeError(error)}`, error);
+    }
+    if (!Array.isArray(stored.entries))
+        throw corrupt(name, 'has malformed entry rows');
+    const directories = [];
+    const files = [];
+    for (const candidate of stored.entries) {
+        let entry;
+        try {
+            entry = requireRecord(candidate, `IndexedDB storage ${JSON.stringify(name)} entry`);
+        }
+        catch (error) {
+            throw corrupt(name, `contains a malformed entry row: ${describeError(error)}`, error);
+        }
+        if (typeof entry.path !== 'string')
+            throw corrupt(name, 'contains a mismatched entry row');
+        if (entry.type === 'dir') {
+            if (!hasExactKeys(entry, ['path', 'type'])) {
+                throw corrupt(name, `contains malformed entry ${JSON.stringify(entry.path)}`);
+            }
+            directories.push(entry.path);
+        }
+        else if (entry.type === 'file' && entry.bytes instanceof Uint8Array) {
+            if (!hasExactKeys(entry, ['bytes', 'path', 'type'])) {
+                throw corrupt(name, `contains malformed entry ${JSON.stringify(entry.path)}`);
+            }
+            files.push({ path: entry.path, bytes: entry.bytes });
+        }
+        else {
+            throw corrupt(name, `contains malformed entry ${JSON.stringify(entry.path)}`);
+        }
+    }
+    return validateStoredSnapshot({ schema: 'oliphaunt-wasix-directory-snapshot-v1', directories, files }, String(identity.postgresMajor), {
+        label: `IndexedDB storage ${JSON.stringify(name)}`,
+        corrupt: (detail, cause) => corrupt(name, detail, cause),
+    });
+}
+function hasExactKeys(value, expected) {
+    const keys = Object.keys(value).sort();
+    return keys.length === expected.length && keys.every((key, index) => key === expected[index]);
+}
+/** @internal Stable physical IndexedDB name for one logical Oliphaunt database. */
+export function indexedDbDatabaseName(name) {
+    return `${DATABASE_PREFIX}${name}`;
+}
+function openStorageDatabase(factory, name) {
+    return new Promise((resolve, reject) => {
+        const request = factory.open(indexedDbDatabaseName(name), DATABASE_VERSION);
+        let settled = false;
+        request.onupgradeneeded = () => {
+            const database = request.result;
+            if (!database.objectStoreNames.contains(METADATA_STORE)) {
+                database.createObjectStore(METADATA_STORE);
+            }
+            if (!database.objectStoreNames.contains(ENTRY_STORE)) {
+                database.createObjectStore(ENTRY_STORE, { keyPath: 'path' });
+            }
+        };
+        request.onerror = () => {
+            settled = true;
+            reject(request.error ?? new Error('IndexedDB open failed'));
+        };
+        request.onblocked = () => {
+            settled = true;
+            reject(new Error(`IndexedDB schema creation for ${JSON.stringify(name)} is blocked by another page`));
+        };
+        request.onsuccess = () => {
+            if (settled)
+                request.result.close();
+            else {
+                settled = true;
+                resolve(request.result);
+            }
+        };
+    });
+}
+export async function readStoredDatabase(database, name) {
+    const transaction = database.transaction([METADATA_STORE, ENTRY_STORE], 'readonly');
+    const complete = transactionComplete(transaction);
+    const metadataRequest = transaction.objectStore(METADATA_STORE).get(METADATA_KEY);
+    const entriesRequest = transaction.objectStore(ENTRY_STORE).getAll();
+    let metadata;
+    let entries;
+    try {
+        [metadata, entries] = await Promise.all([
+            requestValue(metadataRequest),
+            requestValue(entriesRequest),
+        ]);
+        await complete;
+    }
+    catch (error) {
+        // Observe the transaction promise even when an individual request fails;
+        // otherwise its later abort becomes an unhandled rejection in the host.
+        await complete.catch(() => undefined);
+        throw error;
+    }
+    if (metadata === undefined) {
+        if (entries.length > 0)
+            throw corrupt(name, 'contains entries without identity metadata');
+        return undefined;
+    }
+    return { ...metadata, entries: entries };
+}
+export async function applyStoredDatabaseDelta(database, name, identity, delta) {
+    const transaction = database.transaction([METADATA_STORE, ENTRY_STORE], 'readwrite');
+    transaction.objectStore(METADATA_STORE).put({
+        schema: 'oliphaunt-wasix-indexed-db-v1',
+        name,
+        physicalIdentity: assertWasixPhysicalIdentity(identity),
+    }, METADATA_KEY);
+    const entries = transaction.objectStore(ENTRY_STORE);
+    for (const path of delta.deleted)
+        entries.delete(path);
+    for (const path of delta.directories) {
+        entries.put({ path, type: 'dir' });
+    }
+    for (const { path, bytes } of delta.files) {
+        entries.put({
+            path,
+            type: 'file',
+            bytes,
+        });
+    }
+    await transactionComplete(transaction);
+}
+function requestValue(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+    });
+}
+function transactionComplete(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error ?? new Error('IndexedDB transaction failed'));
+        transaction.onabort = () => reject(transaction.error ?? new Error('IndexedDB transaction aborted'));
+    });
+}
+function corrupt(name, detail, cause) {
+    return new WasixStorageError(`IndexedDB storage ${JSON.stringify(name)} ${detail}`, {
+        code: 'corrupt',
+        commitState: 'unchanged',
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/storage/indexed-db.d.ts

@@ -0,0 +1,9 @@
+import { type PersistentWasixStorage } from '../storage.js';
+/**
+ * Select an origin-scoped persistent database.
+ *
+ * Every completed protocol operation commits only journaled PGDATA path
+ * changes in one atomic read-write IndexedDB transaction before its Promise resolves.
+ */
+export declare function indexedDB(name: string): PersistentWasixStorage;
+export default indexedDB;

package/lib/storage/indexed-db.js

@@ -0,0 +1,11 @@
+import { defineIndexedDbStorage } from '../storage.js';
+/**
+ * Select an origin-scoped persistent database.
+ *
+ * Every completed protocol operation commits only journaled PGDATA path
+ * changes in one atomic read-write IndexedDB transaction before its Promise resolves.
+ */
+export function indexedDB(name) {
+    return defineIndexedDbStorage(name);
+}
+export default indexedDB;

package/lib/storage/node.d.ts

@@ -0,0 +1,10 @@
+import { type PersistentWasixStorage } from '../storage.js';
+/**
+ * Persist a managed database below a Node.js host directory.
+ *
+ * Rust opens the selected managed root directly, owns its OS advisory lock,
+ * and performs PostgreSQL-safe durable writes at each native operation
+ * boundary. Network and cross-host shared filesystems are unsupported.
+ */
+export declare function directory(path: string | URL): PersistentWasixStorage;
+export default directory;

package/lib/storage/node.js

@@ -0,0 +1,13 @@
+import { fileURLToPath } from 'node:url';
+import { defineDirectoryStorage } from '../storage.js';
+/**
+ * Persist a managed database below a Node.js host directory.
+ *
+ * Rust opens the selected managed root directly, owns its OS advisory lock,
+ * and performs PostgreSQL-safe durable writes at each native operation
+ * boundary. Network and cross-host shared filesystems are unsupported.
+ */
+export function directory(path) {
+    return defineDirectoryStorage(typeof path === 'string' ? path : fileURLToPath(path));
+}
+export default directory;

package/lib/storage/opfs-pool.d.ts

@@ -0,0 +1,31 @@
+import { type WasixClusterSeedLoader, type WasixPhysicalIdentity, type WasixStorageSyncBoundary } from '../storage-provider.js';
+import { type StorageDelta, type StoredSnapshot } from '../storage-snapshot.js';
+export declare const OPFS_POOL_ROOT = ".oliphaunt-wasix-pool-v1";
+export type PooledOpfsDatabase = Readonly<{
+    snapshot: StoredSnapshot | undefined;
+    state: 'new' | 'existing';
+}>;
+type BridgeResult = [result: number, responseLength: number, value0: number, value1: number];
+/**
+ * A same-realm synchronous OPFS filesystem for the WASIX host.
+ *
+ * Logical PostgreSQL paths live in one atomic state file while relation bytes
+ * live in flat, pre-opened backing files. That deliberate opacity removes all
+ * asynchronous OPFS namespace calls from PostgreSQL's hot syscall path.
+ */
+export declare class DirectOpfsPool {
+    #private;
+    readonly state: 'new' | 'existing';
+    readonly request: (opcode: number, path: string, buffer: Uint8Array, arg0: number, arg1: number, flags: number) => BridgeResult;
+    private constructor();
+    static open(name: string, loadClusterSeed: WasixClusterSeedLoader, physicalIdentity: WasixPhysicalIdentity): Promise<DirectOpfsPool>;
+    sync(boundary: WasixStorageSyncBoundary): Promise<void>;
+    close(clean: boolean): Promise<void>;
+}
+export declare function inspectPooledOpfsDatabase(database: FileSystemDirectoryHandle, name: string, physicalIdentity: WasixPhysicalIdentity): Promise<PooledOpfsDatabase>;
+/** Reset only an unpublished first-open generation before portable hydration. */
+export declare function preparePooledOpfsDatabase(database: FileSystemDirectoryHandle, name: string, loadClusterSeed: WasixClusterSeedLoader, physicalIdentity: WasixPhysicalIdentity): Promise<PooledOpfsDatabase>;
+export declare function applyPooledOpfsDelta(database: FileSystemDirectoryHandle, name: string, physicalIdentity: WasixPhysicalIdentity, delta: StorageDelta): Promise<void>;
+export declare function openPooledDatabaseDirectory(name: string): Promise<FileSystemDirectoryHandle>;
+export declare function openPooledOpfsRoot(): Promise<FileSystemDirectoryHandle>;
+export {};