@lapis-notes/api 0.1.0

package/dist/storage/browser-coordinated-app-database.js

@@ -0,0 +1,704 @@
+import { BrowserAppDatabaseCoordinator } from "./browser-app-database-coordination";
+import { TursoWasmAppDatabaseProvider } from "./turso-app-database";
+const REQUEST_TIMEOUT_MS = 15_000;
+const LOCAL_RECOVERY_POLL_MS = 100;
+const MAX_RPC_ARGUMENTS = 4;
+const MAX_RPC_MESSAGE_BYTES = 32 * 1024 * 1024;
+const MAX_RPC_IDENTIFIER_LENGTH = 512;
+const APP_DATABASE_RPC_METHODS = new Set([
+    "describe",
+    "migrate",
+    "beginSearchIndexingBatch",
+    "endSearchIndexingBatch",
+    "configureSearchEmbeddingProvider",
+    "getSearchEmbeddingProvider",
+    "getSearchEmbeddingRuntimeStatus",
+    "getSearchIndexStats",
+    "getMeta",
+    "setMeta",
+    "getNotebookState",
+    "setNotebookState",
+    "deleteNotebookState",
+    "loadMetadataSnapshot",
+    "saveMetadataSnapshot",
+    "getFileHistory",
+    "storeFileHistoryRevision",
+    "listNotifications",
+    "upsertNotification",
+    "markNotificationRead",
+    "clearNotification",
+    "clearAllNotifications",
+    "getMemorySourceState",
+    "listMemorySourceStates",
+    "upsertMemorySourceState",
+    "deleteMemorySourceState",
+    "upsertMemoryCandidate",
+    "queryMemoryCandidates",
+    "deleteMemoryCandidatesByConversation",
+    "recordMemoryRecallSignal",
+    "listMemoryRecallSignals",
+    "claimMemoryJob",
+    "updateMemoryJob",
+    "listMemoryJobs",
+    "clearMemoryDerivedState",
+    "getChangeRevision",
+    "upsertIndexedFile",
+    "getIndexedFile",
+    "listIndexedFileManifest",
+    "deleteIndexedFile",
+    "renameIndexedFile",
+    "queryIndexedMetadata",
+    "queryIndexedMetadataPage",
+    "queryMetadataFacets",
+    "queryMetadataLinks",
+    "upsertSearchDocument",
+    "deleteSearchDocument",
+    "getSearchDocument",
+    "listSearchDocumentManifest",
+    "listSearchDocuments",
+    "rebuildSearchIndex",
+    "searchDocuments",
+    "searchDocumentPaths",
+    "upsertTaskProjection",
+    "deleteTaskProjection",
+    "queryTasks",
+    "getTaskRow",
+    "listChildLinks",
+    "listTaskDescendants",
+    "registerProjectionDefinition",
+    "unregisterProjectionDefinition",
+    "replaceProjectionSource",
+    "markProjectionSourceError",
+    "deleteProjectionSource",
+    "queryProjection",
+    "getProjectionRow",
+    "queryRelated",
+]);
+function isBoundedIdentifier(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_RPC_IDENTIFIER_LENGTH);
+}
+function isBoundedRpcMessage(message) {
+    try {
+        const serialized = JSON.stringify(message);
+        return (typeof serialized === "string" &&
+            new TextEncoder().encode(serialized).byteLength <= MAX_RPC_MESSAGE_BYTES);
+    }
+    catch {
+        return false;
+    }
+}
+function isRequestMessage(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        message.type === "db-request" &&
+        isBoundedIdentifier(message.vaultId) &&
+        isBoundedIdentifier(message.requesterId) &&
+        isBoundedIdentifier(message.requestId) &&
+        (message.ownerId === undefined ||
+            isBoundedIdentifier(message.ownerId)) &&
+        typeof message.method === "string" &&
+        APP_DATABASE_RPC_METHODS.has(message.method) &&
+        Array.isArray(message.args) &&
+        message.args.length <= MAX_RPC_ARGUMENTS &&
+        isBoundedRpcMessage(message));
+}
+function isResponseMessage(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        message.type === "db-response" &&
+        isBoundedIdentifier(message.vaultId) &&
+        isBoundedIdentifier(message.responderId) &&
+        isBoundedIdentifier(message.requesterId) &&
+        isBoundedIdentifier(message.requestId) &&
+        typeof message.success === "boolean" &&
+        isBoundedRpcMessage(message));
+}
+function isChangeMessage(message) {
+    const change = message?.change;
+    return (typeof message === "object" &&
+        message !== null &&
+        message.type === "db-change" &&
+        isBoundedIdentifier(message.vaultId) &&
+        isBoundedIdentifier(message.ownerId) &&
+        typeof change === "object" &&
+        change !== null &&
+        Number.isSafeInteger(change.revision) &&
+        change.revision >= 0 &&
+        Array.isArray(change.domains) &&
+        Array.isArray(change.paths) &&
+        isBoundedRpcMessage(message));
+}
+function createRequestId() {
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return `req-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+export class BrowserCoordinatedAppDatabase {
+    vaultId;
+    coordinator;
+    startsOwned;
+    provider;
+    get kind() {
+        return this.localDatabase?.kind ?? "turso-wasm";
+    }
+    get descriptor() {
+        if (this.localDatabase)
+            return this.localDatabase.descriptor;
+        if (this.remoteDescriptor) {
+            return {
+                ...this.remoteDescriptor,
+                transport: "broadcast-proxy",
+                role: "proxy",
+                capabilities: {
+                    ...this.remoteDescriptor.capabilities,
+                    crossTabCoordination: true,
+                },
+            };
+        }
+        return {
+            providerId: this.provider.id,
+            engine: "turso",
+            transport: "broadcast-proxy",
+            role: "proxy",
+            storageMode: "local",
+            capabilities: {
+                nativeFullTextSearch: false,
+                vectorSearch: false,
+                approximateNearestNeighbors: false,
+                localEmbeddings: true,
+                crossTabCoordination: true,
+                sync: false,
+            },
+        };
+    }
+    localDatabase = null;
+    remoteDescriptor = null;
+    rpcChannel = null;
+    pendingRequests = new Map();
+    opened = false;
+    closed = false;
+    ownershipMonitorAbortController = null;
+    promotionPromise = null;
+    servingRequests = false;
+    coordinationModeListeners = new Set();
+    changeListeners = new Set();
+    localChangeUnsubscribe = null;
+    lastSeenRevision = 0;
+    constructor(vaultId, coordinator, startsOwned, provider = new TursoWasmAppDatabaseProvider()) {
+        this.vaultId = vaultId;
+        this.coordinator = coordinator;
+        this.startsOwned = startsOwned;
+        this.provider = provider;
+    }
+    get coordinationMode() {
+        return this.startsOwned || this.localDatabase
+            ? "turso-owner"
+            : "turso-proxy";
+    }
+    onCoordinationModeChange(listener) {
+        this.coordinationModeListeners.add(listener);
+        return () => {
+            this.coordinationModeListeners.delete(listener);
+        };
+    }
+    async open() {
+        if (this.opened) {
+            return;
+        }
+        this.opened = true;
+        this.ensureRpcChannel();
+        if (this.startsOwned) {
+            await this.promoteToOwner();
+            return;
+        }
+        this.startOwnershipMonitor();
+        this.remoteDescriptor = await this.invokeRemote("describe", []);
+    }
+    async migrate() {
+        await this.invoke("migrate");
+    }
+    async close() {
+        this.closed = true;
+        this.ownershipMonitorAbortController?.abort();
+        this.ownershipMonitorAbortController = null;
+        this.pendingRequests.forEach(({ reject, timeoutId }) => {
+            clearTimeout(timeoutId);
+            reject(new Error("Coordinated app database closed"));
+        });
+        this.pendingRequests.clear();
+        try {
+            await this.localDatabase?.close();
+        }
+        finally {
+            this.localChangeUnsubscribe?.();
+            this.localChangeUnsubscribe = null;
+            this.changeListeners.clear();
+            this.localDatabase = null;
+            this.rpcChannel?.close();
+            this.rpcChannel = null;
+            if (!this.startsOwned) {
+                this.coordinator.close();
+            }
+        }
+    }
+    async beginSearchIndexingBatch() {
+        await this.invoke("beginSearchIndexingBatch");
+    }
+    async endSearchIndexingBatch() {
+        await this.invoke("endSearchIndexingBatch");
+    }
+    async configureSearchEmbeddingProvider(provider) {
+        await this.invoke("configureSearchEmbeddingProvider", provider);
+    }
+    async getSearchEmbeddingProvider() {
+        return this.invoke("getSearchEmbeddingProvider");
+    }
+    async getSearchEmbeddingRuntimeStatus() {
+        return this.invoke("getSearchEmbeddingRuntimeStatus");
+    }
+    async getSearchIndexStats() {
+        return this.invoke("getSearchIndexStats");
+    }
+    async getMeta(key) {
+        return this.invoke("getMeta", key);
+    }
+    async setMeta(key, value) {
+        await this.invoke("setMeta", key, value);
+    }
+    async getNotebookState(sourcePath) {
+        return this.invoke("getNotebookState", sourcePath);
+    }
+    async setNotebookState(sourcePath, state) {
+        await this.invoke("setNotebookState", sourcePath, state);
+    }
+    async deleteNotebookState(sourcePath) {
+        await this.invoke("deleteNotebookState", sourcePath);
+    }
+    async loadMetadataSnapshot() {
+        return this.invoke("loadMetadataSnapshot");
+    }
+    async saveMetadataSnapshot(snapshot) {
+        await this.invoke("saveMetadataSnapshot", snapshot);
+    }
+    async getFileHistory(path) {
+        return this.invoke("getFileHistory", path);
+    }
+    async storeFileHistoryRevision(input) {
+        return this.invoke("storeFileHistoryRevision", input);
+    }
+    async listNotifications() {
+        return this.invoke("listNotifications");
+    }
+    async upsertNotification(record) {
+        await this.invoke("upsertNotification", record);
+    }
+    async markNotificationRead(id) {
+        await this.invoke("markNotificationRead", id);
+    }
+    async clearNotification(id) {
+        await this.invoke("clearNotification", id);
+    }
+    async clearAllNotifications() {
+        await this.invoke("clearAllNotifications");
+    }
+    async getMemorySourceState(sourceKey) {
+        return this.invoke("getMemorySourceState", sourceKey);
+    }
+    async listMemorySourceStates() {
+        return this.invoke("listMemorySourceStates");
+    }
+    async upsertMemorySourceState(record) {
+        await this.invoke("upsertMemorySourceState", record);
+    }
+    async deleteMemorySourceState(sourceKey) {
+        await this.invoke("deleteMemorySourceState", sourceKey);
+    }
+    async upsertMemoryCandidate(input) {
+        await this.invoke("upsertMemoryCandidate", input);
+    }
+    async queryMemoryCandidates(query) {
+        return this.invoke("queryMemoryCandidates", query);
+    }
+    async deleteMemoryCandidatesByConversation(conversationId) {
+        await this.invoke("deleteMemoryCandidatesByConversation", conversationId);
+    }
+    async recordMemoryRecallSignal(record) {
+        await this.invoke("recordMemoryRecallSignal", record);
+    }
+    async listMemoryRecallSignals(targetRef) {
+        return this.invoke("listMemoryRecallSignals", targetRef);
+    }
+    async claimMemoryJob(input) {
+        return this.invoke("claimMemoryJob", input);
+    }
+    async updateMemoryJob(input) {
+        return this.invoke("updateMemoryJob", input);
+    }
+    async listMemoryJobs(scopeKey) {
+        return this.invoke("listMemoryJobs", scopeKey);
+    }
+    async clearMemoryDerivedState() {
+        await this.invoke("clearMemoryDerivedState");
+    }
+    async getChangeRevision() {
+        const revision = await this.invoke("getChangeRevision");
+        this.lastSeenRevision = Math.max(this.lastSeenRevision, revision);
+        return revision;
+    }
+    subscribeToChanges(listener) {
+        this.changeListeners.add(listener);
+        return () => this.changeListeners.delete(listener);
+    }
+    async upsertIndexedFile(record) {
+        await this.invoke("upsertIndexedFile", record);
+    }
+    async getIndexedFile(path) {
+        return this.invoke("getIndexedFile", path);
+    }
+    async listIndexedFileManifest(query) {
+        return this.invoke("listIndexedFileManifest", query);
+    }
+    async deleteIndexedFile(path) {
+        await this.invoke("deleteIndexedFile", path);
+    }
+    async renameIndexedFile(oldPath, newPath) {
+        await this.invoke("renameIndexedFile", oldPath, newPath);
+    }
+    async queryIndexedMetadata(query = {}) {
+        return this.invoke("queryIndexedMetadata", query);
+    }
+    async queryIndexedMetadataPage(query) {
+        return this.invoke("queryIndexedMetadataPage", query);
+    }
+    async queryMetadataFacets(query) {
+        return this.invoke("queryMetadataFacets", query);
+    }
+    async queryMetadataLinks(query) {
+        return this.invoke("queryMetadataLinks", query);
+    }
+    async upsertSearchDocument(document) {
+        await this.invoke("upsertSearchDocument", document);
+    }
+    async deleteSearchDocument(path) {
+        await this.invoke("deleteSearchDocument", path);
+    }
+    async getSearchDocument(path) {
+        return this.invoke("getSearchDocument", path);
+    }
+    async listSearchDocumentManifest(query) {
+        return this.invoke("listSearchDocumentManifest", query);
+    }
+    async listSearchDocuments() {
+        return this.invoke("listSearchDocuments");
+    }
+    async rebuildSearchIndex() {
+        await this.invoke("rebuildSearchIndex");
+    }
+    async searchDocuments(query, options) {
+        return this.invoke("searchDocuments", query, options);
+    }
+    async searchDocumentPaths(query, options) {
+        return this.invoke("searchDocumentPaths", query, options);
+    }
+    async upsertTaskProjection(record) {
+        await this.invoke("upsertTaskProjection", record);
+    }
+    async deleteTaskProjection(path) {
+        await this.invoke("deleteTaskProjection", path);
+    }
+    async queryTasks(query) {
+        return this.invoke("queryTasks", query);
+    }
+    async getTaskRow(lookup) {
+        return this.invoke("getTaskRow", lookup);
+    }
+    async listChildLinks(query) {
+        return this.invoke("listChildLinks", query);
+    }
+    async listTaskDescendants(path) {
+        return this.invoke("listTaskDescendants", path);
+    }
+    async registerProjectionDefinition(definition) {
+        await this.invoke("registerProjectionDefinition", definition);
+    }
+    async unregisterProjectionDefinition(projectionId) {
+        await this.invoke("unregisterProjectionDefinition", projectionId);
+    }
+    async replaceProjectionSource(input) {
+        await this.invoke("replaceProjectionSource", input);
+    }
+    async markProjectionSourceError(input) {
+        await this.invoke("markProjectionSourceError", input);
+    }
+    async deleteProjectionSource(projectionId, sourcePath, writerPluginId) {
+        await this.invoke("deleteProjectionSource", projectionId, sourcePath, writerPluginId);
+    }
+    async queryProjection(projectionId, query, readerPluginId) {
+        return this.invoke("queryProjection", projectionId, query, readerPluginId);
+    }
+    async getProjectionRow(projectionId, rowId, readerPluginId) {
+        return this.invoke("getProjectionRow", projectionId, rowId, readerPluginId);
+    }
+    async queryRelated(query, readerPluginId) {
+        return this.invoke("queryRelated", query, readerPluginId);
+    }
+    async invoke(method, ...args) {
+        if (!this.opened) {
+            await this.open();
+        }
+        if (this.localDatabase) {
+            return this.localDatabase[method](...args);
+        }
+        return this.invokeRemote(method, args);
+    }
+    ensureRpcChannel() {
+        if (this.rpcChannel || typeof BroadcastChannel === "undefined") {
+            return;
+        }
+        this.rpcChannel = new BroadcastChannel(this.coordinator.rpcChannelName);
+        this.rpcChannel.addEventListener("message", (event) => {
+            const message = event.data;
+            if (!message ||
+                message.vaultId !== this.vaultId) {
+                return;
+            }
+            if (isResponseMessage(message)) {
+                if (message.requesterId !== this.coordinator.tabId) {
+                    return;
+                }
+                const pending = this.pendingRequests.get(message.requestId);
+                if (!pending) {
+                    return;
+                }
+                if (pending.expectedResponderId &&
+                    message.responderId !== pending.expectedResponderId) {
+                    return;
+                }
+                clearTimeout(pending.timeoutId);
+                this.pendingRequests.delete(message.requestId);
+                if (message.success) {
+                    pending.resolve(message.result);
+                }
+                else {
+                    pending.reject(new Error(message.error ?? "Remote app database request failed"));
+                }
+                return;
+            }
+            if (isChangeMessage(message)) {
+                if (!this.localDatabase && message.ownerId === this.coordinator.observedOwnerId) {
+                    this.acceptChange(message.change);
+                }
+                return;
+            }
+            if (!isRequestMessage(message)) {
+                return;
+            }
+            if (!this.localDatabase || !this.servingRequests) {
+                return;
+            }
+            if (message.ownerId && message.ownerId !== this.coordinator.ownerId) {
+                return;
+            }
+            void this.handleRemoteRequest(message);
+        });
+    }
+    async invokeRemote(method, args) {
+        if (!this.rpcChannel) {
+            throw new Error("BroadcastChannel is unavailable for app database delegation");
+        }
+        const requestId = createRequestId();
+        const message = {
+            type: "db-request",
+            vaultId: this.vaultId,
+            ownerId: this.coordinator.observedOwnerId ?? undefined,
+            requesterId: this.coordinator.tabId,
+            requestId,
+            method,
+            args,
+        };
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let recovering = false;
+            const settleResolve = (value) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeoutId);
+                clearInterval(recoveryIntervalId);
+                this.pendingRequests.delete(requestId);
+                resolve(value);
+            };
+            const settleReject = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeoutId);
+                clearInterval(recoveryIntervalId);
+                this.pendingRequests.delete(requestId);
+                reject(error);
+            };
+            const timeoutId = setTimeout(() => {
+                settleReject(new Error(`Remote app database request timed out: ${method}`));
+            }, REQUEST_TIMEOUT_MS);
+            const tryRecoverLocally = async () => {
+                if (settled || recovering || !this.localDatabase) {
+                    return;
+                }
+                recovering = true;
+                try {
+                    const result = method === "describe"
+                        ? this.localDatabase.descriptor
+                        : await this.localDatabase[method](...args);
+                    settleResolve(result);
+                }
+                catch (error) {
+                    settleReject(error instanceof Error ? error : new Error(String(error)));
+                }
+                finally {
+                    recovering = false;
+                }
+            };
+            const recoveryIntervalId = setInterval(() => {
+                void tryRecoverLocally();
+            }, LOCAL_RECOVERY_POLL_MS);
+            this.pendingRequests.set(requestId, {
+                resolve: (value) => settleResolve(value),
+                reject: settleReject,
+                timeoutId,
+                expectedResponderId: message.ownerId,
+            });
+            this.rpcChannel.postMessage(message);
+            void tryRecoverLocally();
+        });
+    }
+    async handleRemoteRequest(message) {
+        let response;
+        try {
+            const result = message.method === "describe"
+                ? this.localDatabase.descriptor
+                : await this.localDatabase[message.method](...message.args);
+            response = {
+                type: "db-response",
+                vaultId: this.vaultId,
+                responderId: this.coordinator.ownerId,
+                requesterId: message.requesterId,
+                requestId: message.requestId,
+                success: true,
+                result,
+            };
+        }
+        catch (error) {
+            response = {
+                type: "db-response",
+                vaultId: this.vaultId,
+                responderId: this.coordinator.ownerId,
+                requesterId: message.requesterId,
+                requestId: message.requestId,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (!isBoundedRpcMessage(response)) {
+            response = {
+                type: "db-response",
+                vaultId: this.vaultId,
+                responderId: this.coordinator.ownerId,
+                requesterId: message.requesterId,
+                requestId: message.requestId,
+                success: false,
+                error: "App database response exceeded the cross-tab payload limit",
+            };
+        }
+        this.rpcChannel?.postMessage(response);
+    }
+    startOwnershipMonitor() {
+        if (this.ownershipMonitorAbortController || this.closed) {
+            return;
+        }
+        this.ownershipMonitorAbortController = new AbortController();
+        void this.coordinator
+            .waitForOwnership({ signal: this.ownershipMonitorAbortController.signal })
+            .then((acquired) => {
+            if (!acquired || this.closed) {
+                return;
+            }
+            return this.promoteToOwner();
+        })
+            .catch(() => {
+            // Request callers surface operational failures. The monitor only promotes ownership.
+        });
+    }
+    async promoteToOwner() {
+        if (this.localDatabase) {
+            this.servingRequests = true;
+            return;
+        }
+        if (this.promotionPromise) {
+            await this.promotionPromise;
+            return;
+        }
+        this.promotionPromise = (async () => {
+            const previousMode = this.coordinationMode;
+            const database = await this.openLocalDatabase();
+            this.localDatabase = database;
+            this.localChangeUnsubscribe = database.subscribeToChanges((change) => {
+                this.acceptChange(change);
+                this.rpcChannel?.postMessage({
+                    type: "db-change",
+                    vaultId: this.vaultId,
+                    ownerId: this.coordinator.ownerId,
+                    change,
+                });
+            });
+            this.startsOwned = true;
+            this.coordinator.startHeartbeat();
+            this.servingRequests = true;
+            if (previousMode !== this.coordinationMode) {
+                this.notifyCoordinationModeChange();
+            }
+            const revision = await database.getChangeRevision();
+            this.acceptChange({
+                revision,
+                domains: ["metadata", "search", "history", "notification", "notebook", "task", "projection", "meta"],
+                paths: [],
+                reset: true,
+                committedAt: Date.now(),
+            });
+        })();
+        try {
+            await this.promotionPromise;
+        }
+        finally {
+            this.promotionPromise = null;
+        }
+    }
+    async openLocalDatabase() {
+        return this.provider.open({
+            vaultId: this.vaultId,
+            runtime: "web-pwa",
+            role: "owner",
+        });
+    }
+    notifyCoordinationModeChange() {
+        const mode = this.coordinationMode;
+        for (const listener of this.coordinationModeListeners) {
+            listener(mode);
+        }
+    }
+    acceptChange(change) {
+        if (!change.reset && change.revision <= this.lastSeenRevision)
+            return;
+        const next = !change.reset && this.lastSeenRevision > 0 && change.revision !== this.lastSeenRevision + 1
+            ? { ...change, reset: true, paths: [] }
+            : change;
+        this.lastSeenRevision = Math.max(this.lastSeenRevision, change.revision);
+        for (const listener of this.changeListeners)
+            listener(structuredClone(next));
+    }
+}