@lix-js/sdk 0.12.3 → 0.14.0

package/dist/worker/client.js

@@ -1,30 +1,109 @@
 import { createWorkerConnection, openDirectLixBinding } from "#worker-factory";
-import { deserializeWorkerError, } from "./protocol.js";
+import { ownedSnapshotRestoreChunks } from "../snapshot-restore.js";
+import { deserializeWorkerError, serializeWorkerError, } from "./protocol.js";
 const MAX_IDLE_WORKERS = 1;
 // The common serial reopen path retains one worker so its prepared plugin cache
 // survives close(). Concurrent opens still receive isolated workers.
 const idleWorkers = [];
-export async function openLixWorker(storage, onDisposed, telemetry) {
+export async function openLixWorker(storage, onDisposed, telemetry, server, onProgress, snapshot) {
     let client = idleWorkers.pop();
     while (client?.isDisposed)
         client = idleWorkers.pop();
     client ??= new LixWorkerClient();
-    client.beginLease(onDisposed, telemetry);
+    client.beginLease(onDisposed, telemetry, server, onProgress);
+    let snapshotReader;
+    let snapshotPumpStarted = false;
     try {
-        await client.request({
+        // Lock the source before telling the worker to start a restore. A locked or
+        // otherwise unusable stream therefore cannot leave a worker open pending input.
+        snapshotReader = snapshot?.getReader();
+        const snapshotId = snapshotReader
+            ? client.allocateSnapshotInputId()
+            : undefined;
+        const open = client.request({
             kind: "open",
             storage,
             telemetryEnabled: telemetry !== undefined,
-        });
+            progressEnabled: onProgress !== undefined,
+            snapshotId,
+            server: serializeSyncServer(server),
+        }, 0);
+        if (snapshotReader && snapshotId !== undefined) {
+            snapshotPumpStarted = true;
+            await pumpSnapshotToWorker(client, snapshotReader, snapshotId, open);
+        }
+        client.openReport = await open;
         return client;
     }
     catch (error) {
+        if (snapshotReader && !snapshotPumpStarted) {
+            await snapshotReader.cancel(error).catch(() => undefined);
+            snapshotReader.releaseLock();
+        }
         await client.terminate();
         throw error;
     }
 }
+export async function pumpSnapshotToWorker(client, reader, snapshotId, open) {
+    let producerError = false;
+    // Convert rejection into data immediately so an early worker-open failure is
+    // always observed, even while or after a source read is pending.
+    const openCompletion = open.then((value) => ({ kind: "open-complete", value }), (error) => ({ kind: "open-error", error }));
+    try {
+        while (true) {
+            const outcome = await Promise.race([
+                reader.read().then((result) => ({ kind: "source", result }), (error) => ({ kind: "source-error", error })),
+                openCompletion,
+            ]);
+            if (outcome.kind === "open-error")
+                throw outcome.error;
+            if (outcome.kind === "open-complete") {
+                // Success cannot normally precede EOF, but if a binding completes early,
+                // stop consuming the now-unneeded producer without reporting an error.
+                await reader.cancel().catch(() => undefined);
+                return;
+            }
+            if (outcome.kind === "source-error") {
+                producerError = true;
+                throw outcome.error;
+            }
+            const read = outcome.result;
+            if (read.done)
+                break;
+            if (!(read.value instanceof Uint8Array)) {
+                producerError = true;
+                throw new TypeError("snapshot stream chunks must be Uint8Array values");
+            }
+            for (const chunk of ownedSnapshotRestoreChunks(read.value)) {
+                await client.request({
+                    kind: "openSnapshot.write",
+                    snapshotId,
+                    chunk,
+                });
+            }
+        }
+        await client.request({ kind: "openSnapshot.finish", snapshotId });
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        client.notify({ kind: "openSnapshot.cancel", snapshotId });
+        try {
+            await open;
+        }
+        catch (openError) {
+            // Decoder errors are more useful than the restore-lane write/close
+            // rejection. Producer errors remain authoritative.
+            if (!producerError)
+                throw openError;
+        }
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 /** Opens the local worker transport behind the semantic Lix binding. */
-export async function openLixWorkerBinding(storage, onDisposed, telemetry) {
+export async function openLixWorkerBinding(storage, onDisposed, telemetry, server, onProgress, snapshot) {
     if (openDirectLixBinding) {
         const telemetryDispatch = telemetry
             ? (span) => {
@@ -36,47 +115,149 @@ export async function openLixWorkerBinding(storage, onDisposed, telemetry) {
                 }
             }
             : undefined;
-        const binding = await openDirectLixBinding(storage, telemetryDispatch);
+        const binding = await openDirectLixBinding(storage, telemetryDispatch, telemetry?.parentContext?.(), await resolveDirectSyncServer(server), onProgress, snapshot);
         if (binding) {
+            const operationAwareBinding = telemetry?.parentContext
+                ? wrapTelemetryParentBinding(binding, telemetry.parentContext)
+                : binding;
             if (!onDisposed)
-                return binding;
-            let disposed = false;
-            return new Proxy(binding, {
-                get(target, property, receiver) {
-                    if (property === "close") {
-                        return async () => {
-                            try {
-                                await target.close();
-                            }
-                            finally {
-                                if (!disposed) {
-                                    disposed = true;
-                                    onDisposed();
-                                }
-                            }
-                        };
-                    }
-                    const value = Reflect.get(target, property, receiver);
-                    return typeof value === "function" ? value.bind(target) : value;
-                }
-            });
+                return operationAwareBinding;
+            return wrapDirectBinding(operationAwareBinding, new BindingLease(onDisposed));
         }
     }
-    const client = await openLixWorker(storage, onDisposed, telemetry);
-    return workerBinding(client);
+    const client = await openLixWorker(storage, onDisposed, telemetry, server, onProgress, snapshot);
+    return workerBinding(client, new BindingLease(() => releaseWorker(client)), 0);
+}
+function wrapTelemetryParentBinding(binding, parentContext) {
+    const prepareOperation = () => binding.setTelemetryParent(parentContext());
+    return new Proxy(binding, {
+        get(target, property, receiver) {
+            if (property === "setTelemetryParent") {
+                return target.setTelemetryParent.bind(target);
+            }
+            if (property === "openAnotherSession") {
+                return async (options) => {
+                    prepareOperation();
+                    return wrapTelemetryParentBinding(await target.openAnotherSession(options), parentContext);
+                };
+            }
+            if (property === "observe") {
+                return async (sql, params) => {
+                    prepareOperation();
+                    return wrapTelemetryParentObserve(await target.observe(sql, params), parentContext);
+                };
+            }
+            if (property === "beginTransaction") {
+                return async () => {
+                    prepareOperation();
+                    return wrapTelemetryParentTransaction(await target.beginTransaction(), target, parentContext);
+                };
+            }
+            const value = Reflect.get(target, property, receiver);
+            if (typeof value !== "function")
+                return value;
+            return (...args) => {
+                prepareOperation();
+                return Reflect.apply(value, target, args);
+            };
+        },
+    });
+}
+function wrapTelemetryParentObserve(events, parentContext) {
+    return {
+        setTelemetryParent: (parent) => events.setTelemetryParent(parent),
+        next: () => {
+            events.setTelemetryParent(parentContext());
+            return events.next();
+        },
+        close: () => events.close(),
+    };
+}
+function wrapTelemetryParentTransaction(transaction, binding, parentContext) {
+    const prepareOperation = () => binding.setTelemetryParent(parentContext());
+    return {
+        execute: (sql, params, options) => {
+            prepareOperation();
+            return transaction.execute(sql, params, options);
+        },
+        commit: () => {
+            prepareOperation();
+            return transaction.commit();
+        },
+        rollback: () => {
+            prepareOperation();
+            return transaction.rollback();
+        },
+    };
+}
+/** @internal Exported only for worker lifecycle tests. */
+export class BindingLease {
+    releaseLast;
+    references = 1;
+    constructor(releaseLast) {
+        this.releaseLast = releaseLast;
+    }
+    retain() {
+        this.references += 1;
+    }
+    async release() {
+        this.references -= 1;
+        if (this.references === 0)
+            await this.releaseLast();
+    }
+}
+function wrapDirectBinding(binding, lease) {
+    let closed = false;
+    return new Proxy(binding, {
+        get(target, property, receiver) {
+            if (property === "openAnotherSession") {
+                return async (options) => {
+                    const opened = await target.openAnotherSession(options);
+                    lease.retain();
+                    return wrapDirectBinding(opened, lease);
+                };
+            }
+            if (property === "close") {
+                return async () => {
+                    if (closed)
+                        return;
+                    try {
+                        await target.close();
+                    }
+                    finally {
+                        closed = true;
+                        await lease.release();
+                    }
+                };
+            }
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
 }
-function workerBinding(client) {
+/** @internal Exported only for worker lifecycle tests. */
+export function workerBinding(client, lease, sessionId) {
     let closed = false;
     const request = (operation) => {
         if (closed)
             return Promise.reject(workerClosedError());
-        return client.request(operation);
+        return client.request(operation, sessionId);
     };
     const notify = (notification) => {
         if (!closed)
             client.notify(notification);
     };
     return {
+        openReport: () => client.openReport,
+        setTelemetryParent: () => { },
+        openAnotherSession: async (options) => {
+            const openedSessionId = await request({
+                kind: "openAnotherSession",
+                options,
+            });
+            lease.retain();
+            return workerBinding(client, lease, openedSessionId);
+        },
         execute: (sql, params, options) => request({ kind: "execute", sql, params, options }),
         executeBatch: (statements, options) => request({ kind: "executeBatch", statements, options }),
         observe: async (sql, params) => {
@@ -96,7 +277,6 @@ function workerBinding(client) {
         activeBranchId: () => request({ kind: "activeBranchId" }),
         activeAccountId: () => request({ kind: "activeAccountId" }),
         createBranch: (options) => request({ kind: "createBranch", options }),
-        createCheckpoint: () => request({ kind: "createCheckpoint" }),
         undo: () => request({ kind: "undo" }),
         redo: () => request({ kind: "redo" }),
         switchBranch: (options) => request({ kind: "switchBranch", options }),
@@ -104,12 +284,46 @@ function workerBinding(client) {
         mergeBranchPreview: (options) => request({ kind: "mergeBranchPreview", options }),
         mergeBranch: (options) => request({ kind: "mergeBranch", options }),
         syncDiskToLix: () => request({ kind: "syncDiskToLix" }),
+        exportSnapshot: () => {
+            const exportId = request({ kind: "exportSnapshot" });
+            let canceled = false;
+            return {
+                next: async () => {
+                    if (canceled)
+                        return undefined;
+                    return request({
+                        kind: "exportSnapshot.next",
+                        exportId: await exportId,
+                    });
+                },
+                cancel: async () => {
+                    if (canceled)
+                        return;
+                    canceled = true;
+                    await request({
+                        kind: "exportSnapshot.cancel",
+                        exportId: await exportId,
+                    });
+                },
+            };
+        },
         close: async () => {
             if (closed)
                 return;
-            await request({ kind: "close" });
-            closed = true;
-            await releaseWorker(client);
+            try {
+                await request({ kind: "close" });
+            }
+            catch (error) {
+                // A failed semantic close may leave the worker host retaining its OPFS
+                // session. Terminating the worker is the ownership backstop before an
+                // outer caller can safely release its cross-tab lock.
+                await client.terminate().catch(() => undefined);
+                throw error;
+            }
+            finally {
+                closed = true;
+                await lease.release();
+            }
         },
     };
 }
@@ -128,6 +342,7 @@ function workerTransactionBinding(request, transactionId) {
 }
 function workerObserveBinding(request, notify, observeId) {
     return {
+        setTelemetryParent: () => { },
         next: () => request({ kind: "observe.next", observeId }),
         close: () => notify({ kind: "observe.close", observeId }),
     };
@@ -143,11 +358,16 @@ async function releaseWorker(client) {
 export class LixWorkerClient {
     connection;
     nextRequestId = 1;
+    nextSnapshotInputId = 1;
     pending = new Map();
     disposed = false;
     leased = false;
     onDisposed;
     telemetry;
+    syncServer;
+    onProgress;
+    openReport;
+    syncFetchControllers = new Map();
     constructor(connection = createWorkerConnection()) {
         this.connection = connection;
         connection.onMessage((message) => this.handleMessage(message));
@@ -156,12 +376,17 @@ export class LixWorkerClient {
     get isDisposed() {
         return this.disposed;
     }
-    beginLease(onDisposed, telemetry) {
+    allocateSnapshotInputId() {
+        return this.nextSnapshotInputId++;
+    }
+    beginLease(onDisposed, telemetry, syncServer, onProgress) {
         if (this.disposed || this.leased)
             throw workerClosedError();
         this.leased = true;
         this.onDisposed = onDisposed;
         this.telemetry = telemetry;
+        this.syncServer = syncServer;
+        this.onProgress = onProgress;
     }
     endLease() {
         if (!this.leased)
@@ -170,9 +395,15 @@ export class LixWorkerClient {
         const onDisposed = this.onDisposed;
         this.onDisposed = undefined;
         this.telemetry = undefined;
+        this.syncServer = undefined;
+        this.onProgress = undefined;
+        this.openReport = undefined;
+        for (const controller of this.syncFetchControllers.values())
+            controller.abort();
+        this.syncFetchControllers.clear();
         onDisposed?.();
     }
-    request(operation) {
+    request(operation, sessionId = 0) {
         if (this.disposed || !this.leased) {
             return Promise.reject(workerClosedError());
         }
@@ -185,7 +416,12 @@ export class LixWorkerClient {
                 reject,
             });
             try {
-                this.connection.postMessage({ id, operation });
+                this.connection.postMessage({
+                    id,
+                    sessionId,
+                    telemetryParent: this.telemetry?.parentContext?.(),
+                    operation,
+                });
             }
             catch (error) {
                 this.pending.delete(id);
@@ -219,12 +455,7 @@ export class LixWorkerClient {
     }
     handleMessage(message) {
         if ("kind" in message) {
-            try {
-                this.telemetry?.onSpan(message.span);
-            }
-            catch {
-                // Telemetry callbacks are isolated from Lix operation results.
-            }
+            this.handleWorkerEvent(message);
             return;
         }
         const pending = this.pending.get(message.id);
@@ -238,6 +469,107 @@ export class LixWorkerClient {
         else
             pending.reject(deserializeWorkerError(message.error));
     }
+    handleWorkerEvent(message) {
+        switch (message.kind) {
+            case "telemetry":
+                try {
+                    this.telemetry?.onSpan(message.span);
+                }
+                catch {
+                    // Telemetry callbacks are isolated from Lix operation results.
+                }
+                break;
+            case "open.progress":
+                try {
+                    this.onProgress?.(message.progress);
+                }
+                catch {
+                    // Open progress is observational and cannot fail repository opening.
+                }
+                break;
+            case "sync.headers":
+                void this.resolveSyncHeaders(message.requestId);
+                break;
+            case "sync.fetch":
+                void this.resolveSyncFetch(message.requestId, message.request);
+                break;
+            case "sync.fetch.cancel":
+                this.syncFetchControllers.get(message.requestId)?.abort();
+                this.syncFetchControllers.delete(message.requestId);
+                break;
+        }
+    }
+    async resolveSyncHeaders(requestId) {
+        try {
+            const source = this.syncServer?.headers;
+            const headers = typeof source === "function" ? await source() : source;
+            this.notify({
+                kind: "sync.headers.result",
+                requestId,
+                result: { ok: true, headers: headerEntries(headers) },
+            });
+        }
+        catch (error) {
+            this.notify({
+                kind: "sync.headers.result",
+                requestId,
+                result: { ok: false, error: serializeWorkerError(error) },
+            });
+        }
+    }
+    async resolveSyncFetch(requestId, request) {
+        const fetcher = this.syncServer?.fetch;
+        if (!fetcher) {
+            this.notify({
+                kind: "sync.fetch.result",
+                requestId,
+                result: {
+                    ok: false,
+                    error: serializeWorkerError(new Error("Sync fetch bridge is unavailable")),
+                },
+            });
+            return;
+        }
+        const controller = new AbortController();
+        this.syncFetchControllers.set(requestId, controller);
+        try {
+            const response = await fetcher(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: typeof request.body === "string"
+                    ? request.body
+                    : request.body?.slice().buffer,
+                credentials: request.credentials,
+                signal: controller.signal,
+            });
+            const body = await readSyncResponseBody(response, request.responseLimit, controller);
+            this.notify({
+                kind: "sync.fetch.result",
+                requestId,
+                result: {
+                    ok: true,
+                    response: {
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers: headerEntries(response.headers),
+                        body,
+                    },
+                },
+            });
+        }
+        catch (error) {
+            if (!controller.signal.aborted || isSyncResponseTooLarge(error)) {
+                this.notify({
+                    kind: "sync.fetch.result",
+                    requestId,
+                    result: { ok: false, error: serializeWorkerError(error) },
+                });
+            }
+        }
+        finally {
+            this.syncFetchControllers.delete(requestId);
+        }
+    }
     handleFatal(error) {
         if (this.disposed)
             return;
@@ -255,9 +587,90 @@ export class LixWorkerClient {
         this.connection.unref();
     }
 }
+async function readSyncResponseBody(response, limit, controller) {
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        throw new TypeError("Browser sync fetch has no valid response limit");
+    }
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > limit) {
+        const error = syncResponseTooLarge(limit);
+        controller.abort(error);
+        throw error;
+    }
+    const stream = response.body;
+    if (!stream)
+        return new Uint8Array();
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > limit) {
+                const error = syncResponseTooLarge(limit);
+                controller.abort(error);
+                await reader.cancel(error).catch(() => undefined);
+                throw error;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+function syncResponseTooLarge(limit) {
+    const error = new Error(`sync fetch response exceeds ${limit} bytes`);
+    error.name = "LixError";
+    error.code = "LIX_ERROR_SYNC_RESPONSE_TOO_LARGE";
+    return error;
+}
+function isSyncResponseTooLarge(error) {
+    return (error instanceof Error &&
+        error.code ===
+            "LIX_ERROR_SYNC_RESPONSE_TOO_LARGE");
+}
 function workerClosedError() {
     const error = new Error("Lix worker is closed");
     error.name = "LixError";
     error.code = "LIX_ERROR_CLOSED";
     return error;
 }
+function serializeSyncServer(server) {
+    if (!server)
+        return undefined;
+    return {
+        url: new URL(server.url).toString(),
+        headers: typeof server.headers === "function"
+            ? undefined
+            : headerEntries(server.headers),
+        dynamicHeaders: typeof server.headers === "function",
+        customFetch: server.fetch !== undefined,
+    };
+}
+function headerEntries(headers) {
+    const entries = [];
+    new Headers(headers).forEach((value, name) => entries.push([name, value]));
+    return entries;
+}
+async function resolveDirectSyncServer(server) {
+    if (!server)
+        return undefined;
+    const source = server.headers;
+    const headers = typeof source === "function" ? await source() : source;
+    return {
+        url: new URL(server.url).toString(),
+        headers: headerEntries(headers),
+        fetch: server.fetch,
+    };
+}

package/dist/worker/factory.browser.d.ts

@@ -1,4 +1,4 @@
-import type { LixBinding, LixStorageConfig, TelemetryDispatch } from "../binding-types.js";
+import type { LixBinding, LixStorageConfig, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch, SyncServerBindingOptions } from "../binding-types.js";
 import type { WorkerConnection } from "./protocol.js";
-export declare const openDirectLixBinding: undefined | ((storage: LixStorageConfig, telemetry?: TelemetryDispatch) => Promise<LixBinding>);
+export declare const openDirectLixBinding: undefined | ((storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>) => Promise<LixBinding>);
 export declare function createWorkerConnection(): WorkerConnection;

package/dist/worker/factory.node.d.ts

@@ -1,5 +1,5 @@
-import type { LixBinding, LixStorageConfig, TelemetryDispatch } from "../binding-types.js";
+import type { LixBinding, LixStorageConfig, SyncServerBindingOptions, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch } from "../binding-types.js";
 import type { WorkerConnection } from "./protocol.js";
 export declare function createWorkerConnection(): WorkerConnection;
 export declare function workerExecArgv(execArgv: readonly string[]): string[];
-export declare const openDirectLixBinding: (storage: LixStorageConfig, telemetry?: TelemetryDispatch) => Promise<LixBinding | undefined>;
+export declare const openDirectLixBinding: (storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>) => Promise<LixBinding | undefined>;

package/dist/worker/factory.node.js

@@ -1,5 +1,5 @@
 import { Worker } from "node:worker_threads";
-import { openNativeLixBinding } from "../binding.node.js";
+import { openLixBinding } from "../binding.node.js";
 export function createWorkerConnection() {
     const worker = new Worker(new URL("./entry.node.js", import.meta.url), {
         name: "lix",
@@ -52,13 +52,6 @@ export function workerExecArgv(execArgv) {
 /// Native Lix already owns a dedicated serialized engine actor. Routing it
 /// through a second JavaScript worker adds two message-port hops per query
 /// without adding isolation or concurrency.
-export const openDirectLixBinding = async (storage, telemetry) => {
-    try {
-        return await openNativeLixBinding(storage, telemetry);
-    }
-    catch (error) {
-        if (storage.kind === "memory")
-            return undefined;
-        throw error;
-    }
+export const openDirectLixBinding = async (storage, telemetry, telemetryParent, server, openProgress, snapshot) => {
+    return openLixBinding(storage, telemetry, telemetryParent, server, openProgress, snapshot);
 };

package/dist/worker/host.d.ts

@@ -1,2 +1,3 @@
-import { type WorkerHostEndpoint } from "./protocol.js";
+import { type WorkerHostEndpoint, type WorkerSyncFetchResponse } from "./protocol.js";
 export declare function startWorkerHost(endpoint: WorkerHostEndpoint): void;
+export declare function responseFromSyncFetch(resolved: WorkerSyncFetchResponse): Response;