@opendatalabs/personal-server-ts-lite 1.34.2 → 1.35.0

package/dist/storage.js

@@ -1,6 +1,7 @@
 import { buildDataBlocksAsync } from "@opendatalabs/personal-server-ts-core/storage/blocks";
 import { DataBlockStorageError, encodeDataBlockCursor, selectScopeBlocksByIds, validateDataBlockCursor, } from "@opendatalabs/personal-server-ts-core/storage/blocks";
 import { withScopeLock } from "@opendatalabs/personal-server-ts-core/additions";
+import { IngestPersistedError, VersionSupersededError, } from "@opendatalabs/personal-server-ts-core/contracts";
 import { createStorageReadMethods, sortEntries } from "./storage-utils.js";
 import { previewEnvelopeValue, previewJsonEnvelopePrefix, } from "@opendatalabs/personal-server-ts-core/storage/preview";
 const DEFAULT_INDEXED_DB_NAME = "personal-server-lite-storage";
@@ -167,6 +168,39 @@ export async function createOpfsPsLiteDataFileStore() {
             await writable.close();
             return new TextEncoder().encode(encoded).length;
         },
+        async openEnvelopeWriter(path) {
+            const parts = path.split("/").filter(Boolean);
+            const fileName = parts.pop();
+            if (!fileName)
+                throw new Error("OPFS path must include a file name");
+            const dir = await getOrCreateOpfsDirectory(root, parts);
+            const handle = await dir.getFileHandle(fileName, { create: true });
+            // A writable stream writes to a swap file; `close` replaces the file in
+            // one step and `abort` drops the swap file.
+            const writable = await handle.createWritable();
+            let sizeBytes = 0;
+            let open = true;
+            return {
+                async write(text) {
+                    const bytes = textEncoder.encode(text);
+                    await writable.write(bytes);
+                    sizeBytes += bytes.byteLength;
+                },
+                async commit() {
+                    open = false;
+                    await writable.close();
+                    return sizeBytes;
+                },
+                async abort() {
+                    if (!open)
+                        return;
+                    open = false;
+                    await writable.abort();
+                    // `create: true` left an empty, unindexed file at the path.
+                    await dir.removeEntry(fileName).catch(() => undefined);
+                },
+            };
+        },
         async deleteEnvelope(path) {
             const parts = path.split("/").filter(Boolean);
             const fileName = parts.pop();
@@ -325,10 +359,18 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
         files: fileStore.kind,
         opfsAvailable: await isOpfsAvailable(),
     };
+    // Every write of the persisted state runs in this queue, one at a time, in
+    // call order. A snapshot is taken when its turn comes, so each write carries
+    // the latest index, and index changes never interleave.
     let persistQueue = Promise.resolve();
