From 47cf040586be76bb29bde7afa62440b8c7801d1f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:12:33 +0900 Subject: [PATCH] fix(storage): treat an empty OPFS receipt as none and keep reconcile going past a failed row (05-02) A first receipt write that hit the quota left a zero-byte receipt.json that cleanup and orphan GC could not parse, so reconcile and GC for the whole authority stopped for good. An empty receipt now counts as no receipt, and reconcile counts a failed row, observes it and moves on to the rest and GC. Co-Authored-By: Claude Opus 5.5 --- .../storage/opfs/opfs-byte-store-adapter.ts | 8 +- .../storage/opfs/opfs-worker-runtime.ts | 43 +++++-- .../ports/browser-file-storage/opfs-ports.ts | 6 + tests/unit/opfs-byte-store.test.ts | 58 ++++++++++ tests/unit/opfs-worker-runtime.test.ts | 108 ++++++++++++++++++ 5 files changed, 210 insertions(+), 13 deletions(-) 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 } }); + }); +});