diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index 5dece5fc..e840bec6 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -613,6 +613,7 @@ export function createOpfsByteStoreAdapter( moreTransactionsAvailable: boolean; deadlineReached: boolean; skippedLiveTransactions: number; + failedTransactions: number; } = { inspectedTransactions: 0, committedTransactions: 0, @@ -624,6 +625,7 @@ export function createOpfsByteStoreAdapter( moreTransactionsAvailable: listed.value.moreAvailable, deadlineReached: false, skippedLiveTransactions: 0, + failedTransactions: 0, }; // 05-01 (D-3). A row is reconciled only while this call holds its // per-transaction lock, so a put or delete still running in any tab is @@ -665,7 +667,11 @@ export function createOpfsByteStoreAdapter( report.inspectedTransactions += 1; const reconciled = await reconcileTransaction(transaction, request.signal); if (!reconciled.ok) { - return observeFailure(reconciled, dependencies.observer); + // 05-02. A row that cannot be settled now stays for a later run; + // it must not stop the rest of the page or orphan GC. + observeFailure(reconciled, dependencies.observer); + report.failedTransactions += 1; + continue; } report.committedTransactions += reconciled.value.committed; report.rolledBackTransactions += reconciled.value.rolledBack; diff --git a/src/adapters/storage/opfs/opfs-worker-runtime.ts b/src/adapters/storage/opfs/opfs-worker-runtime.ts index 68bf2691..07b23ba4 100644 --- a/src/adapters/storage/opfs/opfs-worker-runtime.ts +++ b/src/adapters/storage/opfs/opfs-worker-runtime.ts @@ -890,16 +890,11 @@ export function createOpfsWorkerRuntime( } { if (removePreparedGeneration) { - let receipt: unknown; - try { - receipt = await readJson(receiptPath(scope, transactionId)); - } catch (error) { - if (isNotFound(error)) { - await removeEntryIfPresent(staging, transactionId, true); - return CLEANUP_ALREADY_CLEAN; - } - // Keep unreadable staging in place so orphan GC fails closed. - throw error; + // Keep unreadable staging in place so orphan GC fails closed. + const receipt = await readReceipt(scope, transactionId); + if (receipt === undefined) { + await removeEntryIfPresent(staging, transactionId, true); + return CLEANUP_ALREADY_CLEAN; } const target = extractReceiptPhysicalTarget(receipt, scope); if (!target) { @@ -1133,10 +1128,11 @@ export function createOpfsWorkerRuntime( } let receipt: unknown; try { - receipt = await readJson(receiptPath(scope, transactionId)); + receipt = await readReceipt(scope, transactionId); } catch { return { safeToSweep: false, digests }; } + if (receipt === undefined) continue; if (!receiptBelongsToScope(receipt, scope)) { return { safeToSweep: false, digests }; } @@ -1303,8 +1299,31 @@ export function createOpfsWorkerRuntime( await writeWithAtomicWritable(handle, bytes); } + /** + * 05-02. `writeJsonAtomic` creates the file before its first write lands, + * so a first receipt write that hit the quota or a crash leaves a zero-byte + * file. BEGIN writes that receipt before any chunk or generation directory, + * so an empty receipt, like a missing one, has nothing to clean up. + */ + async function readReceipt( + scope: OpfsStorageScope, + transactionId: string, + ): Promise { + let bytes: Uint8Array; + try { + bytes = await readFile(receiptPath(scope, transactionId)); + } catch (error) { + if (isNotFound(error)) return undefined; + throw error; + } + return bytes.byteLength === 0 ? undefined : parseJson(bytes); + } + async function readJson(path: readonly string[]): Promise { - const bytes = await readFile(path); + return parseJson(await readFile(path)); + } + + function parseJson(bytes: Uint8Array): unknown { if (bytes.byteLength > MAX_MANIFEST_BYTES) { throw new OpfsRuntimeFailure("CORRUPT_DATA"); } diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index d42f6fcc..d3e0fee5 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -105,6 +105,12 @@ export type OpfsReconciliationReport = Readonly<{ * a live put or delete, not debris, and are left for a later reconcile. */ skippedLiveTransactions: number; + /** + * 05-02. Rows that failed to reconcile this time. Each stays in the journal + * for a later run and is observed as a `FAILED` reconcile; it no longer + * stops the rest of the page or orphan GC. + */ + failedTransactions: number; }>; export type OpfsPolicyMaintenanceReport = Readonly<{ diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index 5be24707..734a2d9e 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -717,6 +717,64 @@ describe("OPFS byte-store coordinator", () => { expect(finalizePut).toHaveBeenCalledTimes(1); }); + it("05-02 skips a row it cannot reconcile, settles the rest and still runs orphan GC", async () => { + const journal = createJournal(); + const row = (transactionId: string): OpfsJournalTransaction => ({ + transactionId, + fencingToken: "fencing_12345678", + mutation: "PUT", + scope, + phase: "PREPARING", + objectId: `object_${transactionId.slice(-8)}`, + expectedGeneration: null, + targetGeneration: 1, + targetByteLength: 1, + targetStoragePolicy: storagePolicy, + budgetReservation: { + namespace: scope.namespace, + reservedBytes: 1, + hardBudgetBytes: storagePolicy.hardBudgetBytes, + }, + startedAtEpochMs: 100, + }); + journal.transactions.set("transaction_broken_1", row("transaction_broken_1")); + journal.transactions.set("transaction_healthy_1", row("transaction_healthy_1")); + const worker = createWorker({ + async cleanupTransaction(_scope, transactionId) { + return transactionId === "transaction_broken_1" + ? browserDataFailure("CORRUPT_DATA", "OBJECT_RECONCILE") + : browserDataSuccess({ kind: "CLEANED" as const }); + }, + }); + const listOrphanCandidates = vi.spyOn(worker, "listOrphanCandidates"); + const observations: unknown[] = []; + const adapter = createOpfsByteStoreAdapter({ + journal, + worker, + scope, + storagePolicy, + now: () => 100, + observer: (event) => observations.push(event), + }); + + expect(await adapter.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { + inspectedTransactions: 2, + failedTransactions: 1, + rolledBackTransactions: 1, + orphanGcStatus: "COMPLETED", + }, + }); + expect([...journal.transactions.keys()]).toEqual(["transaction_broken_1"]); + expect(listOrphanCandidates).toHaveBeenCalledTimes(1); + expect(observations).toContainEqual({ + operation: "OBJECT_RECONCILE", + outcome: "FAILED", + failureCode: "CORRUPT_DATA", + }); + }); + it("does not roll back journal after an unknown worker mutation effect", async () => { const journal = createJournal(); const worker = createWorker({ diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index 9c87e156..a7f93f27 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -2184,3 +2184,111 @@ describe("05-01 reconcile leaves a live put's journal row alone", () => { }, ); }); + +describe("05-02 an empty receipt left by a failed first write is no receipt", () => { + it("cleans a crash-left empty receipt and keeps orphan GC sweeping", async () => { + const root = new MemoryDirectory(); + const runtime = createOpfsWorkerRuntime({ + root: root as unknown as FileSystemDirectoryHandle, + crypto: globalThis.crypto, + policy: runtimePolicy, + leaseManager: immediateLeases({ count: 0 }), + dedicatedWorker: true, + supportsSynchronousAccessHandles: false, + }); + // `getFileHandle({create:true})` made the file; the write never landed. + let directory = root as unknown as FileSystemDirectoryHandle; + for (const segment of [ + "authorities", + scopeA.authorityToken, + scopeA.namespaceToken, + scopeA.partitionToken, + "staging", + "transaction_empty_0001", + ]) { + directory = await directory.getDirectoryHandle(segment, { create: true }); + } + await directory.getFileHandle("receipt.json", { create: true }); + const orphan = "0".repeat(64); + await seedChunk(root, scopeA, orphan); + + expect( + await runtime.handleRequest({ + requestId: "request_empty_list", + protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, + kind: "LIST_ORPHAN_CANDIDATES", + scope: scopeA, + olderThanEpochMs: Date.now(), + maxEntries: 10, + }), + ).toMatchObject({ + ok: true, + value: { safeToSweep: true, digests: [orphan] }, + }); + expect( + await runtime.handleRequest({ + requestId: "request_empty_cleanup", + protocolVersion: OPFS_WORKER_PROTOCOL_VERSION, + kind: "CLEANUP_TRANSACTION", + scope: scopeA, + transactionId: "transaction_empty_0001", + }), + ).toMatchObject({ ok: true, value: { kind: "ALREADY_CLEAN" } }); + expect( + root.has([ + "authorities", + scopeA.authorityToken, + scopeA.namespaceToken, + scopeA.partitionToken, + "staging", + "transaction_empty_0001", + ]), + ).toBe(false); + }); + + it("compensates a put whose first receipt write hit the quota, so reconcile runs and the same id retries", async () => { + const { tab } = sharedRootTabs(); + const store = tab("q"); + const getFileHandle = MemoryDirectory.prototype.getFileHandle; + let failReceipt = true; + vi.spyOn(MemoryDirectory.prototype, "getFileHandle").mockImplementation( + async function (this: MemoryDirectory, name, options) { + const handle = await getFileHandle.call(this, name, options); + if (name !== "receipt.json" || !failReceipt) return handle; + failReceipt = false; + return { + ...handle, + async createWritable() { + const writable = await handle.createWritable(); + return { + write: (data: FileSystemWriteChunkType) => writable.write(data), + abort: () => writable.abort(), + async close() { + throw new DOMException("Quota exceeded.", "QuotaExceededError"); + }, + } as unknown as FileSystemWritableFileStream; + }, + } as FileSystemFileHandle; + }, + ); + const put = () => + store.objects.put({ + objectId: "object_12345678", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }); + + const failed = await put(); + expect(failed).toMatchObject({ + ok: false, + error: { code: "QUOTA_EXCEEDED" }, + }); + expect(failed.ok || failed.error.recovery).not.toBe("RECONCILE"); + expect(await store.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { inspectedTransactions: 0, orphanGcStatus: "COMPLETED" }, + }); + expect(await put()).toMatchObject({ ok: true, value: { generation: 1 } }); + }); +});