-    async function persist() {
-        const snapshot = {
-            ...state,
+    function enqueue(step) {
+        const run = persistQueue.then(step);
+        persistQueue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    function snapshotOf(source) {
+        return {
+            ...source,
             readyBlockManifests: Array.from(readyBlockManifests),
             envelopes: fileStore.kind === "indexeddb"
                 ? Array.from(fallbackEnvelopes.values())
@@ -339,9 +381,92 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
                 ? Array.from(pendingLedgerDeletes)
                 : undefined,
         };
-        const write = persistQueue.then(() => persistence.write(snapshot));
-        persistQueue = write.catch(() => undefined);
-        await write;
+    }
+    async function persist() {
+        await enqueue(() => persistence.write(snapshotOf(state)));
+    }
+    /**
+     * Make `next` the live index, once it is durable. Call only inside
+     * `enqueue`. A failed write leaves the live index as it was, so a reader
+     * never sees a change that could be lost on restart.
+     */
+    async function publish(next) {
+        await persistence.write(snapshotOf(next));
+        state = next;
+    }
+    /**
+     * Replace the live index with `change(index)`. `change` returns null to
+     * leave the index alone. Resolves to whether the index was written.
+     */
+    function updateIndex(change) {
+        return enqueue(async () => {
+            const next = change(state);
+            if (!next)
+                return false;
+            await publish(next);
+            return true;
+        });
+    }
+    function updateEntryField(path, patch) {
+        return updateIndex((current) => {
+            if (!current.entries.some((entry) => entry.path === path))
+                return null;
+            return {
+                ...current,
+                entries: current.entries.map((entry) => entry.path === path ? { ...entry, ...patch } : entry),
+            };
+        });
+    }
+    /**
+     * Remove a blob that no index entry names, after its index write failed. A
+     * blob that an entry does name is kept. Best effort: the commit's own error
+     * is what the caller sees.
+     */
+    function dropUnindexedEnvelope(path) {
+        return enqueue(async () => {
+            if (state.entries.some((entry) => entry.path === path))
+                return;
+            await Promise.all([
+                fileStore.deleteEnvelope(path),
+                fallbackStore.deleteEnvelope(path),
+            ]);
+        }).catch(() => undefined);
+    }
+    /**
+     * Install a row at its path, replacing any row there. Caller holds the path
+     * lock. With `onlyIfNewest`, the row is refused when the scope already has a
+     * later `collectedAt`; that check runs in the index queue, so it is atomic
+     * with the publication.
+     */
+    async function installEntry(entry, options = {}) {
+        let indexed;
+        await updateIndex((current) => {
+            if (options.onlyIfNewest &&
+                current.entries.some((e) => e.scope === entry.scope &&
+                    Date.parse(e.collectedAt) > Date.parse(entry.collectedAt))) {
+                throw new VersionSupersededError(entry.scope);
+            }
+            const version = entry.version ??
+                current.entries.reduce((max, e) => e.scope === entry.scope && e.version > max ? e.version : max, 0) + 1;
+            indexed = {
+                ...entry,
+                schemaId: entry.schemaId ?? null,
+                version,
+                dataPointId: entry.dataPointId ?? null,
+                afterTombstoneVersion: entry.afterTombstoneVersion ?? null,
+                id: current.nextId,
+                createdAt: new Date().toISOString(),
+            };
+            return {
+                ...current,
+                nextId: current.nextId + 1,
+                entries: [
+                    ...current.entries.filter((item) => item.path !== entry.path),
+                    indexed,
+                ],
+            };
+        });
+        return indexed;
     }
     function entriesForScope(scope) {
         return sortEntries(state.entries.filter((entry) => entry.scope === scope));
@@ -382,10 +507,13 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
         },
         async writeEnvelope(envelope) {
             const path = envelopePath(envelope.scope, envelope.collectedAt);
-            const sizeBytes = await fileStore.writeEnvelope(path, envelope);
-            if (fileStore.kind !== "indexeddb") {
-                await fallbackStore.deleteEnvelope(path);
-            }
+            const sizeBytes = await withPathLock(path, async () => {
+                const size = await fileStore.writeEnvelope(path, envelope);
+                if (fileStore.kind !== "indexeddb") {
+                    await fallbackStore.deleteEnvelope(path);
+                }
+                return size;
+            });
             await persist();
             return {
                 path,
@@ -393,6 +521,67 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
                 sizeBytes,
             };
         },
+        async writeEnvelopeAndIndex(envelope, entry) {
+            const path = envelopePath(envelope.scope, envelope.collectedAt);
+            // The blob and its row are one step under the path lock, so no erase or
+            // replacement of this path runs between them.
+            return withPathLock(path, async () => {
+                const size = await fileStore.writeEnvelope(path, envelope);
+                if (fileStore.kind !== "indexeddb") {
+                    await fallbackStore.deleteEnvelope(path);
+                }
+                try {
+                    return await installEntry({
+                        ...entry,
+                        scope: envelope.scope,
+                        collectedAt: envelope.collectedAt,
+                        path,
+                        sizeBytes: entry.sizeBytes ?? size,
+                    });
+                }
+                catch (error) {
+                    // The bytes are durable here; the caller's recovery depends on that.
+                    throw new IngestPersistedError(path, error);
+                }
+            });
+        },
+        ...(fileStore.openEnvelopeWriter
+            ? {
+                async openVersionWriter(scope, collectedAt) {
+                    const path = envelopePath(scope, collectedAt);
+                    const file = await fileStore.openEnvelopeWriter(path);
+                    return {
+                        write: (text) => file.write(text),
+                        abort: () => file.abort(),
+                        async commit(entry, options) {
+                            // The rename and the index install are one step under the path
+                            // lock, so no erase of this path runs between them.
+                            return withPathLock(path, async () => {
+                                const sizeBytes = await file.commit();
+                                try {
+                                    // The index entry is what makes the version visible.
+                                    await installEntry({
+                                        ...entry,
+                                        scope,
+                                        collectedAt,
+                                        path,
+                                        sizeBytes,
+                                    }, options);
+                                }
+                                catch (error) {
+                                    await dropUnindexedEnvelope(path);
+                                    throw error;
+                                }
+                                if (fileStore.kind !== "indexeddb") {
+                                    await fallbackStore.deleteEnvelope(path);
+                                }
+                                return { path, relativePath: path, sizeBytes };
+                            });
+                        },
+                    };
+                },
+            }
+            : {}),
         async readScopeBlocks(scope, collectedAt, options) {
             const manifestPath = blockManifestPath(scope, collectedAt);
             let manifest = (await fileStore.readBlockManifest?.(manifestPath)) ??
@@ -577,79 +766,20 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
             readyBlockManifests.add(blockManifestPath(scope, collectedAt));
             await persist();
         },
-        async insertEntry(entry) {
-            const version = entry.version ??
-                state.entries.reduce((max, e) => e.scope === entry.scope && e.version > max ? e.version : max, 0) + 1;
-            const indexed = {
-                ...entry,
-                schemaId: entry.schemaId ?? null,
-                version,
-                dataPointId: entry.dataPointId ?? null,
-                afterTombstoneVersion: entry.afterTombstoneVersion ?? null,
-                id: state.nextId,
-                createdAt: new Date().toISOString(),
-            };
-            state = {
-                ...state,
-                nextId: state.nextId + 1,
-                entries: [
-                    ...state.entries.filter((item) => item.path !== entry.path),
-                    indexed,
-                ],
-            };
-            await persist();
-            return indexed;
-        },
-        async updateFileId(path, fileId) {
-            let updated = false;
-            state = {
-                ...state,
-                entries: state.entries.map((entry) => {
-                    if (entry.path !== path)
-                        return entry;
-                    updated = true;
-                    return { ...entry, fileId };
-                }),
-            };
-            if (updated) {
-                await persist();
-            }
-            return updated;
+        insertEntry(entry) {
+            return withPathLock(entry.path, () => installEntry(entry));
+        },
+        updateFileId(path, fileId) {
+            return updateEntryField(path, { fileId });
         },
         findLatestVersionByScope(scope) {
             return state.entries.reduce((max, e) => (e.scope === scope && e.version > max ? e.version : max), 0);
         },
-        async updateDataPointId(path, dataPointId) {
-            let updated = false;
-            state = {
-                ...state,
-                entries: state.entries.map((entry) => {
-                    if (entry.path !== path)
-                        return entry;
-                    updated = true;
-                    return { ...entry, dataPointId };
-                }),
-            };
-            if (updated) {
-                await persist();
-            }
-            return updated;
-        },
-        async updateEntryVersion(path, version) {
-            let updated = false;
-            state = {
-                ...state,
-                entries: state.entries.map((entry) => {
-                    if (entry.path !== path)
-                        return entry;
-                    updated = true;
-                    return { ...entry, version };
-                }),
-            };
-            if (updated) {
-                await persist();
-            }
-            return updated;
+        updateDataPointId(path, dataPointId) {
+            return updateEntryField(path, { dataPointId });
+        },
+        updateEntryVersion(path, version) {
+            return updateEntryField(path, { version });
         },
         async readFirstSeenLedger(scope) {
             if (!firstSeenLedgers.has(scope)) {
@@ -667,56 +797,72 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
             firstSeenLedgers.delete(scope);
             await persistence.deleteAux?.(ledgerAux(scope));
         },
-        // Deletions run under the scope's first-seen sidecar lock (a rebuild in
-        // flight cannot write it back), and the sidecar goes with the scope's last
-        // version, so no delete path leaves a stale ledger behind.
-        deleteScope(scope) {
-            return withScopeLock(scope, async () => {
+        // The ledger barrier runs under the scope lock (a rebuild in flight cannot
+        // write it back). Each row is then erased under its own path lock, the
+        // same owner an ordinary write takes, so no write to a path interleaves
+        // with the erase of that path. The scope lock is never held across those
+        // path locks: lock order is path, scope, queue.
+        async deleteScope(scope) {
+            await withScopeLock(scope, async () => {
                 await dropLedger(scope);
                 for (const entry of entriesForScope(scope)) {
                     readyBlockManifests.delete(blockManifestPath(scope, entry.collectedAt));
                 }
                 // Repeat the barrier on retry, even if a failed write cleared the set.
                 await persist();
-                let deleted = 0;
-                const deletedPaths = [];
-                const deletedBlockTrees = [];
-                state = {
-                    ...state,
-                    entries: state.entries.filter((entry) => {
-                        if (entry.scope !== scope)
-                            return true;
-                        deleted += 1;
-                        deletedPaths.push(envelopePath(entry.scope, entry.collectedAt));
-                        deletedBlockTrees.push(blockTreePath(entry.scope, entry.collectedAt));
-                        return false;
-                    }),
-                };
-                await Promise.all([
-                    ...deletedPaths.flatMap((path) => [
-                        fileStore.deleteEnvelope(path),
-                        fallbackStore.deleteEnvelope(path),
-                    ]),
-                    ...deletedBlockTrees.flatMap((path) => [
-                        fileStore.deleteBlockTree?.(path),
-                        fallbackStore.deleteBlockTree?.(path),
-                    ]),
-                ].filter((promise) => promise !== undefined));
-                await persist();
-                return deleted;
             });
+            // A row a later write adds is not in this snapshot; it is not deleted.
+            const paths = await enqueue(async () => Array.from(new Set(state.entries
+                .filter((entry) => entry.scope === scope)
+                .map((entry) => entry.path))));
+            // Each path settles on its own, so one failed blob delete does not stop
+            // the others. Rows whose delete failed stay, for the next retry.
+            const outcomes = await Promise.allSettled(paths.map((path) => withPathLock(path, () => eraseUnderPathLock(path, (e) => e.scope === scope && e.path === path))));
+            const failed = outcomes.find((outcome) => outcome.status === "rejected");
+            if (failed)
+                throw failed.reason;
+            return outcomes.filter((outcome) => outcome.status === "fulfilled" && outcome.value === true).length;
         },
-        async deleteVersion(scope, collectedAt) {
-            const entry = state.entries.find((e) => e.scope === scope && e.collectedAt === collectedAt);
-            if (!entry)
-                return false;
-            return removeEntry(entry);
+        // Unfenced: by (scope, collectedAt) alone. Fenced: only the row the caller
+        // decided on, by its id and path.
+        deleteVersion(scope, collectedAt, fence) {
+            // The path is fixed by (scope, collectedAt), so the lock is known now.
+            const path = envelopePath(scope, collectedAt);
+            return withPathLock(path, () => eraseUnderPathLock(path, (e) => e.scope === scope &&
+                e.collectedAt === collectedAt &&
+                e.path === path &&
+                (fence === undefined || e.id === fence.id))).then((outcome) => outcome === true);
+        },
+        // Only while the envelope is absent: the check and the erase both run
+        // under the path lock that every write of this path takes. A store that
+        // throws on read is a fault, not absence, and the row stays.
+        deleteVersionIfEnvelopeMissing(scope, collectedAt, fence) {
+            const path = envelopePath(scope, collectedAt);
+            if (fence.path !== path)
+                return Promise.resolve(false);
+            return withPathLock(path, async () => {
+                const present = (await fileStore.readEnvelope(path)) ??
+                    (await fallbackStore.readEnvelope(path));
+                if (present)
+                    return false;
+                const outcome = await eraseUnderPathLock(path, (e) => e.scope === scope &&
+                    e.collectedAt === collectedAt &&
+                    e.path === path &&
+                    e.id === fence.id);
+                return outcome === true;
+            });
         },
         async deleteByFileId(fileId) {
-            const entry = state.entries.find((e) => e.fileId === fileId);
-            if (!entry)
-                return false;
-            return removeEntry(entry);
+            // The fileId only names the path whose lock to take. The row is
+            // re-resolved under that lock, and looked again if it moved.
+            for (;;) {
+                const path = await enqueue(async () => state.entries.find((e) => e.fileId === fileId)?.path ?? null);
+                if (path === null)
+                    return false;
+                const outcome = await withPathLock(path, () => eraseUnderPathLock(path, (e) => e.fileId === fileId));
+                if (outcome !== "moved")
+                    return outcome;
+            }
         },
     };
     /**
@@ -750,34 +896,94 @@ export async function createPersistentPsLiteStorage(adapter, persistence = creat
             await persist().catch(() => undefined);
         }
     }
-    async function removeEntry(entry) {
-        return withScopeLock(entry.scope, () => removeEntryLocked(entry));
+    /**
+     * The per-path FIFO lock: the one owner of a path's blob and row. An
+     * operation holds it for its whole duration, so operations on one path never
+     * interleave. The slot is taken synchronously at call time, so calls run in
+     * call order.
+     *
+     * Lock order, never reversed: path lock, then scope lock, then the index
+     * queue. Never take a path lock while holding the scope lock or inside the
+     * queue (`enqueue`), or two operations can wait on each other.
+     */
+    const pathTails = new Map();
+    function withPathLock(path, fn) {
+        const previous = pathTails.get(path);
+        let release;
+        const mine = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous ? previous.then(() => mine) : mine;
+        pathTails.set(path, tail);
+        // A free path starts `fn` now, not a microtask later, so the caller's
+        // index-queue slot is taken in call order.
+        const run = previous
+            ? previous.then(fn)
+            : new Promise((resolve) => resolve(fn()));
+        return run.finally(() => {
+            release();
+            if (pathTails.get(path) === tail)
+                pathTails.delete(path);
+        });
     }
-    async function removeEntryLocked(entry) {
-        const blobPath = envelopePath(entry.scope, entry.collectedAt);
-        // Delete the blob FIRST (both stores tolerate a missing blob); only drop the index row once
-        // the blob is gone. If blob deletion throws for a real reason, the row is preserved so the
-        // next sync retry re-attempts instead of orphaning the local blob.
-        // A partial delete can remove the tree while leaving the index row.
-        // Persist the conservative hint before any destructive file operation.
-        readyBlockManifests.delete(blockManifestPath(entry.scope, entry.collectedAt));
-        await persist();
-        await Promise.all([
-            fileStore.deleteEnvelope(blobPath),
-            fallbackStore.deleteEnvelope(blobPath),
-            fileStore.deleteBlockTree?.(blockTreePath(entry.scope, entry.collectedAt)) ?? Promise.resolve(),
-            fallbackStore.deleteBlockTree?.(blockTreePath(entry.scope, entry.collectedAt)) ?? Promise.resolve(),
-        ]);
-        state = {
-            ...state,
-            entries: state.entries.filter((e) => e !== entry),
-        };
-        // The sidecar goes with the scope's last version.
-        await persist();
-        if (!state.entries.some((e) => e.scope === entry.scope)) {
-            await dropLedger(entry.scope);
-        }
-        return true;
+    /**
+     * Erase the row `match` picks, and its blob. The caller holds the path lock
+     * for `path`. The row is resolved inside the queue at the moment the lock is
+     * held, so an earlier update or replacement is seen. Resolves "moved" when
+     * the row found sits at another path, and the caller must look again.
+     *
+     * The blob parts run together, and all of them settle before this returns.
+     * If any part fails, the row stays and the first error is rethrown.
+     */
+    async function eraseUnderPathLock(path, match) {
+        const found = await enqueue(async () => {
+            const entry = state.entries.find(match);
+            if (!entry)
+                return null;
+            if (entry.path !== path)
+                return "moved";
+            // Persist the conservative hint before any destructive file operation.
+            // A partial delete can remove the tree while leaving the row.
+            readyBlockManifests.delete(blockManifestPath(entry.scope, entry.collectedAt));
+            await persistence.write(snapshotOf(state));
+            return {
+                id: entry.id,
+                scope: entry.scope,
+                collectedAt: entry.collectedAt,
+                path: entry.path,
+            };
+        });
+        if (found === null)
+            return false;
+        if (found === "moved")
+            return "moved";
+        return withScopeLock(found.scope, async () => {
+            const blob = envelopePath(found.scope, found.collectedAt);
+            const tree = blockTreePath(found.scope, found.collectedAt);
+            const parts = await Promise.allSettled([
+                fileStore.deleteEnvelope(blob),
+                fallbackStore.deleteEnvelope(blob),
+                fileStore.deleteBlockTree?.(tree) ?? Promise.resolve(),
+                fallbackStore.deleteBlockTree?.(tree) ?? Promise.resolve(),
+            ]);
+            const failed = parts.find((part) => part.status === "rejected");
+            if (failed)
+                throw failed.reason;
+            await enqueue(async () => {
+                if (!state.entries.some((e) => e.id === found.id))
+                    return;
+                await publish({
+                    ...state,
+                    entries: state.entries.filter((e) => e.id !== found.id),
+                });
+            });
+            // The sidecar goes with the scope's last version.
+            await persist();
+            if (!state.entries.some((e) => e.scope === found.scope)) {
+                await dropLedger(found.scope);
+            }
+            return true;
+        });
     }
     if (fileStore.readEnvelopePreview) {
         storagePort.readEnvelopePreview = async (scope, collectedAt, { maxBytes }) => {