@earendil-works/pi-durable 1.4.0 → 1.5.1

package/dist/storage/jsonl/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/storage/jsonl/storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/storage/jsonl/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage/jsonl/storage.js

@@ -4,6 +4,8 @@ import { MemoryStorage } from "../memory.js";
 const FORMAT_VERSION = 1;
 const MAIN_FILE = "main.jsonl";
 const RECLAIM_SUFFIX = ".reclaim";
+/** Read-only opens retried after racing a writer's commits; each retry means another commit landed meanwhile. */
+const READ_ONLY_OPEN_ATTEMPTS = 5;
 const textDecoder = new TextDecoder("utf-8", { fatal: true });
 export class JsonlCorruptionError extends Error {
     constructor(message, cause) {
@@ -11,6 +13,13 @@ export class JsonlCorruptionError extends Error {
         this.name = "JsonlCorruptionError";
     }
 }
+/** `commit()` on a storage opened with `readOnly: true`. Nothing was written. */
+export class JsonlStorageReadOnlyError extends Error {
+    constructor() {
+        super("JSONL storage is open read-only");
+        this.name = "JsonlStorageReadOnlyError";
+    }
+}
 export class JsonlStoragePoisonedError extends Error {
     constructor(cause) {
         super("JSONL storage is poisoned and must be reopened", { cause });
@@ -147,38 +156,122 @@ export class JsonlStorage {
     directory;
     mainPath;
     fsync;
+    readOnly;
     memory = new MemoryStorage();
     currentOnlyDocuments = new Set();
     liveTaskSidecars = new Set();
     closed = false;
+    /** Bytes of `main.jsonl` recovery read (`mainChanged()`). */
+    mainSize = 0;
     poisonError;
+    /** Settles once the batch being appended is; its batches are in memory already (`commit()`). */
+    writing;
     constructor(fs, directory, mainPath, options) {
         this.fs = fs;
         this.directory = directory;
         this.mainPath = mainPath;
         this.fsync = options.fsync ?? false;
+        this.readOnly = options.readOnly ?? false;
     }
-    /** Open or create a JSONL storage directory using the supplied filesystem. */
+    /**
+     * Open or create a JSONL storage directory using the supplied filesystem. With `readOnly`, open an existing one
+     * without writing; a recovery that fails while `main.jsonl` changes raced a writer's commit and is retried.
+     */
     static async open(directory, fs, context, options = {}) {
         const absolute = await fs.absolutePath(directory, context);
         if (!absolute.ok)
             throw errorFromFile("path resolution", absolute.error);
-        const created = await fs.createDir(absolute.value, { recursive: true }, context);
-        if (!created.ok)
-            throw errorFromFile("directory creation", created.error);
+        if (options.readOnly !== true) {
+            const created = await fs.createDir(absolute.value, { recursive: true }, context);
+            if (!created.ok)
+                throw errorFromFile("directory creation", created.error);
+        }
         const mainPathResult = await fs.joinPath([absolute.value, MAIN_FILE], context);
         if (!mainPathResult.ok)
             throw errorFromFile("path join", mainPathResult.error);
-        const storage = new JsonlStorage(fs, absolute.value, mainPathResult.value, options);
-        await storage.recover(context);
-        return storage;
+        for (let attempt = 1;; attempt++) {
+            const storage = new JsonlStorage(fs, absolute.value, mainPathResult.value, options);
+            try {
+                await storage.recover(context);
+                return storage;
+            }
+            catch (error) {
+                if (!storage.readOnly ||
+                    attempt === READ_ONLY_OPEN_ATTEMPTS ||
+                    !(error instanceof JsonlCorruptionError) ||
+                    !(await storage.mainChanged(context))) {
+                    throw error;
+                }
+            }
+        }
     }
-    async commit(writes, context) {
+    /**
+     * Commit `batches` with one append per affected file: every batch's sidecar records first, then their markers in one
+     * write of `main.jsonl`. Each batch is checked against the state the earlier ones left, so memory applies each one
+     * as it passes, and reads wait until the appends are done; the first batch refused ends the batch. A torn append of
+     * the markers recovers a shorter complete prefix; any failure once a batch applied poisons the storage.
+     */
+    async commit(batches, receive, context) {
         this.assertUsable();
-        const prepared = this.memory.prepareCommit(writes);
-        const encoded = this.encodeCommit(prepared.seq, prepared.writes);
-        const reclamations = this.planReclamations(prepared.writes, encoded);
-        const sidecars = await Promise.all([...encoded.sidecars].map(async ([file, content]) => ({
+        if (this.readOnly)
+            throw new JsonlStorageReadOnlyError();
+        const seqs = [];
+        const encoded = [];
+        const reclamations = new Map();
+        let refused;
+        const writing = Promise.withResolvers();
+        this.writing = writing.promise;
+        try {
+            for (const writes of batches) {
+                let prepared;
+                try {
+                    prepared = this.memory.prepareCommit(writes);
+                }
+                catch (error) {
+                    refused = { error };
+                    break;
+                }
+                const commit = this.encodeCommit(prepared.seq, prepared.writes);
+                // A sidecar an earlier batch replaces keeps what the later ones append, unless they replace it again.
+                for (const [file, content] of commit.sidecars) {
+                    const replacement = reclamations.get(file);
+                    if (replacement !== undefined)
+                        reclamations.set(file, replacement + content);
+                }
+                for (const [file, content] of this.planReclamations(prepared.writes, commit))
+                    reclamations.set(file, content);
+                seqs.push(prepared.apply());
+                this.adoptSidecarState(prepared.writes);
+                encoded.push(commit);
+            }
+            if (encoded.length > 0)
+                await this.append(encoded, context);
+        }
+        catch (error) {
+            // Memory runs ahead of the file: once a batch applied, any failure poisons the storage before the reads
+            // waiting on the append go on, so none of them returns what is not stored.
+            if (seqs.length === 0)
+                throw error;
+            throw this.poison(error instanceof Error ? error : new Error("JSONL commit failed", { cause: error }));
+        }
+        finally {
+            this.writing = undefined;
+            writing.resolve();
+        }
+        // The markers are appended: the batches are durable. Reclaiming sidecars comes after the receipts.
+        for (const [index, seq] of seqs.entries())
+            receive(index, seq);
+        await this.reclaimSidecars(reclamations, context);
+        return refused === undefined ? { stored: seqs.length } : { stored: seqs.length, refused: refused.error };
+    }
+    /** Append the sidecar records of `commits`, flushed with `fsync`, then their markers in one write of `main.jsonl`. */
+    async append(commits, context) {
+        const contents = new Map();
+        for (const commit of commits) {
+            for (const [file, content] of commit.sidecars)
+                contents.set(file, (contents.get(file) ?? "") + content);
+        }
+        const sidecars = await Promise.all([...contents].map(async ([file, content]) => ({
             file,
             content,
             path: await this.resolveFile(file, context),
@@ -195,59 +288,56 @@ export class JsonlStorage {
                     throw this.poison(errorFromFile(`flush of ${sidecar.file}`, result.error));
             }
         }
-        const marker = await this.fs.appendFile(this.mainPath, encoded.marker, context);
+        const markers = commits.length === 1 ? commits[0].marker : commits.map((commit) => commit.marker).join("");
+        const marker = await this.fs.appendFile(this.mainPath, markers, context);
         if (!marker.ok)
             throw this.poison(errorFromFile(`append to ${MAIN_FILE}`, marker.error));
-        const seq = prepared.apply();
-        this.adoptSidecarState(prepared.writes);
-        await this.reclaimSidecars(reclamations, context);
-        return seq;
     }
     async mintId() {
         return this.store.mintId();
     }
     async conversation(id, context) {
-        return this.store.conversation(id, context);
+        return (await this.readable()).conversation(id, context);
     }
     async scanConversations(query, limit, cursor, context) {
-        return this.store.scanConversations(query, limit, cursor, context);
+        return (await this.readable()).scanConversations(query, limit, cursor, context);
     }
     async entry(idOrConversationId, idOrContext, context) {
         if (context === undefined)
-            return this.store.entry(idFromNumber(idOrConversationId), idOrContext);
+            return (await this.readable()).entry(idFromNumber(idOrConversationId), idOrContext);
         if (typeof idOrContext !== "number")
             throw new StorageRequestError("Storage.entry() requires an entry ID");
-        return this.store.entry(idFromNumber(idOrConversationId), idFromNumber(idOrContext), context);
+        return (await this.readable()).entry(idFromNumber(idOrConversationId), idFromNumber(idOrContext), context);
     }
     async findLatestHeadMarker(conversationId, atOrBeforeEntryId, context) {
-        return this.store.findLatestHeadMarker(conversationId, atOrBeforeEntryId, context);
+        return (await this.readable()).findLatestHeadMarker(conversationId, atOrBeforeEntryId, context);
     }
     async scanEntries(query, limit, cursor, context) {
-        return this.store.scanEntries(query, limit, cursor, context);
+        return (await this.readable()).scanEntries(query, limit, cursor, context);
     }
     async task(id, context) {
-        return this.store.task(id, context);
+        return (await this.readable()).task(id, context);
     }
     async scanTasks(query, limit, cursor, context) {
-        return this.store.scanTasks(query, limit, cursor, context);
+        return (await this.readable()).scanTasks(query, limit, cursor, context);
     }
     async submission(id, context) {
-        return this.store.submission(id, context);
+        return (await this.readable()).submission(id, context);
     }
     async scanSubmissions(query, limit, cursor, context) {
-        return this.store.scanSubmissions(query, limit, cursor, context);
+        return (await this.readable()).scanSubmissions(query, limit, cursor, context);
     }
     async submissionByRequest(conversationId, requestId, context) {
-        return this.store.submissionByRequest(conversationId, requestId, context);
+        return (await this.readable()).submissionByRequest(conversationId, requestId, context);
     }
     async findDocument(address, at, context) {
-        return this.store.findDocument(address, at, context);
+        return (await this.readable()).findDocument(address, at, context);
     }
     async document(id, at, context) {
-        return this.store.document(id, at, context);
+        return (await this.readable()).document(id, at, context);
     }
     async scanDocuments(query, limit, cursor, context) {
-        return this.store.scanDocuments(query, limit, cursor, context);
+        return (await this.readable()).scanDocuments(query, limit, cursor, context);
     }
     async close(context) {
         if (this.closed)
@@ -412,11 +502,17 @@ export class JsonlStorage {
         }
         await this.fs.renameFile(temporaryPath.value, path.value, context);
     }
+    /**
+     * Load the confirmed state. A writable open also repairs the files: it truncates torn lines and unconfirmed sidecar
+     * tails, removes leftover reclaim files, and reclaims sidecar records later commits made unnecessary. A read-only
+     * open skips the same records in memory only.
+     */
     async recover(context) {
         const fs = this.fs;
         const directory = this.directory;
         const memory = this.memory;
-        const main = await JsonlStorage.readLines(fs, this.mainPath, MAIN_FILE, context, (text, line) => parseMainMarker(text, line));
+        const main = await this.readLines(this.mainPath, MAIN_FILE, context, (text, line) => parseMainMarker(text, line));
+        this.mainSize = main.size;
         let previousSeq = 0;
         for (const marker of main.lines) {
             if (marker.value.seq <= previousSeq) {
@@ -428,7 +524,7 @@ export class JsonlStorage {
         if (!listed.ok)
             throw errorFromFile("directory listing", listed.error);
         for (const info of listed.value) {
-            if (info.kind === "file" && isReclaimFileName(info.name)) {
+            if (!this.readOnly && info.kind === "file" && isReclaimFileName(info.name)) {
                 await fs.remove(info.path, { force: true }, context);
             }
         }
@@ -442,7 +538,7 @@ export class JsonlStorage {
             const pathResult = await fs.joinPath([directory, file], context);
             if (!pathResult.ok)
                 throw errorFromFile("path join", pathResult.error);
-            const parsed = await JsonlStorage.readLines(fs, pathResult.value, file, context, (text, line) => parseSidecarRecord(text, file, line));
+            const parsed = await this.readLines(pathResult.value, file, context, (text, line) => parseSidecarRecord(text, file, line));
             parsedFiles.set(file, parsed);
             let previous;
             for (const line of parsed.lines) {
@@ -578,7 +674,7 @@ export class JsonlStorage {
                     unconfirmedAt = line.start;
                 }
             }
-            if (unconfirmedAt !== undefined) {
+            if (unconfirmedAt !== undefined && !this.readOnly) {
                 const truncated = await fs.truncateFile(parsed.path, unconfirmedAt, context);
                 if (!truncated.ok)
                     throw errorFromFile(`tail truncation of ${file}`, truncated.error);
@@ -603,7 +699,8 @@ export class JsonlStorage {
                 reclamations.set(file, retainedLines.map((line) => jsonLine(line.value)).join(""));
             }
         }
-        await this.reclaimSidecars(reclamations, context);
+        if (!this.readOnly)
+            await this.reclaimSidecars(reclamations, context);
         for (const id of currentOnlyDocuments)
             this.currentOnlyDocuments.add(id);
         for (const [id, live] of finalTaskIsLive) {
@@ -624,20 +721,23 @@ export class JsonlStorage {
         confirmed.add(key);
         return line.value;
     }
-    static async readLines(fs, path, name, context, parse) {
-        const read = await fs.readBinaryFile(path, context);
+    /** Parse the complete lines of `path`; a torn final line is truncated, or only skipped when read-only. */
+    async readLines(path, name, context, parse) {
+        const read = await this.fs.readBinaryFile(path, context);
         if (!read.ok) {
             if (read.error.code === "not_found")
-                return { path, lines: [] };
+                return { path, lines: [], size: 0 };
             throw errorFromFile(`read of ${name}`, read.error);
         }
         const bytes = read.value;
         let completeSize = bytes.length;
         if (completeSize > 0 && bytes[completeSize - 1] !== 0x0a) {
             completeSize = bytes.lastIndexOf(0x0a) + 1;
-            const truncated = await fs.truncateFile(path, completeSize, context);
-            if (!truncated.ok)
-                throw errorFromFile(`torn-line truncation of ${name}`, truncated.error);
+            if (!this.readOnly) {
+                const truncated = await this.fs.truncateFile(path, completeSize, context);
+                if (!truncated.ok)
+                    throw errorFromFile(`torn-line truncation of ${name}`, truncated.error);
+            }
         }
         const lines = [];
         let start = 0;
@@ -656,7 +756,16 @@ export class JsonlStorage {
             start = end + 1;
             lineNumber++;
         }
-        return { path, lines };
+        return { path, lines, size: bytes.length };
+    }
+    /**
+     * Whether `main.jsonl` changed size since recovery read it. A writer reclaims a sidecar only after appending the
+     * marker that allows it, so sidecars read while `main.jsonl` stayed the same match its markers; a recovery that
+     * failed while it changed may have read a sidecar a newer commit reclaimed.
+     */
+    async mainChanged(context) {
+        const info = await this.fs.fileInfo(this.mainPath, context);
+        return info.ok && info.value.size !== this.mainSize;
     }
     async resolveFile(file, context) {
         const path = await this.fs.joinPath([this.directory, file], context);
@@ -668,6 +777,12 @@ export class JsonlStorage {
         this.assertUsable();
         return this.memory;
     }
+    /** The state to read once no batch is being appended: memory runs ahead of the file while one is. */
+    async readable() {
+        while (this.writing !== undefined)
+            await this.writing;
+        return this.store;
+    }
     poison(cause) {
         this.poisonError ??= new JsonlStoragePoisonedError(cause);
         return this.poisonError;