From 8fc816ee2585be8a3e4e66063b372e33ddbd3701 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:09:30 +0900 Subject: [PATCH 01/14] fix(storage): hold a per-transaction lock so reconcile skips a live OPFS put (05-01) Reconcile cleaned up any incomplete journal row, including a put still running in another tab, and the put then reported success for deleted files. Put and delete now hold a Web Lock per transaction from begin to return; reconcile takes those locks with ifAvailable, re-reads the page under them and reports the rows it skipped (D-3). Co-Authored-By: Claude Opus 5.5 --- .../storage/opfs/opfs-byte-store-adapter.ts | 519 +++++++++++------- .../ports/browser-file-storage/opfs-ports.ts | 5 + .../browser-capabilities/opfs-runtime.spec.ts | 190 +++++++ tests/unit/opfs-byte-store.test.ts | 51 ++ tests/unit/opfs-worker-runtime.test.ts | 101 ++++ 5 files changed, 661 insertions(+), 205 deletions(-) diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index df10546e..5dece5fc 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -96,6 +96,13 @@ export type OpfsByteStoreDependencies = Readonly<{ * deliberately separate from any caller signal. */ compensationSignal?: AbortSignal; + /** + * 05-01 (D-3). Web Locks, `navigator.locks` by default. A put or delete + * holds an exclusive per-transaction lock from journal `begin` until it + * returns; reconcile only touches rows whose lock it can take at once, so a + * live transaction in any tab is never cleaned up underneath its owner. + */ + lockManager?: Pick; now?: () => number; observer?: OpfsSafeObserver; /** @@ -152,6 +159,12 @@ export function createOpfsByteStoreAdapter( */ const compensationSignal = dependencies.compensationSignal; const now = dependencies.now ?? Date.now; + const lockManager = + dependencies.lockManager ?? globalThis.navigator?.locks; + if (!lockManager || typeof lockManager.request !== "function") { + throw new TypeError("OPFS byte store requires Web Locks."); + } + const requestLock = lockManager.request.bind(lockManager); const objects: DurableObjectStorePort = Object.freeze({ async capabilities() { @@ -203,146 +216,152 @@ export function createOpfsByteStoreAdapter( } const targetGeneration = (current?.descriptor.generation ?? 0) + 1; const transactionId = createTransactionId(); - // STO-01. The logical generation is reused across transactions; this - // token makes the physical target unique so a late compensation can never - // delete a newer transaction's directory. - const physicalGenerationId = createPhysicalGenerationId(); - notifyProgress(request, "PREPARING", 0); - const begun = await dependencies.journal.begin({ + return await withTransactionLock( transactionId, - mutation: "PUT", - scope: dependencies.scope, - objectId: request.objectId, - expectedGeneration: request.expectedGeneration, - targetGeneration, - targetByteLength: request.source.byteLength!, - targetStoragePolicy: dependencies.storagePolicy, - startedAtEpochMs: now(), - }); - if (!begun.ok) { - return observeFailure( - rebaseFailure(begun.error, "OBJECT_WRITE"), - dependencies.observer, - request.source.byteLength!, - ); - } + "OBJECT_WRITE", + async () => { + // STO-01. The logical generation is reused across transactions; this + // token makes the physical target unique so a late compensation can never + // delete a newer transaction's directory. + const physicalGenerationId = createPhysicalGenerationId(); + notifyProgress(request, "PREPARING", 0); + const begun = await dependencies.journal.begin({ + transactionId, + mutation: "PUT", + scope: dependencies.scope, + objectId: request.objectId, + expectedGeneration: request.expectedGeneration, + targetGeneration, + targetByteLength: request.source.byteLength!, + targetStoragePolicy: dependencies.storagePolicy, + startedAtEpochMs: now(), + }); + if (!begun.ok) { + return observeFailure( + rebaseFailure(begun.error, "OBJECT_WRITE"), + dependencies.observer, + request.source.byteLength!, + ); + } - const descriptor: Omit = - Object.freeze({ - objectId: request.objectId, - scope: dependencies.scope, - generation: targetGeneration, - byteLength: request.source.byteLength!, - mediaType: request.mediaType, - createdAtEpochMs: now(), - storagePolicy: dependencies.storagePolicy, - }); - const prepared = await dependencies.worker.preparePut({ - transactionId, - physicalGenerationId, - descriptor, - source: request.source, - signal: request.signal, - onProgress: request.onProgress, - }); - if (!prepared.ok) { - return observeFailure( - await compensatePreparedPut( - begun.value, + const descriptor: Omit = + Object.freeze({ + objectId: request.objectId, + scope: dependencies.scope, + generation: targetGeneration, + byteLength: request.source.byteLength!, + mediaType: request.mediaType, + createdAtEpochMs: now(), + storagePolicy: dependencies.storagePolicy, + }); + const prepared = await dependencies.worker.preparePut({ + transactionId, physicalGenerationId, - prepared.error, - ), - dependencies.observer, - request.source.byteLength!, - ); - } + descriptor, + source: request.source, + signal: request.signal, + onProgress: request.onProgress, + }); + if (!prepared.ok) { + return observeFailure( + await compensatePreparedPut( + begun.value, + physicalGenerationId, + prepared.error, + ), + dependencies.observer, + request.source.byteLength!, + ); + } - const filesReady = await dependencies.journal.markFilesReady( - transactionId, - begun.value.fencingToken, - prepared.value, - ); - if (!filesReady.ok) { - return observeFailure( - await compensatePreparedPut( - begun.value, - physicalGenerationId, - filesReady.error, - ), - dependencies.observer, - request.source.byteLength!, - ); - } + const filesReady = await dependencies.journal.markFilesReady( + transactionId, + begun.value.fencingToken, + prepared.value, + ); + if (!filesReady.ok) { + return observeFailure( + await compensatePreparedPut( + begun.value, + physicalGenerationId, + filesReady.error, + ), + dependencies.observer, + request.source.byteLength!, + ); + } - const committed = await dependencies.journal.commitPut( - transactionId, - begun.value.fencingToken, - ); - if (!committed.ok) { - // The commit response can be lost after IndexedDB commits. Reconciliation - // decides from the durable journal; rolling back here would be unsafe. - return observeFailure( - rebaseFailure(committed.error, "OBJECT_WRITE"), - dependencies.observer, - request.source.byteLength!, - ); - } + const committed = await dependencies.journal.commitPut( + transactionId, + begun.value.fencingToken, + ); + if (!committed.ok) { + // The commit response can be lost after IndexedDB commits. Reconciliation + // decides from the durable journal; rolling back here would be unsafe. + return observeFailure( + rebaseFailure(committed.error, "OBJECT_WRITE"), + dependencies.observer, + request.source.byteLength!, + ); + } - notifyProgress( - request, - "FINALIZING", - prepared.value.descriptor.byteLength, + notifyProgress( + request, + "FINALIZING", + prepared.value.descriptor.byteLength, + ); + const finalized = await dependencies.worker.finalizePut( + transactionId, + prepared.value, + request.signal, + ); + if (!finalized.ok) { + // STO-RR-01. The commit fence already passed, so the payload is durable + // and the journal keeps its COMMITTED record for reconciliation to + // settle. What did not happen is finalization: the previous generation + // and the staging directory are still present. Reporting a plain + // success here would claim a settled state nobody observed, so the + // worker's own failure is surfaced and the record is left recoverable. + return observeFailure( + rebaseFailure(finalized.error, "OBJECT_WRITE"), + dependencies.observer, + request.source.byteLength!, + ); + } + const completed = await dependencies.journal.complete( + transactionId, + begun.value.fencingToken, + ); + if (!completed.ok) { + // NS-04. The payload is durable and finalized, so nothing is rolled + // back and the `COMMITTED` row stays the reconciler's authority. What + // did not happen is settling the transaction, and reporting a plain + // success for it claimed a state nobody observed while the reconcile + // backlog and its quota pressure grew unseen. + observeOpfsSafely(dependencies.observer, { + operation: "OBJECT_WRITE", + outcome: "DEGRADED", + failureCode: completed.error.code, + byteBucket: byteBucket(prepared.value.descriptor.byteLength), + }); + return { + ok: false as const, + error: Object.freeze({ + ...completed.error, + operation: "OBJECT_WRITE" as const, + retryable: true, + recovery: "RECONCILE" as const, + }), + }; + } + observeOpfsSafely(dependencies.observer, { + operation: "OBJECT_WRITE", + outcome: "SUCCEEDED", + byteBucket: byteBucket(prepared.value.descriptor.byteLength), + }); + return browserDataSuccess(prepared.value.descriptor); + }, ); - const finalized = await dependencies.worker.finalizePut( - transactionId, - prepared.value, - request.signal, - ); - if (!finalized.ok) { - // STO-RR-01. The commit fence already passed, so the payload is durable - // and the journal keeps its COMMITTED record for reconciliation to - // settle. What did not happen is finalization: the previous generation - // and the staging directory are still present. Reporting a plain - // success here would claim a settled state nobody observed, so the - // worker's own failure is surfaced and the record is left recoverable. - return observeFailure( - rebaseFailure(finalized.error, "OBJECT_WRITE"), - dependencies.observer, - request.source.byteLength!, - ); - } - const completed = await dependencies.journal.complete( - transactionId, - begun.value.fencingToken, - ); - if (!completed.ok) { - // NS-04. The payload is durable and finalized, so nothing is rolled - // back and the `COMMITTED` row stays the reconciler's authority. What - // did not happen is settling the transaction, and reporting a plain - // success for it claimed a state nobody observed while the reconcile - // backlog and its quota pressure grew unseen. - observeOpfsSafely(dependencies.observer, { - operation: "OBJECT_WRITE", - outcome: "DEGRADED", - failureCode: completed.error.code, - byteBucket: byteBucket(prepared.value.descriptor.byteLength), - }); - return { - ok: false as const, - error: Object.freeze({ - ...completed.error, - operation: "OBJECT_WRITE" as const, - retryable: true, - recovery: "RECONCILE" as const, - }), - }; - } - observeOpfsSafely(dependencies.observer, { - operation: "OBJECT_WRITE", - outcome: "SUCCEEDED", - byteBucket: byteBucket(prepared.value.descriptor.byteLength), - }); - return browserDataSuccess(prepared.value.descriptor); }, async open( @@ -469,63 +488,70 @@ export function createOpfsByteStoreAdapter( ); } + const targetStoragePolicy = current.value.descriptor.storagePolicy; const transactionId = createTransactionId(); - const begun = await dependencies.journal.begin({ + return await withTransactionLock( transactionId, - mutation: "DELETE", - scope: dependencies.scope, - objectId: request.objectId, - expectedGeneration: request.expectedGeneration, - targetGeneration: request.expectedGeneration + 1, - targetByteLength: 0, - targetStoragePolicy: current.value.descriptor.storagePolicy, - startedAtEpochMs: now(), - }); - if (!begun.ok) { - return observeFailure( - rebaseFailure(begun.error, "OBJECT_DELETE"), - dependencies.observer, - ); - } - const committed = await dependencies.journal.commitDelete( - transactionId, - begun.value.fencingToken, - ); - if (!committed.ok) { - return observeFailure( - rebaseFailure(committed.error, "OBJECT_DELETE"), - dependencies.observer, - ); - } - const removed = await dependencies.worker.removeObject( - dependencies.scope, - request.objectId, - request.expectedGeneration, - request.signal, - ); - const completed = removed.ok - ? await dependencies.journal.complete( + "OBJECT_DELETE", + async () => { + const begun = await dependencies.journal.begin({ + transactionId, + mutation: "DELETE", + scope: dependencies.scope, + objectId: request.objectId, + expectedGeneration: request.expectedGeneration, + targetGeneration: request.expectedGeneration + 1, + targetByteLength: 0, + targetStoragePolicy, + startedAtEpochMs: now(), + }); + if (!begun.ok) { + return observeFailure( + rebaseFailure(begun.error, "OBJECT_DELETE"), + dependencies.observer, + ); + } + const committed = await dependencies.journal.commitDelete( transactionId, begun.value.fencingToken, - ) - : null; - // Logical deletion is already committed. Physical cleanup is retryable - // maintenance and must not make the caller repeat a non-idempotent delete. - // NS-04. It is still not a settled state: an unfinished physical removal - // or an unsettled journal row is maintenance debt the reconciler owns, so - // it is observed as such instead of as a clean success. - const settled = removed.ok && completed !== null && completed.ok; - const debtCode = removed.ok - ? completed !== null && !completed.ok - ? completed.error.code - : undefined - : removed.error.code; - observeOpfsSafely(dependencies.observer, { - operation: "OBJECT_DELETE", - outcome: settled ? "SUCCEEDED" : "DEGRADED", - ...(debtCode ? { failureCode: debtCode } : {}), - }); - return browserDataSuccess(undefined); + ); + if (!committed.ok) { + return observeFailure( + rebaseFailure(committed.error, "OBJECT_DELETE"), + dependencies.observer, + ); + } + const removed = await dependencies.worker.removeObject( + dependencies.scope, + request.objectId, + request.expectedGeneration, + request.signal, + ); + const completed = removed.ok + ? await dependencies.journal.complete( + transactionId, + begun.value.fencingToken, + ) + : null; + // Logical deletion is already committed. Physical cleanup is retryable + // maintenance and must not make the caller repeat a non-idempotent delete. + // NS-04. It is still not a settled state: an unfinished physical removal + // or an unsettled journal row is maintenance debt the reconciler owns, so + // it is observed as such instead of as a clean success. + const settled = removed.ok && completed !== null && completed.ok; + const debtCode = removed.ok + ? completed !== null && !completed.ok + ? completed.error.code + : undefined + : removed.error.code; + observeOpfsSafely(dependencies.observer, { + operation: "OBJECT_DELETE", + outcome: settled ? "SUCCEEDED" : "DEGRADED", + ...(debtCode ? { failureCode: debtCode } : {}), + }); + return browserDataSuccess(undefined); + }, + ); }, }); @@ -563,14 +589,14 @@ export function createOpfsByteStoreAdapter( const maxTransactions = request.maxTransactions ?? policy.reconciliationBatchSize; const deadline = now() + budgetMs; - const page = await dependencies.journal.listIncomplete(maxTransactions); - if (!page.ok) { - return rebaseFailure(page.error, "OBJECT_RECONCILE"); + const listed = await dependencies.journal.listIncomplete(maxTransactions); + if (!listed.ok) { + return rebaseFailure(listed.error, "OBJECT_RECONCILE"); } observeOpfsSafely(dependencies.observer, { operation: "OBJECT_RECONCILE", outcome: "STARTED", - transactionBucket: transactionBucket(page.value.transactions.length), + transactionBucket: transactionBucket(listed.value.transactions.length), }); const report: { @@ -586,6 +612,7 @@ export function createOpfsByteStoreAdapter( | "STAGING_STATE_UNREADABLE"; moreTransactionsAvailable: boolean; deadlineReached: boolean; + skippedLiveTransactions: number; } = { inspectedTransactions: 0, committedTransactions: 0, @@ -594,26 +621,58 @@ export function createOpfsByteStoreAdapter( inspectedOrphanChunks: 0, deletedOrphanChunks: 0, orphanGcStatus: "COMPLETED", - moreTransactionsAvailable: page.value.moreAvailable, + moreTransactionsAvailable: listed.value.moreAvailable, deadlineReached: false, + skippedLiveTransactions: 0, }; - for (const transaction of page.value.transactions) { - if (request.signal?.aborted) { - return browserDataFailure("ABORTED", "OBJECT_RECONCILE"); + // 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 + // skipped. The page is read again under those locks: a row listed while + // its owner still ran may have moved on before the owner let go. + const held = new Map void>(); + try { + for (const transaction of listed.value.transactions) { + let release: (() => void) | null; + try { + release = await holdTransactionLock(transaction.transactionId); + } catch { + return browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE", { + retryable: true, + recovery: "RETRY", + }); + } + if (release) held.set(transaction.transactionId, release); + else report.skippedLiveTransactions += 1; } - if (now() >= deadline) { - report.deadlineReached = true; - report.moreTransactionsAvailable = true; - break; + const page = + held.size === 0 + ? listed + : await dependencies.journal.listIncomplete(maxTransactions); + if (!page.ok) { + return rebaseFailure(page.error, "OBJECT_RECONCILE"); } - report.inspectedTransactions += 1; - const reconciled = await reconcileTransaction(transaction, request.signal); - if (!reconciled.ok) { - return observeFailure(reconciled, dependencies.observer); + report.moreTransactionsAvailable = page.value.moreAvailable; + for (const transaction of page.value.transactions) { + if (!held.has(transaction.transactionId)) continue; + if (request.signal?.aborted) { + return browserDataFailure("ABORTED", "OBJECT_RECONCILE"); + } + if (now() >= deadline) { + report.deadlineReached = true; + report.moreTransactionsAvailable = true; + break; + } + report.inspectedTransactions += 1; + const reconciled = await reconcileTransaction(transaction, request.signal); + if (!reconciled.ok) { + return observeFailure(reconciled, dependencies.observer); + } + report.committedTransactions += reconciled.value.committed; + report.rolledBackTransactions += reconciled.value.rolledBack; + report.cleanedTransactions += reconciled.value.cleaned; } - report.committedTransactions += reconciled.value.committed; - report.rolledBackTransactions += reconciled.value.rolledBack; - report.cleanedTransactions += reconciled.value.cleaned; + } finally { + for (const release of held.values()) release(); } if (now() >= deadline) { report.deadlineReached = true; @@ -905,6 +964,56 @@ export function createOpfsByteStoreAdapter( return Object.freeze({ objects, maintenance }); + /** + * Takes the exclusive per-transaction Web Lock only if nobody holds it. + * Resolves with its release, or `null` while another context holds it. + */ + async function holdTransactionLock( + transactionId: string, + ): Promise<(() => void) | null> { + let release!: () => void; + const held = new Promise((resolve) => { + release = resolve; + }); + return await new Promise((resolve, reject) => { + requestLock( + `${policy.mutationLockName}:transaction:${scope.authorityToken}:${transactionId}`, + { mode: "exclusive", ifAvailable: true }, + async (lock) => { + if (!lock) { + resolve(null); + return; + } + resolve(release); + await held; + }, + ).catch(reject); + }); + } + + async function withTransactionLock( + transactionId: string, + operation: "OBJECT_WRITE" | "OBJECT_DELETE", + run: () => Promise>, + ): Promise> { + let release: (() => void) | null; + try { + release = await holdTransactionLock(transactionId); + } catch { + return browserDataFailure("UNAVAILABLE", operation, { + retryable: true, + recovery: "RETRY", + }); + } + // A fresh transaction id is never held; a holder means a duplicate id. + if (!release) return browserDataFailure("CONFLICT", operation); + try { + return await run(); + } finally { + release(); + } + } + /** * STO-01. The compensating half of the put saga. * diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index dbd2f2ac..d42f6fcc 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -100,6 +100,11 @@ export type OpfsReconciliationReport = Readonly<{ | "STAGING_STATE_UNREADABLE"; moreTransactionsAvailable: boolean; deadlineReached: boolean; + /** + * 05-01. Rows whose owner still holds the per-transaction lock. They are + * a live put or delete, not debris, and are left for a later reconcile. + */ + skippedLiveTransactions: number; }>; export type OpfsPolicyMaintenanceReport = Readonly<{ diff --git a/tests/browser-capabilities/opfs-runtime.spec.ts b/tests/browser-capabilities/opfs-runtime.spec.ts index fa154536..cecf5a07 100644 --- a/tests/browser-capabilities/opfs-runtime.spec.ts +++ b/tests/browser-capabilities/opfs-runtime.spec.ts @@ -219,3 +219,193 @@ test("runs put, open, remove and reconcile through a native DedicatedWorker, OPF expect(result.deletion).toBe("DELETED"); expect(["DELETED", "ABSENT"]).toContain(result.opfsCleanup); }); + +type OpfsTabScope = Readonly<{ + namespace: string; + authorityToken: string; + namespaceToken: string; + partitionToken: string; +}>; + +/** + * Installs an OPFS runtime for `scope` in this tab and keeps it on + * `globalThis.__opfsTab` for later evaluate calls. + */ +async function installOpfsTab( + page: import("@playwright/test").Page, + scope: OpfsTabScope, +): Promise { + return await page.evaluate(async (tabScope) => { + const runtimeModulePath = + "/src/adapters/storage/opfs/browser-opfs-runtime.ts"; + const policyModulePath = "/src/adapters/storage/opfs/opfs-policy.ts"; + const { createBrowserOpfsRuntime, inspectBrowserOpfsSupport } = + (await import( + /* @vite-ignore */ runtimeModulePath + )) as typeof import("../../src/adapters/storage/opfs/browser-opfs-runtime.ts"); + const { resolveOpfsRuntimePolicy } = (await import( + /* @vite-ignore */ policyModulePath + )) as typeof import("../../src/adapters/storage/opfs/opfs-policy.ts"); + const policy = resolveOpfsRuntimePolicy(); + if (!inspectBrowserOpfsSupport(policy).ok) return false; + (globalThis as unknown as { __opfsTab: unknown }).__opfsTab = + createBrowserOpfsRuntime({ + workerUrl: new URL( + "/tests/browser-capabilities/opfs-test.worker.ts", + location.href, + ), + workerName: `opfs-tab-${crypto.randomUUID()}`, + scope: tabScope, + storagePolicy: { + owner: "browser-capability", + namespace: tabScope.namespace, + classification: "PERSONAL", + authority: "LOCAL_FIRST", + accountScope: "OPAQUE_PARTITION", + retention: { kind: "EXPLICIT_DELETE" }, + softBudgetBytes: 1024 * 1024, + hardBudgetBytes: 2 * 1024 * 1024, + evictionPriority: "USER_AUTHORED", + logoutAction: "EXPORT_THEN_PURGE", + accountDeletionAction: "PURGE_PARTITION", + pressureAction: "RETAIN", + unavailableFallback: "EXPORT_REQUIRED", + }, + policy, + }); + return true; + }, scope); +} + +test("05-01 a reconcile in another tab skips a live put and the put stays readable", async ({ + page, +}) => { + const secondPage = await page.context().newPage(); + const suffix = crypto.randomUUID().replaceAll("-", ""); + const scope: OpfsTabScope = { + namespace: "durable-objects", + authorityToken: `authority_${suffix}`, + namespaceToken: `namespace_${suffix}`, + partitionToken: `partition_${suffix}`, + }; + type Tab = import("../../src/adapters/storage/opfs/browser-opfs-runtime.ts").BrowserOpfsRuntime; + try { + await Promise.all([page.goto("/"), secondPage.goto("/")]); + if (!(await installOpfsTab(page, scope))) return; + expect(await installOpfsTab(secondPage, scope)).toBe(true); + + // Tab A starts a put whose source stalls, so its journal row stays + // PREPARING and its worker holds the OPFS mutation lock. + await page.evaluate(async () => { + const state = globalThis as unknown as { + __opfsTab: Tab; + __release?: () => void; + __put?: Promise; + }; + let streaming!: () => void; + const started = new Promise((resolve) => { + streaming = resolve; + }); + const gate = new Promise((resolve) => { + state.__release = resolve; + }); + state.__put = state.__opfsTab.objects.put({ + objectId: "object_tab_12345678", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: { + byteLength: 4, + async *stream() { + streaming(); + await gate; + yield { ok: true as const, value: new Uint8Array([2, 7, 1, 8]) }; + }, + }, + }); + await started; + }); + + // Tab B reconciles while tab A's put is in flight. + await secondPage.evaluate(() => { + const state = globalThis as unknown as { + __opfsTab: Tab; + __reconcile?: Promise; + }; + state.__reconcile = state.__opfsTab.maintenance.reconcile(); + }); + await page.waitForTimeout(250); + const put = await page.evaluate(async () => { + const state = globalThis as unknown as { + __release: () => void; + __put: Promise; + }; + state.__release(); + return await state.__put; + }); + const reconciled = await secondPage.evaluate( + async () => + await (globalThis as unknown as { __reconcile: Promise }) + .__reconcile, + ); + const opened = await page.evaluate(async () => { + const runtime = (globalThis as unknown as { __opfsTab: Tab }).__opfsTab; + const result = await runtime.objects.open({ + objectId: "object_tab_12345678", + }); + if (!result.ok) return result.error.code; + const bytes: number[] = []; + for await (const chunk of result.value.source.stream( + new AbortController().signal, + )) { + if (!chunk.ok) return chunk.error.code; + bytes.push(...chunk.value); + } + return bytes; + }); + + expect(put).toMatchObject({ ok: true, value: { generation: 1 } }); + expect(reconciled).toMatchObject({ + ok: true, + value: { skippedLiveTransactions: 1, rolledBackTransactions: 0 }, + }); + expect(opened).toEqual([2, 7, 1, 8]); + } finally { + for (const tab of [page, secondPage]) { + await tab.evaluate(() => + (globalThis as unknown as { __opfsTab?: Tab }).__opfsTab?.close(), + ); + } + const cleanup = await page.evaluate(async (tabScope) => { + const journalModulePath = + "/src/adapters/storage/opfs/indexeddb-opfs-journal.ts"; + const policyModulePath = "/src/adapters/storage/opfs/opfs-policy.ts"; + const { opfsJournalDatabaseName } = (await import( + /* @vite-ignore */ journalModulePath + )) as typeof import("../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"); + const { DEFAULT_OPFS_RUNTIME_POLICY } = (await import( + /* @vite-ignore */ policyModulePath + )) as typeof import("../../src/adapters/storage/opfs/opfs-policy.ts"); + const deletion = await new Promise((resolve) => { + const request = indexedDB.deleteDatabase( + opfsJournalDatabaseName(tabScope.authorityToken), + ); + request.onsuccess = () => resolve("DELETED"); + request.onerror = () => resolve(request.error?.name ?? "UNKNOWN"); + request.onblocked = () => resolve("BLOCKED"); + }); + try { + const root = await ( + await navigator.storage.getDirectory() + ).getDirectoryHandle(DEFAULT_OPFS_RUNTIME_POLICY.rootDirectoryName); + await ( + await root.getDirectoryHandle("authorities") + ).removeEntry(tabScope.authorityToken, { recursive: true }); + } catch { + // Nothing was written for this authority. + } + return deletion; + }, scope); + expect(cleanup).toBe("DELETED"); + await secondPage.close(); + } +}); diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index 8586f2ef..5be24707 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -666,6 +666,57 @@ describe("OPFS byte-store coordinator", () => { } }); + it("05-01 decides a reconciled row from what the journal holds once its lock is taken", async () => { + // Listed while its owner still ran, the row was PREPARING. By the time + // the owner let go it had committed and only finalization failed, so the + // staging receipt names the committed generation. Cleaning it up from the + // stale snapshot would delete a committed object. + const journal = createJournal(); + const row: OpfsJournalTransaction = { + transactionId: "transaction_12345678", + fencingToken: "fencing_12345678", + mutation: "PUT", + scope, + phase: "PREPARING", + objectId: "object_12345678", + expectedGeneration: null, + targetGeneration: 1, + targetByteLength: 1, + targetStoragePolicy: storagePolicy, + budgetReservation: { + namespace: scope.namespace, + reservedBytes: 1, + hardBudgetBytes: storagePolicy.hardBudgetBytes, + }, + startedAtEpochMs: 100, + }; + journal.transactions.set(row.transactionId, { + ...row, + phase: "COMMITTED", + preparedObject: committedObject("object_12345678", storagePolicy, 100), + }); + vi.spyOn(journal, "listIncomplete").mockResolvedValueOnce( + browserDataSuccess({ transactions: [row], moreAvailable: false }), + ); + const worker = createWorker(); + const cleanupTransaction = vi.spyOn(worker, "cleanupTransaction"); + const finalizePut = vi.spyOn(worker, "finalizePut"); + const adapter = createOpfsByteStoreAdapter({ + journal, + worker, + scope, + storagePolicy, + now: () => 100, + }); + + expect(await adapter.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { inspectedTransactions: 1, rolledBackTransactions: 0 }, + }); + expect(cleanupTransaction).not.toHaveBeenCalled(); + expect(finalizePut).toHaveBeenCalledTimes(1); + }); + 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 71f7a117..9c87e156 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -13,6 +13,7 @@ import type { } from "../../src/application/ports/browser-file-storage/shared.ts"; import { browserDataSuccess } from "../../src/adapters/browser-file-storage/result.ts"; import { createOpfsByteStoreAdapter } from "../../src/adapters/storage/opfs/opfs-byte-store-adapter.ts"; +import { createIndexedDbOpfsJournal } from "../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"; import { resolveOpfsRuntimePolicy, } from "../../src/adapters/storage/opfs/opfs-policy.ts"; @@ -33,6 +34,7 @@ import { type OpfsWorkerMessageHost, type OpfsWorkerRuntime, } from "../../src/adapters/storage/opfs/opfs-worker-runtime.ts"; +import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; const scopeA: OpfsStorageScope = Object.freeze({ namespace: "durable-objects", @@ -2083,3 +2085,102 @@ describe("NS-05 a bootstrap failure answers the request it belongs to", () => { }); } }); + +/** + * Two runtimes ("tabs") share one OPFS root, one exclusive worker lock and + * one journal database, the way two tabs of one origin do. + */ +function sharedRootTabs(policy = runtimePolicy) { + const root = new MemoryDirectory(); + const leases = exclusiveLeases(); + const idb = new MemoryIndexedDbFactory(); + const tab = (tag: string) => { + const runtime = createOpfsWorkerRuntime({ + root: root as unknown as FileSystemDirectoryHandle, + crypto: globalThis.crypto, + policy, + leaseManager: leases, + dedicatedWorker: true, + supportsSynchronousAccessHandles: false, + }); + let sequence = 0; + return createOpfsByteStoreAdapter({ + journal: createIndexedDbOpfsJournal({ + authorityToken: scopeA.authorityToken, + factory: idb.factory, + keyRange: idb.keyRange, + }), + worker: loopbackGateway(runtime, policy), + scope: scopeA, + storagePolicy, + policy, + createTransactionId: () => `transaction_${tag}_${++sequence}`, + }); + }; + return { root, leases, idb, tab }; +} + +async function openedBytes( + adapter: ReturnType, + objectId: string, +): Promise | string> { + const opened = await adapter.objects.open({ objectId }); + if (!opened.ok) return opened.error.code; + const bytes: number[] = []; + for await (const chunk of opened.value.source.stream( + new AbortController().signal, + )) { + if (!chunk.ok) return chunk.error.code; + bytes.push(...chunk.value); + } + return { generation: opened.value.descriptor.generation, bytes }; +} + +describe("05-01 reconcile leaves a live put's journal row alone", () => { + it.each([ + ["a first put", null], + ["an overwrite", 1], + ] as const)( + "keeps %s that reconcile overlapped in another tab", + async (_label, expectedGeneration) => { + const { tab } = sharedRootTabs(); + const tabA = tab("a"); + const tabB = tab("b"); + if (expectedGeneration !== null) { + expect( + await tabA.objects.put({ + objectId: "object_12345678", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }), + ).toMatchObject({ ok: true, value: { generation: 1 } }); + } + + const stalled = stalledSource(); + const putA = tabA.objects.put({ + objectId: "object_12345678", + expectedGeneration, + mediaType: "application/octet-stream", + source: stalled.source, + }); + // Tab A holds the worker lock and its journal row is PREPARING. + await stalled.streaming; + const reconcileB = tabB.maintenance.reconcile(); + await new Promise((resolve) => setTimeout(resolve, 20)); + stalled.release(); + + const [put, reconciled] = await Promise.all([putA, reconcileB]); + const generation = (expectedGeneration ?? 0) + 1; + expect(put).toMatchObject({ ok: true, value: { generation } }); + expect(reconciled).toMatchObject({ + ok: true, + value: { skippedLiveTransactions: 1, rolledBackTransactions: 0 }, + }); + expect(await openedBytes(tabA, "object_12345678")).toEqual({ + generation, + bytes: [5], + }); + }, + ); +}); From 47cf040586be76bb29bde7afa62440b8c7801d1f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:12:33 +0900 Subject: [PATCH 02/14] 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 } }); + }); +}); From 9cae587aea2ed385b637b9f75f8c407fe321939a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:18:00 +0900 Subject: [PATCH 03/14] test(storage): make the memory IndexedDB fake serialize, expire and separate like a browser (05-08) The fake let overlapping readwrite transactions overwrite each other, took requests after the transaction's task ended and shared rows across database names, so adapter tests could pass on behavior no browser has. It now keeps one database per name, runs overlapping transactions in order, throws TransactionInactiveError for late requests, and its header lists what it still does not model. Co-Authored-By: Claude Opus 5.5 --- tests/helpers/memory-indexeddb.ts | 263 ++++++++++++++----- tests/unit/memory-indexeddb-fidelity.test.ts | 120 +++++++++ 2 files changed, 322 insertions(+), 61 deletions(-) create mode 100644 tests/unit/memory-indexeddb-fidelity.test.ts diff --git a/tests/helpers/memory-indexeddb.ts b/tests/helpers/memory-indexeddb.ts index 50238e7a..7eae6491 100644 --- a/tests/helpers/memory-indexeddb.ts +++ b/tests/helpers/memory-indexeddb.ts @@ -24,6 +24,27 @@ type StoreState = { indexes: Map; }; +/** One named database: its schema, rows and version. */ +type DatabaseState = { + stores: Map; + version: number; + latest: FakeDatabase | null; + /** Transactions that have not finished, in creation order. */ + transactions: FakeTransaction[]; +}; + +function storeOf(state: DatabaseState, name: string): StoreState { + const store = state.stores.get(name); + if (!store) { + throw new DOMException("Store does not exist.", "NotFoundError"); + } + return store; +} + +// The fake decides when a transaction's task has ended with a real macrotask, +// so a test that fakes timers cannot keep a transaction alive by accident. +const realSetTimeout = globalThis.setTimeout.bind(globalThis); + type FakeKeyRange = | Readonly<{ fakeKind: "ONLY"; @@ -221,23 +242,26 @@ class FakeDatabase { onversionchange: ((event: IDBVersionChangeEvent) => unknown) | null = null; onclose: ((event: Event) => unknown) | null = null; - constructor(private readonly owner: MemoryIndexedDbFactory) {} + constructor( + private readonly owner: MemoryIndexedDbFactory, + readonly state: DatabaseState, + ) {} get objectStoreNames(): DOMStringList { - return stringList(this.owner.storeNames()); + return stringList(this.state.stores.keys()); } createObjectStore( name: string, options?: IDBObjectStoreParameters, ): IDBObjectStore { - if (this.owner.hasStore(name)) { + if (this.state.stores.has(name)) { throw new DOMException("Store already exists.", "ConstraintError"); } if (typeof options?.keyPath !== "string") { throw new DOMException("The fake requires a string key path.", "DataError"); } - this.owner.createStore(name, { + this.state.stores.set(name, { keyPath: options.keyPath, autoIncrement: options.autoIncrement ?? false, data: new Map(), @@ -247,13 +271,13 @@ class FakeDatabase { } deleteObjectStore(name: string): void { - if (!this.owner.deleteStore(name)) { + if (!this.state.stores.delete(name)) { throw new DOMException("Store does not exist.", "NotFoundError"); } } schemaObjectStore(name: string): IDBObjectStore { - const state = this.owner.store(name); + const state = storeOf(this.state, name); return new FakeObjectStore(null, state) as unknown as IDBObjectStore; } @@ -261,7 +285,7 @@ class FakeDatabase { name: string, transaction: FakeUpgradeTransaction, ): IDBObjectStore { - const state = this.owner.store(name); + const state = storeOf(this.state, name); return new FakeObjectStore( null, state, @@ -278,7 +302,12 @@ class FakeDatabase { } const names = typeof storeNames === "string" ? [storeNames] : [...storeNames]; - const transaction = new FakeTransaction(this.owner, names, mode); + const transaction = new FakeTransaction( + this.owner, + this.state, + names, + mode, + ); this.owner.noteTransaction(transaction); return transaction as unknown as IDBTransaction; } @@ -307,19 +336,108 @@ class FakeTransaction { error: DOMException | null = null; readonly mode: IDBTransactionMode; private active = true; + /** + * Native "active" state: a request may be placed only in the task that + * created the transaction or while one of its request events (and the + * microtasks that event queued) is being handled. + */ + private accepting = true; + /** Held back until every earlier overlapping transaction finishes. */ + private started = false; + private readonly deferred: Array<() => void> = []; private completionQueued = false; private pending = 0; private readonly workingStores: Map; constructor( private readonly owner: MemoryIndexedDbFactory, + private readonly database: DatabaseState, private readonly names: readonly string[], mode: IDBTransactionMode, ) { this.mode = mode; this.workingStores = new Map( - names.map((name) => [name, cloneStore(owner.store(name))]), + names.map((name) => [name, cloneStore(storeOf(database, name))]), ); + database.transactions.push(this); + this.startIfUnblocked(); + this.deactivateAfterTask(); + } + + /** + * Native IndexedDB runs transactions with overlapping scopes in creation + * order unless both are readonly. A later one starts from the rows the + * earlier one committed. + */ + startIfUnblocked(): void { + if (this.started || !this.active) return; + const earlier = this.database.transactions.slice( + 0, + this.database.transactions.indexOf(this), + ); + if (earlier.some((transaction) => transaction.blocks(this))) return; + this.started = true; + for (const name of this.names) { + const fresh = cloneStore(storeOf(this.database, name)); + const working = this.workingStores.get(name)!; + working.data = fresh.data; + working.indexes = fresh.indexes; + } + for (const callback of this.deferred.splice(0)) { + this.owner.scheduleTransaction(callback, this.mode); + } + if (!this.accepting) this.commitIfIdle(); + } + + private blocks(later: FakeTransaction): boolean { + return ( + this.active && + (this.mode === "readwrite" || later.mode === "readwrite") && + this.names.some((name) => later.names.includes(name)) + ); + } + + private schedule(callback: () => void): void { + if (this.started) { + this.owner.scheduleTransaction(callback, this.mode); + } else { + this.deferred.push(callback); + } + } + + private deactivateAfterTask(): void { + realSetTimeout(() => { + this.accepting = false; + this.commitIfIdle(); + }, 0); + } + + /** A native transaction with no request left commits once inactive. */ + private commitIfIdle(): void { + if (this.started && this.pending === 0) this.queueCompletion(); + } + + private assertAccepting(): void { + if (!this.active || !this.accepting) { + throw new DOMException( + "The transaction is not active.", + "TransactionInactiveError", + ); + } + } + + private dispatch(handler: () => void): void { + this.accepting = true; + handler(); + this.deactivateAfterTask(); + } + + private finish(): void { + const index = this.database.transactions.indexOf(this); + if (index >= 0) this.database.transactions.splice(index, 1); + for (const transaction of [...this.database.transactions]) { + transaction.startIfUnblocked(); + } } objectStore(name: string): IDBObjectStore { @@ -341,22 +459,23 @@ class FakeTransaction { } request(operation: () => Value): IDBRequest { + this.assertAccepting(); const request = createRequest(); this.pending += 1; - this.owner.scheduleTransaction(() => { + this.schedule(() => { if (!this.active) return; try { request.result = structuredClone(operation()); - request.onsuccess?.(new Event("success")); + this.dispatch(() => request.onsuccess?.(new Event("success"))); } catch (error) { request.error = asException(error); - request.onerror?.(new Event("error")); + this.dispatch(() => request.onerror?.(new Event("error"))); this.abortWith(request.error); } if (!this.active) return; this.pending -= 1; this.queueCompletion(); - }, this.mode); + }); return request as unknown as IDBRequest; } @@ -368,12 +487,13 @@ class FakeTransaction { }>[], direction: IDBCursorDirection, ): IDBRequest { + this.assertAccepting(); const request = createRequest(); let position = 0; this.pending += 1; const emit = () => { - this.owner.scheduleTransaction(() => { + this.schedule(() => { if (!this.active) return; let continued = false; let eventReturned = false; @@ -445,12 +565,12 @@ class FakeTransaction { }, } as unknown as IDBCursorWithValue; } - request.onsuccess?.(new Event("success")); + this.dispatch(() => request.onsuccess?.(new Event("success"))); eventReturned = true; if (continued || !this.active) return; this.pending -= 1; this.queueCompletion(); - }, this.mode); + }); }; emit(); @@ -472,7 +592,7 @@ class FakeTransaction { return; } this.completionQueued = true; - this.owner.scheduleTransaction(() => { + this.schedule(() => { this.completionQueued = false; if (!this.active || this.pending !== 0) return; const commitFailure = @@ -485,18 +605,20 @@ class FakeTransaction { } if (this.mode === "readwrite") { for (const [name, state] of this.workingStores) { - this.owner.replaceStore(name, cloneStore(state)); + this.database.stores.set(name, cloneStore(state)); } } this.active = false; + this.finish(); this.oncomplete?.(new Event("complete")); - }, this.mode); + }); } private abortWith(error: DOMException): void { if (!this.active) return; this.active = false; this.error = error; + this.finish(); this.owner.scheduleLifecycle(() => { this.onerror?.(new Event("error")); this.onabort?.(new Event("abort")); @@ -721,14 +843,36 @@ class FakeIndex { } /** - * Minimal deterministic IndexedDB model for adapter contract tests. It models - * request ordering, transaction-level commit/rollback and upgrade blocking; - * it is not intended to polyfill IndexedDB for application code. + * Minimal deterministic IndexedDB model for adapter contract tests. It is not + * intended to polyfill IndexedDB for application code. + * + * Modeled like a browser: + * - request ordering and transaction-level commit/rollback; + * - one database per name (`open(name)`), so two names never share rows; + * - transactions with overlapping scopes run one after another unless both + * are readonly, and a later one sees what the earlier one committed; + * - a request placed after the transaction's task ended, outside a request + * event and its microtasks, throws `TransactionInactiveError`, and a + * transaction with nothing left to do commits on its own; + * - upgrade blocking, through `blockNextOpen`/`releaseBlockedOpen`. + * + * Not modeled (05-08) — use a browser capability spec for these: + * - key comparison is by `String`/JSON, and a compound (array) index key path + * is not read, so such an index orders by primary key; + * - opening a higher version does not fire `versionchange` on open + * connections, and `onblocked` fires only for `blockNextOpen`; tests drive + * `triggerVersionChange` by hand; + * - the upgrade transaction ends synchronously, so an abort requested from an + * asynchronous step inside `onupgradeneeded` is not rolled back; + * - quota: writes never fail for lack of space unless a test injects it with + * `failNextWriteCommit`. + * + * `seed`, `readRaw` and the lifecycle triggers act on the database opened + * most recently. */ export class MemoryIndexedDbFactory { - private stores = new Map(); - private databaseVersion = 0; - private latestDatabase = new FakeDatabase(this); + private readonly databases = new Map(); + private current: DatabaseState = this.databaseNamed(""); private blockedRequest: Readonly<{ request: MutableOpenRequest; targetVersion: number; @@ -741,8 +885,8 @@ export class MemoryIndexedDbFactory { lastTransaction: FakeTransaction | null = null; readonly factory: IDBFactory = { - open: (_name: string, version?: number) => - this.open(version ?? 1) as unknown as IDBOpenDBRequest, + open: (name: string, version?: number) => + this.open(name, version ?? 1) as unknown as IDBOpenDBRequest, cmp: compareKeys, } as IDBFactory; @@ -782,10 +926,12 @@ export class MemoryIndexedDbFactory { }) as unknown as IDBKeyRange, }; - open(version: number): MutableOpenRequest { - const database = new FakeDatabase(this); - database.version = this.databaseVersion; - this.latestDatabase = database; + open(name: string, version: number): MutableOpenRequest { + const state = this.databaseNamed(name); + const database = new FakeDatabase(this, state); + database.version = state.version; + state.latest = database; + this.current = state; const request: MutableOpenRequest = { ...createRequest(), result: database as unknown as IDBDatabase, @@ -802,7 +948,7 @@ export class MemoryIndexedDbFactory { database, }; request.onblocked?.({ - oldVersion: this.databaseVersion, + oldVersion: state.version, newVersion: version, } as IDBVersionChangeEvent); return; @@ -848,25 +994,25 @@ export class MemoryIndexedDbFactory { } triggerVersionChange(newVersion: number): void { - this.latestDatabase.fireVersionChange(newVersion); + this.current.latest?.fireVersionChange(newVersion); } triggerForcedClose(): void { - this.latestDatabase.fireForcedClose(); + this.current.latest?.fireForcedClose(); } isConnectionClosed(): boolean { - return this.latestDatabase.closed; + return this.current.latest?.closed ?? true; } seed(storeName: string, value: unknown): void { - const state = this.store(storeName); + const state = storeOf(this.current, storeName); const key = primaryKey(state, value); state.data.set(key, structuredClone(value)); } readRaw(storeName: string, key: string): unknown { - const value = this.store(storeName).data.get(key); + const value = storeOf(this.current, storeName).data.get(key); return value === undefined ? undefined : structuredClone(value); } @@ -896,39 +1042,34 @@ export class MemoryIndexedDbFactory { } storeNames(): Iterable { - return this.stores.keys(); + return this.current.stores.keys(); } hasStore(name: string): boolean { - return this.stores.has(name); + return this.current.stores.has(name); } - store(name: string): StoreState { - const state = this.stores.get(name); + private databaseNamed(name: string): DatabaseState { + let state = this.databases.get(name); if (!state) { - throw new DOMException("Store does not exist.", "NotFoundError"); + state = { + stores: new Map(), + version: 0, + latest: null, + transactions: [], + }; + this.databases.set(name, state); } return state; } - createStore(name: string, state: StoreState): void { - this.stores.set(name, state); - } - - replaceStore(name: string, state: StoreState): void { - this.stores.set(name, state); - } - - deleteStore(name: string): boolean { - return this.stores.delete(name); - } - private finishOpen( request: MutableOpenRequest, targetVersion: number, database: FakeDatabase, ): void { - if (targetVersion < this.databaseVersion) { + const state = database.state; + if (targetVersion < state.version) { request.error = new DOMException( "Requested version is older.", "VersionError", @@ -936,9 +1077,9 @@ export class MemoryIndexedDbFactory { request.onerror?.(new Event("error")); return; } - if (targetVersion > this.databaseVersion) { - const before = cloneStores(this.stores); - const oldVersion = this.databaseVersion; + if (targetVersion > state.version) { + const before = cloneStores(state.stores); + const oldVersion = state.version; const upgrade = new FakeUpgradeTransaction(database); request.transaction = upgrade as unknown as IDBTransaction; database.version = targetVersion; @@ -948,7 +1089,7 @@ export class MemoryIndexedDbFactory { } as IDBVersionChangeEvent); request.transaction = null; if (upgrade.aborted) { - this.stores = before; + state.stores = before; database.version = oldVersion; request.error = new DOMException( "Upgrade transaction aborted.", @@ -957,9 +1098,9 @@ export class MemoryIndexedDbFactory { request.onerror?.(new Event("error")); return; } - this.databaseVersion = targetVersion; + state.version = targetVersion; } - database.version = this.databaseVersion; + database.version = state.version; request.result = database as unknown as IDBDatabase; request.onsuccess?.(new Event("success")); } diff --git a/tests/unit/memory-indexeddb-fidelity.test.ts b/tests/unit/memory-indexeddb-fidelity.test.ts new file mode 100644 index 00000000..ad5dc91e --- /dev/null +++ b/tests/unit/memory-indexeddb-fidelity.test.ts @@ -0,0 +1,120 @@ +import { describe, expect, it } from "vitest"; + +import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; + +/** + * 05-08. Where the fake used to part from native IndexedDB, each case pins + * the native result, so a test built on the fake cannot pass on a behavior no + * browser has. + */ + +function settle(request: IDBRequest): Promise { + return new Promise((resolve, reject) => { + request.onsuccess = () => resolve(request.result); + request.onerror = () => reject(request.error); + }); +} + +function outcome(transaction: IDBTransaction): Promise { + return new Promise((resolve) => { + transaction.oncomplete = () => resolve("complete"); + transaction.onabort = () => + resolve(`abort:${transaction.error?.name ?? "none"}`); + }); +} + +async function openWithStore( + memory: MemoryIndexedDbFactory, + name: string, +): Promise { + const request = memory.factory.open(name, 1); + request.onupgradeneeded = () => { + request.result.createObjectStore("s", { keyPath: "k" }); + }; + return await settle(request); +} + +describe("05-08 memory IndexedDB matches native semantics the adapters rely on", () => { + it("(a) runs overlapping readwrite transactions one after another", async () => { + const memory = new MemoryIndexedDbFactory(); + const database = await openWithStore(memory, "a"); + memory.seed("s", { k: "counter", n: 0 }); + const first = database.transaction(["s"], "readwrite"); + const second = database.transaction(["s"], "readwrite"); + const settled = [outcome(first), outcome(second)]; + for (const transaction of [first, second]) { + const read = transaction.objectStore("s").get("counter"); + read.onsuccess = () => { + const { n } = read.result as { n: number }; + transaction.objectStore("s").put({ k: "counter", n: n + 1 }); + }; + } + + expect(await Promise.all(settled)).toEqual(["complete", "complete"]); + expect(memory.readRaw("s", "counter")).toEqual({ k: "counter", n: 2 }); + }); + + it("(b) rejects a request placed after the transaction's task ended", async () => { + const memory = new MemoryIndexedDbFactory(); + const database = await openWithStore(memory, "b"); + const transaction = database.transaction(["s"], "readwrite"); + const settled = outcome(transaction); + await new Promise((resolve) => setTimeout(resolve, 5)); + + expect(() => + transaction.objectStore("s").put({ k: "late" }), + ).toThrow(expect.objectContaining({ name: "TransactionInactiveError" })); + // A transaction with no request left commits on its own. + expect(await settled).toBe("complete"); + expect(memory.readRaw("s", "late")).toBeUndefined(); + }); + + it("(b) keeps a transaction active for requests placed in a success callback's microtasks", async () => { + const memory = new MemoryIndexedDbFactory(); + const database = await openWithStore(memory, "b2"); + const transaction = database.transaction(["s"], "readwrite"); + const settled = outcome(transaction); + const read = transaction.objectStore("s").get("absent"); + read.onsuccess = () => { + void Promise.resolve().then(() => { + transaction.objectStore("s").put({ k: "chained" }); + }); + }; + + expect(await settled).toBe("complete"); + expect(memory.readRaw("s", "chained")).toEqual({ k: "chained" }); + }); + + it("(d) keeps databases of different names apart", async () => { + const memory = new MemoryIndexedDbFactory(); + const userA = await openWithStore(memory, "user-A"); + await settle( + userA.transaction(["s"], "readwrite").objectStore("s").put({ + k: "secret-of-A", + }), + ); + let upgraded = false; + const request = memory.factory.open("user-B", 1); + request.onupgradeneeded = () => { + upgraded = true; + request.result.createObjectStore("s", { keyPath: "k" }); + }; + const userB = await settle(request); + + expect(upgraded).toBe(true); + expect( + await settle( + userB.transaction(["s"], "readonly").objectStore("s").get( + "secret-of-A", + ), + ), + ).toBeUndefined(); + expect( + await settle( + userA.transaction(["s"], "readonly").objectStore("s").get( + "secret-of-A", + ), + ), + ).toEqual({ k: "secret-of-A" }); + }); +}); From 3e37fbf0ed108d92d0ce809bcccb0d1b30ba0e10 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:24:55 +0900 Subject: [PATCH 04/14] fix(storage): delete a partition's IndexedDB dataset when an authorized purge cannot open it (05-03) LOGOUT and ACCOUNT_DELETION purged row by row and so needed an open that a corrupt budget or binding row always rejected, leaving personal rows on the device. After authority approval, a purge that finds the dataset rejected by admission now deletes that partition's own database and reports it; healthy datasets and other partitions are untouched. Co-Authored-By: Claude Opus 5.5 --- .../browser-file-storage-recovery.md | 19 ++- src/adapters/platform/indexeddb-connection.ts | 6 +- .../storage/indexeddb/indexeddb-runtime.ts | 53 +++++- .../browser-file-storage/indexeddb-port.ts | 7 + .../indexeddb-runtime.spec.ts | 127 ++++++++++++++- tests/helpers/memory-indexeddb.ts | 57 ++++++- tests/unit/indexeddb-runtime.test.ts | 153 ++++++++++++++++++ 7 files changed, 412 insertions(+), 10 deletions(-) diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 6a583216..7a90213c 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -36,6 +36,9 @@ primitive를 coordinator 완료 증거로 사용하지 않는다. incident 중에도 다음 작업은 금지한다. - 자동 또는 일괄 `deleteDatabase()` + - 예외는 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된 + governance 때문에 dataset을 열 수 없을 때, runtime이 그 partition의 DB + 하나만 지운다(§5 "database 전체 삭제" 참고). - origin의 모든 `caches.keys()` 삭제 - user-authored/unsynced IndexedDB 또는 OPFS data 자동 purge - schema version downgrade @@ -248,7 +251,21 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다. proof를 운영자가 수동 생성·재사용하지 않음 database 전체 삭제는 data owner가 export/recovery와 영향 scope를 승인한 별도 -action이다. +action이다. runtime이 스스로 DB를 지우는 경우는 하나뿐이다(05-03). + +- 조건: `enforceLifecycleBatch`의 action이 `LOGOUT` 또는 `ACCOUNT_DELETION`이고, + `authorizeLifecycle`이 proof를 내준 뒤, open이 `POLICY_REJECTED` 또는 + `CORRUPT_DATA`로 실패했을 때(budget/binding 행 손상, 바뀐 policy). 행 단위 + purge는 open이 필요해서 이 상태에서는 영영 돌 수 없다 + (`src/adapters/storage/indexeddb/indexeddb-runtime.ts` `deleteUnadmittedDataset`). +- 범위: 세 opaque token에서 만든 그 partition의 DB 이름 하나 + (`indexeddb-governance.ts` `indexedDbPhysicalDatabaseName`). 다른 partition과 + origin의 다른 DB는 건드리지 않는다. +- 결과: 지워지면 receipt `COMPLETE`와 `datasetDeleted: true`(행 수는 세지 + 않는다). 다른 context가 연결을 닫지 않아 blocked deadline이 지나면 `BLOCKED` + / `RELOAD_OTHER_CONTEXTS`를 반환한다. 이때 삭제 요청은 브라우저에 살아 있어 + 나중에 적용될 수 있으므로 다른 tab을 닫고 같은 purge를 다시 호출한다. +- governance가 정상이면 지금처럼 행 단위 purge만 하고 DB는 지우지 않는다. 성공 판정: diff --git a/src/adapters/platform/indexeddb-connection.ts b/src/adapters/platform/indexeddb-connection.ts index 29015b51..b7476442 100644 --- a/src/adapters/platform/indexeddb-connection.ts +++ b/src/adapters/platform/indexeddb-connection.ts @@ -605,9 +605,9 @@ export function createIndexedDbConnection( /** * In this module because it is the same `IDBOpenDBRequest` state machine as - * `openIndexedDbDatabase`, not because three subsystems need it — only - * `indexeddb-checkpoint-store.ts` deletes a database, and nothing here asks the - * other three to start. Leaving it out would leave a third hand-written copy of + * `openIndexedDbDatabase`. Two callers delete a database: + * `indexeddb-checkpoint-store.ts`, and the IndexedDB runtime's authorized + * LOGOUT/ACCOUNT_DELETION purge when its dataset fails admission. Leaving it out would leave a third hand-written copy of * the settle-once blocked-deadline latch eight lines away from the kernel's. * * There is deliberately no `signal`: the request cannot be cancelled after diff --git a/src/adapters/storage/indexeddb/indexeddb-runtime.ts b/src/adapters/storage/indexeddb/indexeddb-runtime.ts index ad4e4926..d4bbc4ec 100644 --- a/src/adapters/storage/indexeddb/indexeddb-runtime.ts +++ b/src/adapters/storage/indexeddb/indexeddb-runtime.ts @@ -24,6 +24,7 @@ import { import { snapshotAbortTimers } from "../../platform/abortable-operation.ts"; import { createIndexedDbConnection, + deleteIndexedDbDatabase, openIndexedDbDatabase, type IndexedDbTranslate, } from "../../platform/indexeddb-connection.ts"; @@ -2500,7 +2501,9 @@ export function createIndexedDbRuntime( cutoffEpochMs, ); } else { - result = await purgePartitionRecords(input, deadline); + result = + (await deleteUnadmittedDataset(input.signal)) ?? + (await purgePartitionRecords(input, deadline)); } return observeResult( operation, @@ -2509,6 +2512,54 @@ export function createIndexedDbRuntime( ); } + /** + * 05-03. A LOGOUT or ACCOUNT_DELETION purge must not depend on the dataset + * passing admission: a corrupt governance row rejects every open, so no row + * could ever be purged one by one. The authority has already approved this + * purge, and the database name comes from this partition's own tokens, so + * deleting the whole database touches no other partition. Returns `null` + * when a connection is ready for the row-by-row purge. + */ + async function deleteUnadmittedDataset( + signal: AbortSignal | undefined, + ): Promise | null> { + if (connection.current()) return null; + const opened = await open(signal); + if (opened.ok) return null; + if ( + (opened.error.code !== "POLICY_REJECTED" && + opened.error.code !== "CORRUPT_DATA") || + disposed || + typeof factory?.deleteDatabase !== "function" + ) { + return opened; + } + const deleted = await deleteIndexedDbDatabase({ + factory, + databaseName, + translate: translateFor("INDEXEDDB_WRITE"), + blockedTimeoutMs, + timers, + }); + if (!deleted.ok) return deleted; + if (deleted.value.kind === "BLOCKED_DEADLINE") { + // The request is still live and may yet land; the next call finds out. + return browserDataFailure("BLOCKED", "INDEXEDDB_WRITE", { + retryable: true, + recovery: "RELOAD_OTHER_CONTEXTS", + }); + } + return browserDataSuccess( + Object.freeze({ + state: "COMPLETE" as const, + scannedRows: 0, + deletedRows: 0, + budgetExhausted: false, + datasetDeleted: true as const, + }), + ); + } + function close(): void { if (disposed) return; disposed = true; diff --git a/src/application/ports/browser-file-storage/indexeddb-port.ts b/src/application/ports/browser-file-storage/indexeddb-port.ts index cf71d6f3..9c81a893 100644 --- a/src/application/ports/browser-file-storage/indexeddb-port.ts +++ b/src/application/ports/browser-file-storage/indexeddb-port.ts @@ -144,6 +144,13 @@ export type IndexedDbLifecycleBatchReceipt = Readonly<{ scannedRows: number; deletedRows: number; budgetExhausted: boolean; + /** + * 05-03. Present when an authorized LOGOUT or ACCOUNT_DELETION found the + * dataset's governance rows unreadable, so no row could be purged one by + * one, and deleted the partition's whole database instead. Rows are then + * not counted. + */ + datasetDeleted?: true; }>; export type IndexedDbLifecycleAuthorityRequest = Readonly<{ diff --git a/tests/browser-capabilities/indexeddb-runtime.spec.ts b/tests/browser-capabilities/indexeddb-runtime.spec.ts index feeba8c7..775d5f59 100644 --- a/tests/browser-capabilities/indexeddb-runtime.spec.ts +++ b/tests/browser-capabilities/indexeddb-runtime.spec.ts @@ -23,12 +23,14 @@ async function startLifecycleRuntime( name: string, targetVersion: 1 | 2, blockedTimeoutMs = 1_000, + partitioned = false, ): Promise { await page.evaluate( async ({ currentDatabaseName, currentTargetVersion, currentBlockedTimeoutMs, + currentPartitioned, }) => { const modulePath = "/src/adapters/storage/indexeddb/indexeddb-runtime.ts"; @@ -38,24 +40,31 @@ async function startLifecycleRuntime( type LifecycleValue = Readonly<{ value: string }>; const [authorityToken, namespaceToken, partitionToken] = currentDatabaseName.slice("ca-idb-v1:".length).split("."); + const accountScope = currentPartitioned + ? ("OPAQUE_PARTITION" as const) + : ("ORIGIN_SHARED" as const); const scope = { authorityToken, namespaceToken, partitionToken, - accountScope: "ORIGIN_SHARED" as const, + accountScope, }; const storagePolicy = { owner: "platform-storage", namespace: "indexeddb-browser-lifecycle", classification: "INTERNAL" as const, authority: "SERVER" as const, - accountScope: "ORIGIN_SHARED" as const, + accountScope, retention: { kind: "EXPLICIT_DELETE" as const }, softBudgetBytes: 1_000_000, hardBudgetBytes: 2_000_000, evictionPriority: "SYNCED_COPY" as const, - logoutAction: "KEEP_ORIGIN_SHARED" as const, - accountDeletionAction: "KEEP_ORIGIN_SHARED" as const, + logoutAction: currentPartitioned + ? ("PURGE_PARTITION" as const) + : ("KEEP_ORIGIN_SHARED" as const), + accountDeletionAction: currentPartitioned + ? ("PURGE_PARTITION" as const) + : ("KEEP_ORIGIN_SHARED" as const), pressureAction: "RETAIN" as const, unavailableFallback: "ONLINE_ONLY" as const, }; @@ -184,6 +193,7 @@ async function startLifecycleRuntime( currentDatabaseName: name, currentTargetVersion: targetVersion, currentBlockedTimeoutMs: blockedTimeoutMs, + currentPartitioned: partitioned, }, ); } @@ -1067,3 +1077,112 @@ test("fails a blocked v2 upgrade closed, then closes its late connection after t await blockerPage.close(); } }); + +test("05-03 deletes a partition's dataset for an authorized ACCOUNT_DELETION when its budget row is corrupt", async ({ + page, +}) => { + const name = databaseName("corrupt-governance"); + await page.goto("/"); + await startLifecycleRuntime(page, name, 1, 1_000, true); + expect(await settleLifecycleRuntime(page)).toMatchObject({ + opened: { ok: true }, + }); + expect( + await page.evaluate(async () => { + const runtime = ( + globalThis as unknown as { + __indexedDbLifecycleRuntime: { + compareAndSwap(input: unknown): Promise; + close(): void; + }; + } + ).__indexedDbLifecycleRuntime; + const written = await runtime.compareAndSwap({ + key: "personal-1", + value: { value: "mine" }, + expectedRevision: null, + idempotencyKey: "personal-create", + }); + runtime.close(); + return written; + }), + ).toMatchObject({ ok: true }); + expect( + await page.evaluate( + async (currentDatabaseName) => + await new Promise((resolve) => { + const request = indexedDB.open(currentDatabaseName, 1); + request.onerror = () => + resolve(request.error?.name ?? "UNKNOWN_ERROR"); + request.onsuccess = () => { + const database = request.result; + const transaction = database.transaction( + "governance", + "readwrite", + ); + transaction.objectStore("governance").put({ + bindingKey: "dataset-budget", + budgetVersion: 1, + usedBytes: -5, + receiptCount: 1, + }); + transaction.oncomplete = () => { + database.close(); + resolve("CORRUPTED"); + }; + transaction.onabort = () => { + database.close(); + resolve("ABORTED"); + }; + }; + }), + name, + ), + ).toBe("CORRUPTED"); + + await startLifecycleRuntime(page, name, 1, 1_000, true); + expect(await settleLifecycleRuntime(page)).toMatchObject({ + opened: { ok: false, error: { code: "POLICY_REJECTED" } }, + }); + const purged = await page.evaluate(async () => { + const runtime = ( + globalThis as unknown as { + __indexedDbLifecycleRuntime: { + enforceLifecycleBatch(input: unknown): Promise; + }; + } + ).__indexedDbLifecycleRuntime; + return await runtime.enforceLifecycleBatch({ + action: "ACCOUNT_DELETION", + maxRows: 100, + maxDurationMs: 5_000, + }); + }); + expect(purged).toMatchObject({ + ok: true, + value: { state: "COMPLETE", datasetDeleted: true }, + }); + const remaining = await page.evaluate(async (currentDatabaseName) => { + ( + globalThis as unknown as { + __indexedDbLifecycleRuntime?: { close(): void }; + } + ).__indexedDbLifecycleRuntime?.close(); + // A fresh open of a deleted database runs its upgrade from version 0. + return await new Promise((resolve, reject) => { + const request = indexedDB.open(currentDatabaseName); + let oldVersion = -1; + request.onupgradeneeded = (event) => { + oldVersion = event.oldVersion; + }; + request.onsuccess = () => { + request.result.close(); + const deletion = indexedDB.deleteDatabase(currentDatabaseName); + deletion.onsuccess = () => resolve(oldVersion); + deletion.onerror = () => reject(deletion.error); + }; + request.onerror = () => reject(request.error); + }); + }, name); + expect(remaining).toBe(0); +}); diff --git a/tests/helpers/memory-indexeddb.ts b/tests/helpers/memory-indexeddb.ts index 7eae6491..a8746881 100644 --- a/tests/helpers/memory-indexeddb.ts +++ b/tests/helpers/memory-indexeddb.ts @@ -29,8 +29,12 @@ type DatabaseState = { stores: Map; version: number; latest: FakeDatabase | null; + /** Connections handed out by a successful open, closed or not. */ + connections: FakeDatabase[]; /** Transactions that have not finished, in creation order. */ transactions: FakeTransaction[]; + /** A `deleteDatabase` waiting for the open connections to close. */ + pendingDelete: (() => void) | null; }; function storeOf(state: DatabaseState, name: string): StoreState { @@ -314,9 +318,10 @@ class FakeDatabase { close(): void { this.closed = true; + this.state.pendingDelete?.(); } - fireVersionChange(newVersion: number): void { + fireVersionChange(newVersion: number | null): void { this.onversionchange?.({ oldVersion: this.version, newVersion, @@ -887,6 +892,8 @@ export class MemoryIndexedDbFactory { readonly factory: IDBFactory = { open: (name: string, version?: number) => this.open(name, version ?? 1) as unknown as IDBOpenDBRequest, + deleteDatabase: (name: string) => + this.deleteDatabase(name) as unknown as IDBOpenDBRequest, cmp: compareKeys, } as IDBFactory; @@ -958,6 +965,51 @@ export class MemoryIndexedDbFactory { return request; } + /** + * Like a browser: open connections get `versionchange` (new version + * `null`); if any stays open the request reports `blocked` and completes + * once the last one closes. The name then holds an empty version-0 + * database, so `hasStore` answers false. + */ + deleteDatabase(name: string): MutableOpenRequest { + const request: MutableOpenRequest = { + ...createRequest(), + transaction: null, + onblocked: null, + onupgradeneeded: null, + }; + queueMicrotask(() => { + const state = this.databaseNamed(name); + const oldVersion = state.version; + const finish = () => { + if (state.connections.some((connection) => !connection.closed)) { + return; + } + state.pendingDelete = null; + state.stores = new Map(); + state.version = 0; + state.connections = []; + request.onsuccess?.({ + oldVersion, + newVersion: null, + } as unknown as Event); + }; + for (const connection of state.connections) { + if (!connection.closed) connection.fireVersionChange(null); + } + if (state.connections.some((connection) => !connection.closed)) { + state.pendingDelete = finish; + request.onblocked?.({ + oldVersion, + newVersion: null, + } as IDBVersionChangeEvent); + return; + } + finish(); + }); + return request; + } + blockNextOpen(): void { this.shouldBlockNextOpen = true; } @@ -1056,7 +1108,9 @@ export class MemoryIndexedDbFactory { stores: new Map(), version: 0, latest: null, + connections: [], transactions: [], + pendingDelete: null, }; this.databases.set(name, state); } @@ -1101,6 +1155,7 @@ export class MemoryIndexedDbFactory { state.version = targetVersion; } database.version = state.version; + state.connections.push(database); request.result = database as unknown as IDBDatabase; request.onsuccess?.(new Event("success")); } diff --git a/tests/unit/indexeddb-runtime.test.ts b/tests/unit/indexeddb-runtime.test.ts index dbe64ac8..6103db7e 100644 --- a/tests/unit/indexeddb-runtime.test.ts +++ b/tests/unit/indexeddb-runtime.test.ts @@ -1453,3 +1453,156 @@ describe("IndexedDB runtime", () => { expect(hardMemory.readRaw("records", "x")).toBeUndefined(); }); }); + +describe("05-03 a LOGOUT or ACCOUNT_DELETION purge survives corrupt governance", () => { + const partitionScope = { + ...TEST_SCOPE, + accountScope: "OPAQUE_PARTITION" as const, + }; + const otherScope = { + ...partitionScope, + partitionToken: "partitiontoken_002", + }; + const partitionPolicy = { + ...TEST_STORAGE_POLICY, + accountScope: "OPAQUE_PARTITION" as const, + logoutAction: "PURGE_PARTITION" as const, + accountDeletionAction: "PURGE_PARTITION" as const, + }; + const batch = { maxRows: 100, maxDurationMs: 1_000 } as const; + + /** + * Another partition and this one each hold a record in one factory; this + * partition's budget row is then corrupted, so a fresh runtime cannot pass + * admission (E1). + */ + async function corruptedPartition( + authorizeLifecycle: IndexedDbRuntimeDependencies< + Item, + Item, + Query + >["authorizeLifecycle"] = () => ({ + authorized: true, + proofToken: "authorityproof_001", + }), + ) { + const memory = new MemoryIndexedDbFactory(); + const other = createIndexedDbRuntime( + dependencies(memory, { + scope: otherScope, + storagePolicy: partitionPolicy, + }), + ); + expect(await other.open()).toMatchObject({ ok: true }); + await other.compareAndSwap({ + key: "kept", + value: { label: "other", rank: 1 }, + expectedRevision: null, + idempotencyKey: "kept-create", + }); + const writer = createIndexedDbRuntime( + dependencies(memory, { + scope: partitionScope, + storagePolicy: partitionPolicy, + }), + ); + expect(await writer.open()).toMatchObject({ ok: true }); + await writer.compareAndSwap({ + key: "personal-1", + value: { label: "mine", rank: 1 }, + expectedRevision: null, + idempotencyKey: "personal-create", + }); + writer.close(); + memory.seed("governance", { + bindingKey: "dataset-budget", + budgetVersion: 1, + usedBytes: -5, + receiptCount: 1, + }); + const deleteDatabase = vi.spyOn(memory.factory, "deleteDatabase"); + const fresh = createIndexedDbRuntime( + dependencies(memory, { + scope: partitionScope, + storagePolicy: partitionPolicy, + authorizeLifecycle, + }), + ); + expect(await fresh.open()).toMatchObject({ + ok: false, + error: { code: "POLICY_REJECTED" }, + }); + return { memory, other, fresh, deleteDatabase }; + } + + it.each(["LOGOUT", "ACCOUNT_DELETION"] as const)( + "deletes the partition's whole dataset for an authorized %s and leaves other partitions alone", + async (action) => { + const { memory, other, fresh, deleteDatabase } = + await corruptedPartition(); + + expect( + await fresh.enforceLifecycleBatch({ action, ...batch }), + ).toMatchObject({ + ok: true, + value: { state: "COMPLETE", datasetDeleted: true }, + }); + expect(deleteDatabase).toHaveBeenCalledTimes(1); + expect(deleteDatabase).toHaveBeenCalledWith( + indexedDbPhysicalDatabaseName(partitionScope), + ); + expect(memory.hasStore("records")).toBe(false); + expect(await other.read("kept")).toMatchObject({ + ok: true, + value: { value: { label: "other", rank: 1 } }, + }); + }, + ); + + it("keeps the dataset when the authority does not approve", async () => { + const { memory, fresh, deleteDatabase } = await corruptedPartition( + () => ({ authorized: false }), + ); + + expect( + await fresh.enforceLifecycleBatch({ action: "ACCOUNT_DELETION", ...batch }), + ).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" } }); + expect(deleteDatabase).not.toHaveBeenCalled(); + expect(memory.readRaw("records", "personal-1")).toBeDefined(); + }); + + it("purges row by row, never the database, when governance is healthy", async () => { + const memory = new MemoryIndexedDbFactory(); + const deleteDatabase = vi.spyOn(memory.factory, "deleteDatabase"); + const runtime = createIndexedDbRuntime( + dependencies(memory, { + scope: partitionScope, + storagePolicy: partitionPolicy, + }), + ); + expect(await runtime.open()).toMatchObject({ ok: true }); + await runtime.compareAndSwap({ + key: "personal-1", + value: { label: "mine", rank: 1 }, + expectedRevision: null, + idempotencyKey: "personal-create", + }); + runtime.close(); + const fresh = createIndexedDbRuntime( + dependencies(memory, { + scope: partitionScope, + storagePolicy: partitionPolicy, + }), + ); + + const purged = await fresh.enforceLifecycleBatch({ + action: "LOGOUT", + ...batch, + }); + expect(purged).toMatchObject({ ok: true, value: { state: "COMPLETE" } }); + expect(purged.ok && purged.value).not.toHaveProperty("datasetDeleted"); + expect(deleteDatabase).not.toHaveBeenCalled(); + expect(memory.hasStore("records")).toBe(true); + expect(memory.readRaw("records", "personal-1")).toBeUndefined(); + }); +}); From 6ab564f376b3f7c66d25ff6cc7044bf03f3d5842 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:29:07 +0900 Subject: [PATCH 05/14] fix(storage): sweep a purged OPFS partition's chunks without the GC grace (05-04) A LOGOUT or ACCOUNT_DELETION purge removed object directories only; chunk bytes stayed until a GC 24 h later that might never run for that user. Once every object is gone the purge now sweeps the partition's unreferenced chunks at once and reports how the sweep ended. Chunks the journal or a staged put still references are kept. Co-Authored-By: Claude Opus 5.5 --- .../browser-file-storage-recovery.md | 6 + .../storage/opfs/opfs-byte-store-adapter.ts | 31 ++++- .../ports/browser-file-storage/opfs-ports.ts | 6 + tests/unit/opfs-worker-runtime.test.ts | 112 +++++++++++++++++- 4 files changed, 148 insertions(+), 7 deletions(-) diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 7a90213c..cdb10c69 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -394,6 +394,12 @@ VD-15 목표 runtime을 먼저 구현한다. - `COMMITTED` + file missing/corrupt: reconstructable만 server rehydrate; user-created private는 read-only/export/recovery - stale staging/orphan chunk는 grace period와 bounded mark/sweep 후 제거 +- `LOGOUT`/`ACCOUNT_DELETION` purge는 객체를 모두 지운 뒤 그 partition의 chunk를 + grace 없이 sweep한다(05-04, `opfs-byte-store-adapter.ts` `enforcePolicies`). + journal이나 staging receipt가 참조하는 chunk는 이때도 지우지 않는다. report의 + `chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다. `DEADLINE_REACHED`면 같은 + purge를 다시 호출하고, `STAGING_STATE_UNREADABLE`이면 읽을 수 없는 staging부터 + 처리한다 - lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only - scope binding mismatch면 affected scope를 read-only로 격리하고 registry/ composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지 diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index e840bec6..fa803da7 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -846,12 +846,38 @@ export function createOpfsByteStoreAdapter( afterObjectId = page.value.nextObjectId; moreObjectsAvailable = page.value.moreAvailable; } + // 05-04. Removing an object leaves its chunks, and GC only takes a + // chunk 24 h after it was written, so a purged user's bytes stayed on + // the device. Once every object is gone the partition's chunks are swept + // without that grace. The sweep still skips any chunk the journal or a + // staged put references. + let chunkSweep: OpfsPolicyMaintenanceReport["chunkSweep"]; + if ( + (request.reason === "LOGOUT" || + request.reason === "ACCOUNT_DELETION") && + !moreObjectsAvailable && + !deadlineReached && + !request.signal?.aborted + ) { + const swept = await reconcileOrphanChunks( + deadline, + request.signal, + now(), + ); + if (!swept.ok) return rebaseFailure(swept.error, "OBJECT_RECONCILE"); + chunkSweep = swept.value.status; + if (chunkSweep === "DEADLINE_REACHED") { + deadlineReached = true; + moreObjectsAvailable = true; + } + } const report: OpfsPolicyMaintenanceReport = Object.freeze({ inspectedObjects, removedObjects, releasedBytes, moreObjectsAvailable, deadlineReached, + ...(chunkSweep ? { chunkSweep } : {}), }); return browserDataSuccess(report); }, @@ -1188,6 +1214,7 @@ export function createOpfsByteStoreAdapter( async function reconcileOrphanChunks( deadline: number, signal: AbortSignal | undefined, + olderThanEpochMs = Math.max(0, now() - policy.orphanGracePeriodMs), ): Promise< BrowserDataResult< Readonly<{ @@ -1200,10 +1227,6 @@ export function createOpfsByteStoreAdapter( }> > > { - const olderThanEpochMs = Math.max( - 0, - now() - policy.orphanGracePeriodMs, - ); let inspected = 0; let deleted = 0; // R-5.1. Candidates include committed chunks, so a page can be all diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index d3e0fee5..fdc2d3d1 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -119,6 +119,12 @@ export type OpfsPolicyMaintenanceReport = Readonly<{ releasedBytes: number; moreObjectsAvailable: boolean; deadlineReached: boolean; + /** + * 05-04. LOGOUT and ACCOUNT_DELETION only, once every object is removed: + * how the sweep of the partition's now unreferenced chunks ended. Chunk + * bytes are gone only when it is `COMPLETED`. + */ + chunkSweep?: "COMPLETED" | "DEADLINE_REACHED" | "STAGING_STATE_UNREADABLE"; }>; export type OpfsSensitiveMaintenanceReason = diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index a7f93f27..3c3a6a52 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -2094,7 +2094,11 @@ function sharedRootTabs(policy = runtimePolicy) { const root = new MemoryDirectory(); const leases = exclusiveLeases(); const idb = new MemoryIndexedDbFactory(); - const tab = (tag: string) => { + const tab = ( + tag: string, + extra: Partial[0]> = {}, + ) => { + const tabScope = extra.scope ?? scopeA; const runtime = createOpfsWorkerRuntime({ root: root as unknown as FileSystemDirectoryHandle, crypto: globalThis.crypto, @@ -2106,15 +2110,16 @@ function sharedRootTabs(policy = runtimePolicy) { let sequence = 0; return createOpfsByteStoreAdapter({ journal: createIndexedDbOpfsJournal({ - authorityToken: scopeA.authorityToken, + authorityToken: tabScope.authorityToken, factory: idb.factory, keyRange: idb.keyRange, }), worker: loopbackGateway(runtime, policy), - scope: scopeA, + scope: tabScope, storagePolicy, policy, createTransactionId: () => `transaction_${tag}_${++sequence}`, + ...extra, }); }; return { root, leases, idb, tab }; @@ -2292,3 +2297,104 @@ describe("05-02 an empty receipt left by a failed first write is no receipt", () expect(await put()).toMatchObject({ ok: true, value: { generation: 1 } }); }); }); + +describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes behind", () => { + const scopeP2: OpfsStorageScope = Object.freeze({ + ...scopeA, + partitionToken: "partition_87654321", + }); + const authority = { + requestMaintenanceAuthority: () => ({ + authorized: true as const, + proofToken: "proof_token_1234567890", + expiresAtEpochMs: Date.now() + 60_000, + }), + consumeMaintenanceAuthority: () => true, + }; + + function filesUnder(root: MemoryDirectory, scope: OpfsStorageScope): string[] { + const files: string[] = []; + const walk = (directory: MemoryDirectory, path: string) => { + for (const [name, node] of directory.children) { + if (node instanceof MemoryDirectory) walk(node, `${path}/${name}`); + else files.push(`${path}/${name}`); + } + }; + const partition = [ + "authorities", + scope.authorityToken, + scope.namespaceToken, + scope.partitionToken, + ].reduce( + (node, segment) => + node instanceof MemoryDirectory ? node.children.get(segment) : node, + root, + ); + if (partition instanceof MemoryDirectory) walk(partition, ""); + return files; + } + + const putBytes = ( + adapter: ReturnType, + objectId: string, + bytes: number[], + ) => + adapter.objects.put({ + objectId, + expectedGeneration: null, + mediaType: "application/octet-stream", + source: bytesSource(new Uint8Array(bytes)), + }); + + it.each(["LOGOUT", "ACCOUNT_DELETION"] as const)( + "removes the chunks of a %s-purged partition and keeps other partitions", + async (reason) => { + const { root, tab } = sharedRootTabs(); + const purged = tab("p", authority); + const kept = tab("k", { ...authority, scope: scopeP2 }); + expect(await putBytes(purged, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); + expect(await putBytes(purged, "object_secret_2", [4, 5])).toMatchObject({ ok: true }); + expect(await putBytes(kept, "object_kept_0001", [7, 7])).toMatchObject({ ok: true }); + + expect(await purged.maintenance.enforcePolicies({ reason })).toMatchObject({ + ok: true, + value: { + removedObjects: 2, + moreObjectsAvailable: false, + deadlineReached: false, + chunkSweep: "COMPLETED", + }, + }); + expect(filesUnder(root, scopeA)).toEqual([]); + expect(await openedBytes(kept, "object_kept_0001")).toEqual({ + generation: 1, + bytes: [7, 7], + }); + }, + ); + + it("never sweeps the chunk of a put that runs while the purge does", async () => { + const { tab } = sharedRootTabs(); + const purger = tab("p", authority); + const writer = tab("w", authority); + expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); + const stalled = stalledSource(); + const put = writer.objects.put({ + objectId: "object_late_0001", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: stalled.source, + }); + await stalled.streaming; + const purge = purger.maintenance.enforcePolicies({ reason: "LOGOUT" }); + await new Promise((resolve) => setTimeout(resolve, 20)); + stalled.release(); + + expect(await put).toMatchObject({ ok: true }); + expect(await purge).toMatchObject({ ok: true, value: { removedObjects: 1 } }); + expect(await openedBytes(writer, "object_late_0001")).toEqual({ + generation: 1, + bytes: [5], + }); + }); +}); From b87ab5ee8ef74eef0c564919219284d177ec662a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:33:44 +0900 Subject: [PATCH 06/14] fix(storage): let retention sweep and receipt prune step over a corrupt row (05-05) One corrupt sidecar or receipt stopped every later sweep or prune, so expired rows stayed on the device and receipts grew until all writes failed LIMIT_EXCEEDED. Both now leave the corrupt row, count it and report it as one CORRUPT_DATA observation, and keep a budget they cannot account for as it is. A malformed budget row in prune now fails as CORRUPT_DATA, not MIGRATION_FAILED. Co-Authored-By: Claude Opus 5.5 --- .../browser-file-storage-recovery.md | 6 ++ .../indexeddb/indexeddb-maintenance.ts | 39 ++++++-- .../storage/indexeddb/indexeddb-runtime.ts | 42 ++++++--- tests/unit/indexeddb-maintenance.test.ts | 37 ++++++++ tests/unit/indexeddb-runtime.test.ts | 94 ++++++++++++++++--- 5 files changed, 188 insertions(+), 30 deletions(-) diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index cdb10c69..ca969f33 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -199,6 +199,12 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다. - `MIGRATION_FAILED`, unknown codec, schema postcondition failure - `CORRUPT_DATA`, `NOT_READABLE`, forced close + - `RETENTION_SWEEP`(`INDEXEDDB_WRITE`)과 `pruneExpiredReceipts` + (`INDEXEDDB_MIGRATE`)의 `CORRUPT_DATA` 관측은 실패가 아니다. 손상 행을 지우지 + 않고 건너뛴 수이고, 나머지 정상 행은 정리된다(05-05, + `indexeddb-runtime.ts` `purgeEligibleRecords`, + `indexeddb-maintenance.ts` `pruneExpiredReceipts`). budget이 삭제 bytes나 + receipt 수를 감당하지 못하면 그 값은 내리지 않고 둔다 - transaction request success 후 commit failure - `LIMIT_EXCEEDED`: dataset logical byte/receipt budget 초과 - lifecycle batch가 proof 없이 실행되거나 TTL/UNTIL_SYNCED record가 잘못 노출·삭제 diff --git a/src/adapters/storage/indexeddb/indexeddb-maintenance.ts b/src/adapters/storage/indexeddb/indexeddb-maintenance.ts index 3bedea47..7d8debee 100644 --- a/src/adapters/storage/indexeddb/indexeddb-maintenance.ts +++ b/src/adapters/storage/indexeddb/indexeddb-maintenance.ts @@ -146,6 +146,14 @@ function migrationFailure(): BrowserDataFailure { return failureOf(migrationFailed()); } +function corruptFailure(): BrowserDataFailure { + return failureOf( + browserDataFailure("CORRUPT_DATA", "INDEXEDDB_MIGRATE", { + recovery: "READ_ONLY", + }), + ); +} + function unsupportedFailure(): BrowserDataFailure { return failureOf(unsupported()); } @@ -1124,6 +1132,11 @@ export function createIndexedDbMaintenance( const opened = await openExactVersion(input.signal); if (!opened.ok) return observeResult(opened); const database = opened.value; + // 05-05. A corrupt receipt is left in place and counted, not a stop: one + // bad row used to end every later prune, so receipts piled up until every + // write failed with LIMIT_EXCEEDED. A receipt count already at zero stays + // there. Both are reported as one CORRUPT_DATA observation. + let corruptRows = 0; try { const pruned = await runTransaction< @@ -1188,8 +1201,8 @@ export function createIndexedDbMaintenance( String(cursor.primaryKey) || cursor.value.expiresAtEpochMs > cutoff.value ) { - context.fail(migrationFailure()); - return { kind: "SUSPEND" }; + corruptRows += 1; + return { kind: "CONTINUE" }; } let deleteRequest: IDBRequest; try { @@ -1207,11 +1220,14 @@ export function createIndexedDbMaintenance( budgetRequest.onerror = () => context.requestFailed(budgetRequest.error); budgetRequest.onsuccess = () => { - if ( - !isStoredDatasetBudget(budgetRequest.result) || - budgetRequest.result.receiptCount < 1 - ) { - context.fail(migrationFailure()); + if (!isStoredDatasetBudget(budgetRequest.result)) { + context.fail(corruptFailure()); + return; + } + if (budgetRequest.result.receiptCount < 1) { + corruptRows += 1; + deletedRows += 1; + resume({ kind: "CONTINUE" }); return; } const budgetWrite = governance.put({ @@ -1248,6 +1264,15 @@ export function createIndexedDbMaintenance( }); }, ); + if (corruptRows > 0) { + observe({ + operation: "INDEXEDDB_MIGRATE", + outcome: "FAILED", + schemaVersion: dependencies.schemaVersion, + countBucket: countBucket(corruptRows), + failureCode: "CORRUPT_DATA", + }); + } return observeResult( pruned, pruned.ok ? pruned.value.deletedRows : 0, diff --git a/src/adapters/storage/indexeddb/indexeddb-runtime.ts b/src/adapters/storage/indexeddb/indexeddb-runtime.ts index d4bbc4ec..564f445c 100644 --- a/src/adapters/storage/indexeddb/indexeddb-runtime.ts +++ b/src/adapters/storage/indexeddb/indexeddb-runtime.ts @@ -2045,12 +2045,21 @@ export function createIndexedDbRuntime( return browserDataSuccess(undefined); } - function purgeEligibleRecords( + /** + * 05-05. Like the partition purge (R-5.4), the sweep never stops on a row it + * cannot read: failing closed left every later expired row on the device and + * failed the next sweep the same way. A corrupt sidecar is left in place, + * counted and reported as one CORRUPT_DATA observation per batch. A budget + * that cannot account for a deleted row's bytes is left as it is: it can + * only read high, which blocks writes and never admits one. + */ + async function purgeEligibleRecords( input: IndexedDbLifecycleBatchInput, deadline: number, cutoffEpochMs: number, ): Promise> { - return runTransaction( + let corruptRows = 0; + const result = await runTransaction( [ dependencies.recordStore, dependencies.governanceStore, @@ -2141,11 +2150,9 @@ export function createIndexedDbRuntime( "UNTIL_SYNCED" && cursor.value.synchronization !== "CONFIRMED") ) { - context.fail(corruptFailure("INDEXEDDB_WRITE")); - // `fail` aborts, so the pump has nowhere to go. Suspending - // without ever resuming says that without claiming a summary - // the sweep never reached. - return { kind: "SUSPEND" }; + scannedRows += 1; + corruptRows += 1; + return { kind: "CONTINUE" }; } scannedRows += 1; const measuredBytes = cursor.value.measuredBytes; @@ -2177,13 +2184,16 @@ export function createIndexedDbRuntime( budgetRequest.onerror = () => context.requestFailed(budgetRequest.error); budgetRequest.onsuccess = () => { - if ( - !isStoredDatasetBudget(budgetRequest.result) || - budgetRequest.result.usedBytes < measuredBytes - ) { + if (!isStoredDatasetBudget(budgetRequest.result)) { context.fail(corruptFailure("INDEXEDDB_WRITE")); return; } + if (budgetRequest.result.usedBytes < measuredBytes) { + corruptRows += 1; + deletedRows += 1; + resume({ kind: "CONTINUE" }); + return; + } const storedBudgetRequest = governance.put({ bindingKey: INDEXEDDB_DATASET_BUDGET_KEY, budgetVersion: 1, @@ -2216,6 +2226,16 @@ export function createIndexedDbRuntime( }); }, ); + if (corruptRows > 0) { + observe({ + operation: "INDEXEDDB_WRITE", + outcome: "FAILED", + schemaVersion: dependencies.schemaVersion, + countBucket: countBucket(corruptRows), + failureCode: "CORRUPT_DATA", + }); + } + return result; } /** diff --git a/tests/unit/indexeddb-maintenance.test.ts b/tests/unit/indexeddb-maintenance.test.ts index 13fd4999..0adee209 100644 --- a/tests/unit/indexeddb-maintenance.test.ts +++ b/tests/unit/indexeddb-maintenance.test.ts @@ -1123,3 +1123,40 @@ describe("Q-6.5-7 stored-row rules stay the same at every call site", () => { ).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" } }); }); }); + +describe("05-05 a receipt prune steps over a corrupt receipt", () => { + it("deletes every expired healthy receipt, leaves the corrupt one and reports CORRUPT_DATA", async () => { + const memory = new MemoryIndexedDbFactory(); + await prepareSchema(memory); + seedReceipt(memory, "expired-a", 100); + seedReceipt(memory, "expired-b", 200); + memory.seed("receipts", { idempotencyKey: "broken", expiresAtEpochMs: 0 }); + const observations: IndexedDbObservation[] = []; + const maintenance = createMaintenance(memory, defaultPolicy(), { + nowEpochMilliseconds: () => 300, + observe: (event) => observations.push(event), + }); + + expect( + await maintenance.pruneExpiredReceipts({ + maxRows: 10, + maxDurationMs: 10_000, + }), + ).toMatchObject({ + ok: true, + value: { state: "COMPLETE", deletedRows: 2 }, + }); + expect(memory.readRaw("receipts", "expired-a")).toBeUndefined(); + expect(memory.readRaw("receipts", "expired-b")).toBeUndefined(); + expect(memory.readRaw("receipts", "broken")).toBeDefined(); + expect( + memory.readRaw("governance", "dataset-budget"), + ).toMatchObject({ receiptCount: 0 }); + expect(observations).toContainEqual( + expect.objectContaining({ + outcome: "FAILED", + failureCode: "CORRUPT_DATA", + }), + ); + }); +}); diff --git a/tests/unit/indexeddb-runtime.test.ts b/tests/unit/indexeddb-runtime.test.ts index 6103db7e..59947308 100644 --- a/tests/unit/indexeddb-runtime.test.ts +++ b/tests/unit/indexeddb-runtime.test.ts @@ -1035,9 +1035,10 @@ describe("IndexedDB runtime", () => { }); }); - it("aborts a sweep whose budget row cannot account for the deleted bytes", async () => { + it("05-05 sweeps a row the budget cannot account for and leaves the budget high", async () => { const memory = new MemoryIndexedDbFactory(); let epochMs = 1_000; + const observations: IndexedDbObservation[] = []; const runtime = createIndexedDbRuntime( dependencies(memory, { storagePolicy: { @@ -1054,6 +1055,7 @@ describe("IndexedDB runtime", () => { authorized: true, proofToken: "sweep_authority_proof_001", }), + observe: (event) => observations.push(event), }), ); expect(await runtime.open()).toMatchObject({ ok: true }); @@ -1066,9 +1068,8 @@ describe("IndexedDB runtime", () => { }), ).toMatchObject({ ok: true }); - // A budget that cannot account for the record's bytes is corrupt, and the - // sweep only discovers it after both deletions have already succeeded - // inside the transaction. + // A budget that cannot account for the record's bytes is corrupt. The + // sweep finds it only after both deletions succeeded in the transaction. memory.seed("governance", { bindingKey: "dataset-budget", budgetVersion: 1, @@ -1085,15 +1086,20 @@ describe("IndexedDB runtime", () => { maxDurationMs: 1_000, }), ).toMatchObject({ - ok: false, - error: { code: "CORRUPT_DATA" }, + ok: true, + value: { state: "COMPLETE", deletedRows: 1 }, }); - // `fail` aborts. Recording the failure without aborting would report the - // same code while letting the two deletions commit against a budget that - // never moved. - expect(aborts.count).toBe(1); - expect(memory.readRaw("records", "sweep-record")).toBeDefined(); - expect(memory.readRaw("retention", "sweep-record")).toBeDefined(); + expect(aborts.count).toBe(0); + expect(memory.readRaw("records", "sweep-record")).toBeUndefined(); + expect(memory.readRaw("retention", "sweep-record")).toBeUndefined(); + // Not lowered below what it cannot account for: a budget that reads high + // blocks writes, one that reads low would admit them. + expect(memory.readRaw("governance", "dataset-budget")).toMatchObject({ + usedBytes: 0, + }); + expect(observations).toContainEqual( + expect.objectContaining({ failureCode: "CORRUPT_DATA" }), + ); }); it("requires lifecycle authority and only deletes sync-confirmed rows", async () => { @@ -1606,3 +1612,67 @@ describe("05-03 a LOGOUT or ACCOUNT_DELETION purge survives corrupt governance", expect(memory.readRaw("records", "personal-1")).toBeUndefined(); }); }); + +describe("05-05 a retention sweep steps over a corrupt row", () => { + it("deletes every expired healthy row, leaves the corrupt sidecar and reports it", async () => { + const memory = new MemoryIndexedDbFactory(); + let epochMs = 1_000; + const observations: IndexedDbObservation[] = []; + const runtime = createIndexedDbRuntime( + dependencies(memory, { + storagePolicy: { + ...TEST_STORAGE_POLICY, + retention: { kind: "TTL", maxAgeMs: 10 }, + }, + keyRange: + memory.keyRange as NonNullable< + IndexedDbRuntimeDependencies["keyRange"] + >, + nowEpochMilliseconds: () => epochMs, + nowMonotonicMilliseconds: () => 0, + observe: (event) => observations.push(event), + }), + ); + expect(await runtime.open()).toMatchObject({ ok: true }); + for (const key of ["a", "b", "c"]) { + await runtime.compareAndSwap({ + key, + value: { label: key, rank: 1 }, + expectedRevision: null, + idempotencyKey: `create-${key}`, + }); + } + // Sorts first on the eligibility index and names a record it is not keyed by. + memory.seed("retention", { + recordKey: "zzz", + writtenAtEpochMs: 0, + synchronization: "NONE", + measuredBytes: 0, + eligibleAtEpochMs: 0, + }); + epochMs = 5_000; + + for (let attempt = 0; attempt < 2; attempt += 1) { + expect( + await runtime.enforceLifecycleBatch({ + action: "RETENTION_SWEEP", + maxRows: 100, + maxDurationMs: 1_000, + }), + ).toMatchObject({ ok: true, value: { state: "COMPLETE" } }); + } + expect( + ["a", "b", "c"].filter( + (key) => memory.readRaw("records", key) !== undefined, + ), + ).toEqual([]); + expect(memory.readRaw("retention", "zzz")).toBeDefined(); + expect(observations).toContainEqual( + expect.objectContaining({ + operation: "INDEXEDDB_WRITE", + outcome: "FAILED", + failureCode: "CORRUPT_DATA", + }), + ); + }); +}); From 7f45afac7df7723fef94d14f965567edfe6e57af Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:37:40 +0900 Subject: [PATCH 07/14] fix(storage): report a future IndexedDB schema as INCOMPATIBLE and online-only (05-06) An older tab that met a schema a newer release had upgraded got MIGRATION_FAILED / READ_ONLY, but could not even read, and operators were sent to the migration runbook. The VersionError on open now yields UNSUPPORTED / ONLINE_ONLY with status INCOMPATIBLE, reads and writes give the same answer, and the OPFS journal answers the same way. Co-Authored-By: Claude Opus 5.5 --- .../browser-file-storage-recovery.md | 9 +++- .../storage/indexeddb/indexeddb-runtime.ts | 36 +++++++++++++++- .../storage/opfs/indexeddb-opfs-journal.ts | 11 +++++ .../browser-file-storage/indexeddb-port.ts | 7 +++ .../indexeddb-runtime.spec.ts | 43 +++++++++++++++++++ tests/unit/indexeddb-opfs-journal.test.ts | 25 +++++++++++ tests/unit/indexeddb-runtime.test.ts | 40 +++++++++++++++++ 7 files changed, 168 insertions(+), 3 deletions(-) diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index ca969f33..bb35dda3 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -157,6 +157,12 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e - `versionchange` 뒤 connection이 남음 - repeated reload/update loop - open/maintenance의 `POLICY_REJECTED`: immutable dataset binding missing/mismatch +- open의 `UNSUPPORTED` / `ONLINE_ONLY`와 status `INCOMPATIBLE`: 더 새 release가 + schema를 올린 DB를 이전 bundle이 열었다(05-06). migration 실패가 아니므로 §5로 + 가지 않는다. 이 bundle은 그 dataset을 읽지도 쓰지도 않고 online-only로 + 동작하며, 새 release로 reload하면 풀린다 + (`indexeddb-runtime.ts` open의 `VersionError` 분기). OPFS journal도 같은 답을 + 낸다(`indexeddb-opfs-journal.ts` `translateFor`) ### 확인 순서 @@ -173,7 +179,8 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e 6. 모든 connection에 `versionchange`/forced-close handler가 설치됐는지 확인한다. 7. BroadcastChannel prepare hint는 참고만 하고 실제 open/connection registry를 확인한다. -8. N-1 bundle이 future schema를 read-only/online-only로 처리하는지 확인한다. +8. N-1 bundle이 future schema를 `INCOMPATIBLE` / `ONLINE_ONLY`로 처리하는지 + 확인한다. reference runtime은 read-only가 아니라 online-only로 닫는다. ### 안전한 조치 diff --git a/src/adapters/storage/indexeddb/indexeddb-runtime.ts b/src/adapters/storage/indexeddb/indexeddb-runtime.ts index 564f445c..abb7059d 100644 --- a/src/adapters/storage/indexeddb/indexeddb-runtime.ts +++ b/src/adapters/storage/indexeddb/indexeddb-runtime.ts @@ -285,6 +285,14 @@ function unavailable( }); } +function incompatible( + operation: BrowserDataOperation, +): BrowserDataResult { + return browserDataFailure("UNSUPPORTED", operation, { + recovery: "ONLINE_ONLY", + }); +} + function mappedFailure( error: unknown, operation: BrowserDataOperation, @@ -643,6 +651,7 @@ export function createIndexedDbRuntime( // so the migration count and the binding verdict belong to the attempt. let appliedMigrations = 0; let policyBindingRejected = false; + let futureSchema = false; updateStatus({ kind: "OPENING", targetVersion: dependencies.schemaVersion, @@ -651,7 +660,20 @@ export function createIndexedDbRuntime( factory, databaseName, version: dependencies.schemaVersion, - translate: translateFor(operation), + translate: (cause) => { + // 05-06. A VersionError on open means a newer release already + // upgraded this database. That is not a failed migration: this + // bundle can only work online until it is reloaded. + if ( + cause.kind === "NATIVE_EXCEPTION" && + (cause.error as { name?: unknown } | null)?.name === + "VersionError" + ) { + futureSchema = true; + return failureOf(incompatible(operation)); + } + return translateFor(operation)(cause); + }, signal, blockedTimeoutMs, timers, @@ -744,7 +766,14 @@ export function createIndexedDbRuntime( : opened; if (disposed) return result; if (!result.ok) { - updateStatus({ kind: "CLOSED", reason: "NOT_OPENED" }); + updateStatus( + futureSchema + ? { + kind: "INCOMPATIBLE", + schemaVersion: dependencies.schemaVersion, + } + : { kind: "CLOSED", reason: "NOT_OPENED" }, + ); // A failed migration is observed against INDEXEDDB_MIGRATE as well // as against the open the caller asked for. if (result.error.operation === "INDEXEDDB_MIGRATE") { @@ -834,6 +863,9 @@ export function createIndexedDbRuntime( const cancelled = abortedResult(signal, operation); if (cancelled) return Promise.resolve(cancelled); const db = connection.current(); + if (!db && !disposed && status.kind === "INCOMPATIBLE") { + return Promise.resolve(incompatible(operation)); + } if (!db || disposed) return Promise.resolve(unavailable(operation)); return runIndexedDbTransaction({ diff --git a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts index 464a9eda..cc58f704 100644 --- a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts +++ b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts @@ -1714,6 +1714,17 @@ function translateFor( return (cause) => { switch (cause.kind) { case "NATIVE_EXCEPTION": + // 05-06. A journal a newer release upgraded is not a failed + // migration; this bundle cannot use it and works online instead. + if ( + (cause.error as { name?: unknown } | null)?.name === "VersionError" + ) { + return failureOf( + browserDataFailure("UNSUPPORTED", operation, { + recovery: "ONLINE_ONLY", + }), + ); + } return failureOf(mapIndexedDbException(cause.error, operation)); case "BLOCKED": case "BLOCKED_DEADLINE": diff --git a/src/application/ports/browser-file-storage/indexeddb-port.ts b/src/application/ports/browser-file-storage/indexeddb-port.ts index 9c81a893..9d7e467a 100644 --- a/src/application/ports/browser-file-storage/indexeddb-port.ts +++ b/src/application/ports/browser-file-storage/indexeddb-port.ts @@ -43,6 +43,13 @@ export type IndexedDbConnectionStatus = targetVersion: number; }> | Readonly<{ kind: "READY"; schemaVersion: number }> + /** + * 05-06. The database was upgraded past `schemaVersion` by a newer release + * (another tab, or the bundle rolled back). This runtime cannot read or + * write it: open and every operation answer `UNSUPPORTED` with recovery + * `ONLINE_ONLY`, and a reload onto the newer release is the way back. + */ + | Readonly<{ kind: "INCOMPATIBLE"; schemaVersion: number }> | Readonly<{ kind: "DISPOSED" }>; export type IndexedDbCursorKey = diff --git a/tests/browser-capabilities/indexeddb-runtime.spec.ts b/tests/browser-capabilities/indexeddb-runtime.spec.ts index 775d5f59..e3fa690b 100644 --- a/tests/browser-capabilities/indexeddb-runtime.spec.ts +++ b/tests/browser-capabilities/indexeddb-runtime.spec.ts @@ -1186,3 +1186,46 @@ test("05-03 deletes a partition's dataset for an authorized ACCOUNT_DELETION whe }, name); expect(remaining).toBe(0); }); + +test("05-06 an older tab meets a schema a newer tab upgraded and goes online-only", async ({ + page, +}) => { + const olderPage = await page.context().newPage(); + const name = databaseName("future-schema"); + try { + await Promise.all([page.goto("/"), olderPage.goto("/")]); + expect(await installLifecycleRuntime(page, name, 2)).toMatchObject({ + opened: { ok: true }, + status: { kind: "READY", schemaVersion: 2 }, + }); + await closeLifecycleRuntime(page); + + expect(await installLifecycleRuntime(olderPage, name, 1)).toEqual({ + opened: { + ok: false, + error: { + code: "UNSUPPORTED", + operation: "INDEXEDDB_OPEN", + retryable: false, + recovery: "ONLINE_ONLY", + }, + }, + status: { kind: "INCOMPATIBLE", schemaVersion: 1 }, + }); + await closeLifecycleRuntime(olderPage); + const deletion = await page.evaluate( + async (currentDatabaseName) => + await new Promise((resolve) => { + const request = indexedDB.deleteDatabase(currentDatabaseName); + request.onsuccess = () => resolve("DELETED"); + request.onerror = () => + resolve(request.error?.name ?? "UNKNOWN_ERROR"); + request.onblocked = () => resolve("BLOCKED"); + }), + name, + ); + expect(deletion).toBe("DELETED"); + } finally { + await olderPage.close(); + } +}); diff --git a/tests/unit/indexeddb-opfs-journal.test.ts b/tests/unit/indexeddb-opfs-journal.test.ts index 3ab1e8bf..e5d79ee5 100644 --- a/tests/unit/indexeddb-opfs-journal.test.ts +++ b/tests/unit/indexeddb-opfs-journal.test.ts @@ -795,3 +795,28 @@ describe("IndexedDB OPFS journal", () => { ).toMatchObject({ ok: false, error: { code: "UNSUPPORTED" } }); }); }); + +describe("05-06 a journal from a newer release", () => { + it("answers online-only instead of a migration failure", async () => { + const memory = new MemoryIndexedDbFactory(); + const name = opfsJournalDatabaseName("authority_12345678"); + await new Promise((resolve, reject) => { + const request = memory.factory.open(name, 2); + request.onsuccess = () => { + request.result.close(); + resolve(); + }; + request.onerror = () => reject(request.error); + }); + const journal = createIndexedDbOpfsJournal({ + authorityToken: "authority_12345678", + factory: memory.factory, + keyRange: memory.keyRange, + }); + + expect(await journal.listIncomplete(10)).toMatchObject({ + ok: false, + error: { code: "UNSUPPORTED", recovery: "ONLINE_ONLY" }, + }); + }); +}); diff --git a/tests/unit/indexeddb-runtime.test.ts b/tests/unit/indexeddb-runtime.test.ts index 59947308..064d6317 100644 --- a/tests/unit/indexeddb-runtime.test.ts +++ b/tests/unit/indexeddb-runtime.test.ts @@ -1676,3 +1676,43 @@ describe("05-05 a retention sweep steps over a corrupt row", () => { ); }); }); + +describe("05-06 an older tab that meets a newer schema", () => { + it("reports INCOMPATIBLE and online-only, not a migration failure", async () => { + const memory = new MemoryIndexedDbFactory(); + const base = dependencies(memory); + const newer = createIndexedDbRuntime({ + ...base, + schemaVersion: 2, + migrations: [ + ...base.migrations, + { + id: "schema-v2", + fromVersion: 1, + toVersion: 2, + operations: [{ kind: "CREATE_STORE", name: "extra", keyPath: "k" }], + }, + ], + }); + expect(await newer.open()).toMatchObject({ ok: true }); + newer.close(); + const older = createIndexedDbRuntime(dependencies(memory)); + + expect(await older.open()).toMatchObject({ + ok: false, + error: { + code: "UNSUPPORTED", + operation: "INDEXEDDB_OPEN", + recovery: "ONLINE_ONLY", + }, + }); + expect(older.getStatus()).toEqual({ + kind: "INCOMPATIBLE", + schemaVersion: 1, + }); + expect(await older.read("x")).toMatchObject({ + ok: false, + error: { code: "UNSUPPORTED", recovery: "ONLINE_ONLY" }, + }); + }); +}); From 2b24f6d8f0722087fe452d53bb2474d59a250a98 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:41:31 +0900 Subject: [PATCH 08/14] fix(storage): fail a put whose source stalls so the OPFS origin lock is freed (05-07) A put holds the origin-wide mutation lock from BEGIN to FINISH, and the page waited on its source with no bound, so one stalled source blocked every tab's writes until their lock wait failed. Each wait for source bytes is now bounded by putIdleTimeoutMs; the put fails NOT_READABLE (retryable) and its compensation releases the lock. The port now says writes are one at a time. Co-Authored-By: Claude Opus 5.5 --- .../browser-file-storage-recovery.md | 5 +++ src/adapters/storage/opfs/opfs-policy.ts | 11 +++++ .../storage/opfs/opfs-worker-client.ts | 42 ++++++++++++----- .../ports/browser-file-storage/opfs-ports.ts | 6 +++ tests/unit/opfs-worker-runtime.test.ts | 45 +++++++++++++++++++ 5 files changed, 99 insertions(+), 10 deletions(-) diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index bb35dda3..36367cff 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -366,6 +366,11 @@ VD-15 목표 runtime을 먼저 구현한다. - committed logical row와 physical manifest/file 불일치 - digest/length mismatch - worker crash, handle lock timeout, `NoModificationAllowedError` +- put의 retryable `NOT_READABLE`: source가 `putIdleTimeoutMs`(기본 2분) 동안 다음 + bytes를 주지 않아 put을 끝내고 origin mutation lock을 풀었다(05-07, + `opfs-worker-client.ts` `preparePut`, `opfs-policy.ts`). OPFS 쓰기는 origin + 전체에서 한 번에 하나라서, 이 bound가 없으면 멈춘 source 하나가 모든 tab의 쓰기를 + `mutationLockWaitTimeoutMs` 뒤 `BLOCKED`로 만든다 - sensitive policy maintenance의 `POLICY_REJECTED`, proof replay/expiry 또는 authority provider/consumer unavailable diff --git a/src/adapters/storage/opfs/opfs-policy.ts b/src/adapters/storage/opfs/opfs-policy.ts index 5f0a9954..d5dd8a95 100644 --- a/src/adapters/storage/opfs/opfs-policy.ts +++ b/src/adapters/storage/opfs/opfs-policy.ts @@ -20,6 +20,13 @@ export type OpfsRuntimePolicy = Readonly<{ * is bounded on its own and never counted against `rpcTimeoutMs`. */ mutationLockWaitTimeoutMs: number; + /** + * 05-07. How long a put may wait for its source's next bytes. The put holds + * the origin mutation lock from BEGIN to FINISH, so a stalled source would + * otherwise stop every tab's writes until their lock wait ran out. Keep it + * below `mutationLockWaitTimeoutMs` so a queued writer outlasts it. + */ + putIdleTimeoutMs: number; reconciliationBudgetMs: number; reconciliationBatchSize: number; orphanGracePeriodMs: number; @@ -56,6 +63,7 @@ export const DEFAULT_OPFS_RUNTIME_POLICY: OpfsRuntimePolicy = Object.freeze({ maxChunkCount: 512, rpcTimeoutMs: 60_000, mutationLockWaitTimeoutMs: 10 * 60_000, + putIdleTimeoutMs: 2 * 60_000, reconciliationBudgetMs: 5_000, reconciliationBatchSize: 100, orphanGracePeriodMs: 24 * 60 * 60 * 1_000, @@ -94,6 +102,9 @@ export function assertOpfsRuntimePolicy(policy: OpfsRuntimePolicy): void { !Number.isSafeInteger(policy.mutationLockWaitTimeoutMs) || policy.mutationLockWaitTimeoutMs < 1_000 || policy.mutationLockWaitTimeoutMs > 60 * 60_000 || + !Number.isSafeInteger(policy.putIdleTimeoutMs) || + policy.putIdleTimeoutMs < 1_000 || + policy.putIdleTimeoutMs > 60 * 60_000 || !Number.isSafeInteger(policy.reconciliationBudgetMs) || policy.reconciliationBudgetMs < 1 || policy.reconciliationBudgetMs > 60_000 || diff --git a/src/adapters/storage/opfs/opfs-worker-client.ts b/src/adapters/storage/opfs/opfs-worker-client.ts index 9707ce79..2dffd10a 100644 --- a/src/adapters/storage/opfs/opfs-worker-client.ts +++ b/src/adapters/storage/opfs/opfs-worker-client.ts @@ -14,6 +14,7 @@ import { browserDataFailure, browserDataSuccess, } from "../../browser-file-storage/result.ts"; +import { createAbortableOperation } from "../../platform/abortable-operation.ts"; import type { OpfsRuntimePolicy } from "./opfs-policy.ts"; import { isPreparedObject } from "./opfs-prepared-object.ts"; import { @@ -272,13 +273,36 @@ export function createOpfsWorkerGateway( let sequence = 0; let transferredBytes = 0; notifyProgress(request, "TRANSFERRING", 0); + // 05-07. BEGIN took the origin mutation lock, so every wait for the + // source is bounded by `putIdleTimeoutMs`. A source that stops fails the + // put, and the coordinator's compensation releases the lock. + const sourceStop = new AbortController(); + const stopSource = () => sourceStop.abort(); + request.signal?.addEventListener("abort", stopSource, { once: true }); + if (request.signal?.aborted) stopSource(); + const chunks = rechunk( + request.source.stream(sourceStop.signal), + dependencies.policy.chunkSizeBytes, + dependencies.policy.maxObjectBytes, + request.signal, + ); try { - for await (const chunk of rechunk( - request.source.stream(requiredSignal(request.signal)), - dependencies.policy.chunkSizeBytes, - dependencies.policy.maxObjectBytes, - request.signal, - )) { + for (;;) { + const idle = createAbortableOperation({ + signal: request.signal, + timeoutMs: dependencies.policy.putIdleTimeoutMs, + }); + const next = await idle.race(chunks.next()); + idle.close(); + if (next.kind === "REJECTED") throw next.reason; + if (next.kind === "TERMINAL") { + stopSource(); + throw new OpfsRpcError( + next.terminal === "DEADLINE" ? "NOT_READABLE" : "ABORTED", + ); + } + if (next.value.done) break; + const chunk = next.value.value; const chunkByteLength = chunk.byteLength; const append = await invoke( "OBJECT_WRITE", @@ -320,6 +344,8 @@ export function createOpfsWorkerGateway( error instanceof OpfsRpcError ? error.code : "NOT_READABLE", "OBJECT_WRITE", ); + } finally { + request.signal?.removeEventListener("abort", stopSource); } }, @@ -585,10 +611,6 @@ async function* rechunk( } } -function requiredSignal(signal: AbortSignal | undefined): AbortSignal { - return signal ?? new AbortController().signal; -} - function notifyProgress( request: PreparePhysicalObjectRequest, phase: "TRANSFERRING" | "VERIFYING", diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index fdc2d3d1..227b314d 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -76,6 +76,12 @@ export type OpfsCapabilities = Readonly<{ export interface DurableObjectStorePort { capabilities(): Promise>; + /** + * 05-07. OPFS writes are one at a time across the whole origin: a put holds + * the origin mutation lock while it streams, and every put, remove and GC in + * every tab waits for it. A source that stops for the runtime's put idle + * bound fails the put with a retryable `NOT_READABLE` and frees the lock. + */ put( request: PutDurableObjectRequest, ): Promise>; diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index 3c3a6a52..dbac0184 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -2398,3 +2398,48 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh }); }); }); + +describe("05-07 a put whose source stops lets go of the origin lock", () => { + afterEach(() => { + vi.useRealTimers(); + }); + + it("fails the stalled put at the idle bound so another tab's put runs", async () => { + const policy = resolveOpfsRuntimePolicy({ + ...runtimePolicy, + putIdleTimeoutMs: 30_000, + }); + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); + const { tab, leases } = sharedRootTabs(policy); + const tabA = tab("a"); + const tabB = tab("b"); + const stalled = stalledSource(); + const putA = tabA.objects.put({ + objectId: "object_stalled_01", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: stalled.source, + }); + await stalled.streaming; + expect(leases.held).toBe(true); + const putB = tabB.objects.put({ + objectId: "object_waiting_01", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }); + + await vi.advanceTimersByTimeAsync(policy.putIdleTimeoutMs + 1); + vi.useRealTimers(); + const settledA = await Promise.race([ + putA, + new Promise((resolve) => setTimeout(() => resolve("STILL_RUNNING"), 2_000)), + ]); + expect(settledA).toMatchObject({ + ok: false, + error: { code: "NOT_READABLE", retryable: true }, + }); + expect(await putB).toMatchObject({ ok: true, value: { generation: 1 } }); + stalled.release(); + }); +}); From 4d8ceade21953e6712932c500adde463fe829072 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:44:51 +0900 Subject: [PATCH 09/14] fix(storage): match the OPFS runbook to the adapter and drop the dead EFFECT_UNKNOWN branch (05-09) The runbook named failure codes the adapter stopped using and promised a resume and a quarantine reconcile never does. It now states the put's own code with RECONCILE, the skipped and failed row counts, and what reconcile really does per phase. The worker never sent EFFECT_UNKNOWN and the client refused it, so the cleanup effect type and its two adapter branches go. Co-Authored-By: Claude Opus 5.5 --- .../browser-file-and-origin-storage.md | 2 +- .../browser-file-storage-recovery.md | 34 ++++++++++++++----- .../storage/opfs/opfs-byte-store-adapter.ts | 8 +---- .../ports/browser-file-storage/opfs-ports.ts | 9 ++--- tests/unit/opfs-byte-store.test.ts | 12 +++---- 5 files changed, 38 insertions(+), 27 deletions(-) diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index 8389839f..45e72674 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -759,7 +759,7 @@ CLEANED -> journal 제거 - journal row와 budget reservation은 physical cleanup effect가 `CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash, - malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를 + malformed response, worker cleanup 실패는 성공이 아니며 `PREPARING`/`FILES_READY`를 그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면 `QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다 (Q-6.5-9). journal rollback이 실패해도 같다. diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 36367cff..b2e8d014 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -16,15 +16,24 @@ primitive를 coordinator 완료 증거로 사용하지 않는다. ## OPFS 보상 실패와 reconcile (STO-01) -`put()`이 실패했는데 보상 cleanup effect가 확인되지 않으면 runtime은 실패를 -`OBJECT_RECONCILE` / `CONFLICT`(recovery `RETRY`)로 보고하고 journal row를 남긴다. -이는 결함이 아니라 설계된 상태다. +`put()`이 commit 전에 실패하면 coordinator가 그 transaction의 staging을 지우고 +journal row를 되돌린다(보상). 보상의 worker cleanup이나 journal rollback이 끝나지 +않으면 put은 자기 실패 코드(`QUOTA_EXCEEDED`, `ABORTED` 등)와 operation +`OBJECT_WRITE`를 그대로 두고 recovery만 `RECONCILE`로 바꿔 반환한다. journal +row(`PREPARING`/`FILES_READY`)는 남는다(`opfs-byte-store-adapter.ts` +`compensatePreparedPut`, Q-6.5-9). 이는 결함이 아니라 설계된 상태다. worker가 +cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답한다. 별도의 "결과 불명" +값은 없다(05-09). 1. journal에 `PREPARING` 또는 `FILES_READY` row가 남아 있는지 확인한다. 남아 있다면 staging bytes가 아직 존재할 수 있다는 뜻이다. -2. `maintenance.reconcile()`을 실행한다. reconcile은 같은 exact physical - generation token만 삭제하고, effect가 여전히 `EFFECT_UNKNOWN`이면 journal을 - 유지한 채 다시 `OBJECT_RECONCILE`을 반환한다. +2. `maintenance.reconcile()`을 실행한다. reconcile은 exact physical generation + token만 삭제한다. report에서 다음을 본다. + - `skippedLiveTransactions`: 어느 tab에서든 아직 진행 중인 put/delete의 row다. + reconcile은 transaction별 Web Lock을 `ifAvailable`로 잡지 못한 row를 건드리지 + 않는다(05-01, `reconcile`의 `holdTransactionLock`). 결함이 아니다. + - `failedTransactions`: 이번에 정리하지 못해 journal에 남긴 row 수다. 나머지 + row와 orphan GC는 계속 돈다(05-02). 같은 row가 계속 실패하면 §7을 본다. 3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할 근거가 사라지고 quota만 누수된다. 4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지 @@ -406,9 +415,16 @@ VD-15 목표 runtime을 먼저 구현한다. ### recovery -- `PREPARING`: partial staging 검증 후 idempotent resume 또는 purge -- `FILES_READY`: expected generation/digest 일치 시 logical commit, 아니면 - quarantine +- `PREPARING`: reconcile은 resume하지 않는다. staging receipt가 가리키는 그 + transaction의 physical generation과 staging을 지우고 journal row를 rollback한다. + receipt가 없거나 0바이트면(첫 receipt 쓰기가 quota나 crash로 끝나지 못함) 지울 + generation이 없으므로 staging만 지운다(05-02). 읽을 수 없는 receipt는 지우지 + 않고 그 row를 `failedTransactions`로 남긴다 + (`opfs-byte-store-adapter.ts` `reconcileTransaction`, + `opfs-worker-runtime.ts` `cleanupTransactionLocked`) +- `FILES_READY`: worker가 manifest와 모든 chunk digest를 다시 검증한다. 맞으면 + logical commit 뒤 finalize한다. 맞지 않으면 quarantine하지 않고 그 generation과 + staging을 지운 뒤 rollback한다. 지워지는 것은 commit 전 staging뿐이다 - `COMMITTED` + file missing/corrupt: reconstructable만 server rehydrate; user-created private는 read-only/export/recovery - stale staging/orphan chunk는 grace period와 bounded mark/sweep 후 제거 diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index fa803da7..2390325a 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -1052,7 +1052,7 @@ export function createOpfsByteStoreAdapter( * The journal row and its budget reservation are the only durable evidence * that a physical staging generation may still exist, so they are released * exactly when the physical effect is confirmed `CLEANED` or - * `ALREADY_CLEAN`. A timeout, crash, malformed response or `EFFECT_UNKNOWN` + * `ALREADY_CLEAN`. A timeout, crash, malformed response or worker failure * keeps `PREPARING`/`FILES_READY` in place and asks for reconciliation. */ /** @@ -1074,7 +1074,6 @@ export function createOpfsByteStoreAdapter( }); const compensated = cleanup.ok && - cleanup.value.kind !== "EFFECT_UNKNOWN" && ( await dependencies.journal.rollback( transaction.transactionId, @@ -1102,11 +1101,6 @@ export function createOpfsByteStoreAdapter( signal, ); if (!cleaned.ok) return cleaned; - if (cleaned.value.kind === "EFFECT_UNKNOWN") { - return browserDataFailure("CONFLICT", "OBJECT_RECONCILE", { - recovery: "RETRY", - }); - } const rolledBack = await dependencies.journal.rollback( transaction.transactionId, transaction.fencingToken, diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index 227b314d..7091ab07 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -233,11 +233,12 @@ export type OpfsPreparedObject = OpfsPreparedObjectV1 | OpfsPreparedObjectV2; /** * STO-01. Compensation is only allowed to release journal and budget state - * after the physical effect is confirmed. `EFFECT_UNKNOWN` is never a success. + * after the physical effect is confirmed. An effect the worker cannot confirm + * comes back as a failure, never as a success value (05-09). */ -export type OpfsCleanupEffect = - | Readonly<{ kind: "CLEANED" | "ALREADY_CLEAN" }> - | Readonly<{ kind: "EFFECT_UNKNOWN" }>; +export type OpfsCleanupEffect = Readonly<{ + kind: "CLEANED" | "ALREADY_CLEAN"; +}>; export type OpfsJournalMutation = "PUT" | "DELETE"; export type OpfsJournalPhase = diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index 734a2d9e..a81d5f2e 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -630,7 +630,7 @@ describe("OPFS byte-store coordinator", () => { }, { async abortPreparedPut() { - return browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }); + return browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"); }, }, ]) { @@ -775,11 +775,11 @@ describe("OPFS byte-store coordinator", () => { }); }); - it("does not roll back journal after an unknown worker mutation effect", async () => { + it("does not roll back journal after an unconfirmed worker cleanup", async () => { const journal = createJournal(); const worker = createWorker({ async abortPreparedPut() { - return browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }); + return browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"); }, }); const rollback = vi.spyOn(journal, "rollback"); @@ -843,8 +843,8 @@ describe("OPFS byte-store coordinator", () => { async () => browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"), ], [ - "an unknown cleanup effect", - async () => browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }), + "an aborted cleanup", + async () => browserDataFailure("ABORTED", "OBJECT_RECONCILE"), ], ])("after %s", async (_label, abortPreparedPut) => { const journal = createJournal(); @@ -910,7 +910,7 @@ describe("OPFS byte-store coordinator", () => { await putWith( { abortPreparedPut: async () => - browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }), + browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"), }, journal, ), From 3767ed7ccb0acbd87fb5a3f04e8790ceba3799ef Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:48:03 +0900 Subject: [PATCH 10/14] fix(storage): refuse an OPFS policy that widens the object id grammar and keep one stableJson (05-10) isObjectIdAllowed could be widened while stored objects, journal rows and paths keep the fixed opaque id grammar, so such a policy failed puts late. Resolving the policy now rejects a predicate that admits ids just outside the grammar, and the prepared-object check uses the policy's own grammar. The worker and the journal share one stableJson that throws on values JSON cannot carry instead of writing NaN as null. Co-Authored-By: Claude Opus 5.5 --- .../storage/opfs/indexeddb-opfs-journal.ts | 24 +----------- src/adapters/storage/opfs/opfs-policy.ts | 35 ++++++++++++++++- .../storage/opfs/opfs-prepared-object.ts | 38 +++++++++++++++++-- .../storage/opfs/opfs-worker-runtime.ts | 27 +------------ tests/unit/opfs-worker-runtime.test.ts | 11 ++++++ 5 files changed, 82 insertions(+), 53 deletions(-) diff --git a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts index cc58f704..e1dcb5d2 100644 --- a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts +++ b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts @@ -33,7 +33,7 @@ import { } from "../../platform/indexeddb-transaction.ts"; import { mapIndexedDbException } from "../indexeddb/indexeddb-failure.ts"; import { isValidOpfsStorageScope } from "./opfs-policy.ts"; -import { isPreparedObject } from "./opfs-prepared-object.ts"; +import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts"; export type IndexedDbOpfsJournalDependencies = Readonly<{ authorityToken: string; @@ -1608,28 +1608,6 @@ function isChunkReference( ); } -function stableJson(value: unknown): string { - if ( - value === null || - typeof value === "string" || - typeof value === "boolean" || - typeof value === "number" - ) { - return JSON.stringify(value); - } - if (Array.isArray(value)) { - return `[${value.map(stableJson).join(",")}]`; - } - if (typeof value === "object") { - const record = value as Record; - return `{${Object.keys(record) - .sort() - .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`) - .join(",")}}`; - } - throw new TypeError("Journal value is not JSON-safe."); -} - /** * `browserDataFailure` and `mapIndexedDbException` build a `Result`, while the * kernel's `translate` and `context.fail` want the failure on its own. Both diff --git a/src/adapters/storage/opfs/opfs-policy.ts b/src/adapters/storage/opfs/opfs-policy.ts index d5dd8a95..f62f4f42 100644 --- a/src/adapters/storage/opfs/opfs-policy.ts +++ b/src/adapters/storage/opfs/opfs-policy.ts @@ -120,12 +120,45 @@ export function assertOpfsRuntimePolicy(policy: OpfsRuntimePolicy): void { policy.maxCancellationTombstones < 16 || policy.maxCancellationTombstones > 10_000 || typeof policy.isObjectIdAllowed !== "function" || - typeof policy.isMediaTypeAllowed !== "function" + typeof policy.isMediaTypeAllowed !== "function" || + widensObjectIdGrammar(policy.isObjectIdAllowed) ) { throw new TypeError("OPFS runtime policy is invalid."); } } +/** + * 05-10. Stored prepared objects, journal rows and physical paths all use the + * opaque id grammar, so a policy may narrow it but never widen it: a wider + * policy let BEGIN through and failed every put at its last step. Ids just + * outside the grammar catch the usual widenings when the policy is resolved. + */ +const OBJECT_IDS_OUTSIDE_GRAMMAR = Object.freeze([ + "", + "short_7", + "a".repeat(129), + "object 12345", + "object.12345", + "object/12345", + "object~12345", +]); + +function widensObjectIdGrammar( + isObjectIdAllowed: (objectId: string) => boolean, +): boolean { + try { + return OBJECT_IDS_OUTSIDE_GRAMMAR.some((objectId) => + isObjectIdAllowed(objectId), + ); + } catch { + return true; + } +} + +export function isOpaqueObjectId(value: string): boolean { + return OPAQUE_OBJECT_ID.test(value); +} + export function validateObjectWriteInput( input: Readonly<{ scope: OpfsStorageScope; diff --git a/src/adapters/storage/opfs/opfs-prepared-object.ts b/src/adapters/storage/opfs/opfs-prepared-object.ts index ab44c1f8..5ee2af2b 100644 --- a/src/adapters/storage/opfs/opfs-prepared-object.ts +++ b/src/adapters/storage/opfs/opfs-prepared-object.ts @@ -3,9 +3,8 @@ import type { OpfsStorageScope, } from "../../../application/ports/browser-file-storage/opfs-ports.ts"; import { assertValidStoragePolicy } from "../../../application/ports/browser-file-storage/shared.ts"; -import { isValidOpfsStorageScope } from "./opfs-policy.ts"; +import { isOpaqueObjectId, isValidOpfsStorageScope } from "./opfs-policy.ts"; -const OPAQUE_OBJECT_ID = /^[A-Za-z0-9_-]{8,128}$/u; const SHA256_HEX = /^[a-f0-9]{64}$/u; /** @@ -53,7 +52,7 @@ export function isPreparedObject( : null; if ( typeof descriptor.objectId !== "string" || - !OPAQUE_OBJECT_ID.test(descriptor.objectId) || + !isOpaqueObjectId(descriptor.objectId) || !descriptor.scope || typeof descriptor.scope !== "object" || !isValidOpfsStorageScope(descriptor.scope as OpfsStorageScope) || @@ -129,3 +128,36 @@ export function isPreparedObject( Math.ceil(descriptor.byteLength / integrity.chunkSizeBytes) ); } + +/** + * 05-10. The one canonical JSON for comparing OPFS records, used by the + * worker and the journal alike. A value JSON cannot carry exactly (a + * non-finite number, `undefined`, a function) throws instead of being + * written as something else, so two different values never compare equal. + */ +export function stableJson(value: unknown): string { + if ( + value === null || + typeof value === "string" || + typeof value === "boolean" + ) { + return JSON.stringify(value); + } + if (typeof value === "number") { + if (!Number.isFinite(value)) { + throw new TypeError("OPFS value is not JSON-safe."); + } + return JSON.stringify(value); + } + if (Array.isArray(value)) { + return `[${value.map(stableJson).join(",")}]`; + } + if (typeof value === "object") { + const record = value as Record; + return `{${Object.keys(record) + .sort() + .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`) + .join(",")}}`; + } + throw new TypeError("OPFS value is not JSON-safe."); +} diff --git a/src/adapters/storage/opfs/opfs-worker-runtime.ts b/src/adapters/storage/opfs/opfs-worker-runtime.ts index 07b23ba4..71e4991b 100644 --- a/src/adapters/storage/opfs/opfs-worker-runtime.ts +++ b/src/adapters/storage/opfs/opfs-worker-runtime.ts @@ -16,7 +16,7 @@ import { isValidOpfsStorageScope, type OpfsRuntimePolicy, } from "./opfs-policy.ts"; -import { isPreparedObject } from "./opfs-prepared-object.ts"; +import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts"; import { OPFS_WORKER_PROTOCOL_VERSION, } from "./opfs-worker-protocol.ts"; @@ -1739,31 +1739,6 @@ function bytesToHex(bytes: Uint8Array): string { return hex; } -function stableJson(value: unknown): string { - if ( - value === null || - typeof value === "string" || - typeof value === "boolean" - ) { - return JSON.stringify(value); - } - if (typeof value === "number") { - if (!Number.isFinite(value)) throw new OpfsRuntimeFailure("CORRUPT_DATA"); - return JSON.stringify(value); - } - if (Array.isArray(value)) { - return `[${value.map(stableJson).join(",")}]`; - } - if (typeof value === "object") { - const record = value as Record; - return `{${Object.keys(record) - .sort() - .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`) - .join(",")}}`; - } - throw new OpfsRuntimeFailure("CORRUPT_DATA"); -} - function success( requestId: string, kind: OpfsWorkerRequest["kind"], diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index dbac0184..d1b1bae3 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -2443,3 +2443,14 @@ describe("05-07 a put whose source stops lets go of the origin lock", () => { stalled.release(); }); }); + +describe("05-10 the object id grammar is the prepared-object grammar", () => { + it("rejects a policy that widens the object id grammar when it is resolved", () => { + expect(() => + resolveOpfsRuntimePolicy({ + ...runtimePolicy, + isObjectIdAllowed: (objectId) => /^[A-Za-z0-9_.-]{1,200}$/u.test(objectId), + }), + ).toThrow(TypeError); + }); +}); From 6cc652610d1c3fee1f6f20c226e7ef660182de89 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:52:29 +0900 Subject: [PATCH 11/14] refactor(storage): move the IndexedDB error table to the kernel exception file (05-11) The OPFS journal imported mapIndexedDbException from the IndexedDB runtime's folder, so the two runtimes were not separable as the comments claimed. The table now lives in browser-file-storage/result.ts next to the DOM table, with the differences between the two written down; storage/opfs imports nothing from storage/indexeddb. The storage barrel comment now states the drill's real scope: it removes the whole bundle, never one folder. Co-Authored-By: Claude Opus 5.5 --- .../adapters/03-storage-and-browser-files.md | 3 +- docs/reviews/adapters/INVENTORY.md | 65 ++++++++------- src/adapters/browser-file-storage/result.ts | 81 +++++++++++++++++++ src/adapters/storage/index.ts | 8 +- .../storage/indexeddb/indexeddb-failure.ts | 72 ----------------- .../indexeddb/indexeddb-maintenance.ts | 9 +-- .../storage/indexeddb/indexeddb-runtime.ts | 9 +-- .../storage/opfs/indexeddb-opfs-journal.ts | 9 +-- tests/unit/indexeddb-runtime.test.ts | 2 +- 9 files changed, 132 insertions(+), 126 deletions(-) delete mode 100644 src/adapters/storage/indexeddb/indexeddb-failure.ts diff --git a/docs/reviews/adapters/03-storage-and-browser-files.md b/docs/reviews/adapters/03-storage-and-browser-files.md index 93fb3d38..279cdbec 100644 --- a/docs/reviews/adapters/03-storage-and-browser-files.md +++ b/docs/reviews/adapters/03-storage-and-browser-files.md @@ -31,7 +31,7 @@ | 파일 | 책임 | 주요 의존성 / 리뷰 결과 | | --- | --- | --- | | `src/adapters/browser-file-storage/index.ts` | browser data 공통 Result와 StorageManager adapter barrel export | 내부 두 모듈만 export. 경계가 작고 유지 대상. | -| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공 | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. | +| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공. IndexedDB 예외 표 `mapIndexedDbException`도 여기 있다(05-11, 옛 `storage/indexeddb/indexeddb-failure.ts`) | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. | | `src/adapters/browser-file-storage/storage-manager-adapter.ts` | `estimate/persisted/persist` snapshot, pressure bucket, user-activation-bound persistence 요청 | storage durability port/result. estimate를 예약량으로 오인하지 않고 irreversible `persist()` truth를 보존한다. origin coordinator는 의도적으로 없음(GAP-03). | ### 1.2 `browser-files` @@ -66,7 +66,6 @@ | `src/adapters/storage/browser-storage-adapter.ts` | registry key별 local/session/memory 저장, TTL, failure overlay/tombstone, quota fallback | `storage-keys`, `StoragePort`, codec, diagnostics. strict registry와 stale persistent suppression을 유지. adjacent physical-key migration/sweep는 문서상 미구현. | | `src/adapters/storage/browser-storage-codec.ts` | bounded exact JSON envelope, exotic/accessor/unsafe-key/cycle/depth/node 거절 | 독립 codec. prototype pollution/JSON silent coercion 방어가 좋다. | | `src/adapters/storage/indexeddb/index.ts` | IndexedDB runtime/maintenance/governance/migration export | native IDB type을 application port 밖으로 내보내지 않는 구조 유지. | -| `src/adapters/storage/indexeddb/indexeddb-failure.ts` | IDB/DOM failure를 closed browser failure로 변환 | common Result. raw native detail 비노출 유지. | | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | opaque dataset scope/physical DB identity 및 frozen policy binding | indexeddb/shared ports. account/business ID를 physical name에 쓰지 않는 양방향 binding 유지. | | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | post-open codec migration 및 idempotency receipt prune, keyset checkpoint, budget/revision fencing | IndexedDB port/types/failure/governance. async transform outside tx, row+sidecar+budget+checkpoint atomic commit은 좋다. STO-06 및 temporal drain lease 개선 후보. | | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | additive-only contiguous DDL planner/validator | indexeddb types. destructive DDL 거절 유지. | diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index d4829486..0cc3fc07 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -122,38 +122,37 @@ | 112 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) | | 113 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | | 114 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 115 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 116 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 117 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 118 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 119 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 120 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 121 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 122 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 123 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 124 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 125 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 126 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 127 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 128 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 129 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 130 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 131 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) | -| 132 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) | -| 133 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) | -| 134 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) | -| 135 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 136 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 137 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 138 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 139 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 140 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 141 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 142 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 143 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 144 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 145 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 146 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 115 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 116 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 117 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 118 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 119 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 120 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 121 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 122 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 123 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 124 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 125 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 126 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 127 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 128 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 129 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | +| 130 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) | +| 131 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) | +| 132 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) | +| 133 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) | +| 134 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 135 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 136 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 137 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 138 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 139 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 140 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 141 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 142 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 143 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 144 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 145 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -합계: **146/146**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. +합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. diff --git a/src/adapters/browser-file-storage/result.ts b/src/adapters/browser-file-storage/result.ts index 17df5acc..7940982d 100644 --- a/src/adapters/browser-file-storage/result.ts +++ b/src/adapters/browser-file-storage/result.ts @@ -40,6 +40,12 @@ export function abortedResult( : null; } +/** + * The table for File, Storage Manager, Cache Storage and download DOM errors. + * IndexedDB errors use `mapIndexedDbException` below: the same exception name + * means something else there (a `NotFoundError` is a missing store, not a + * missing file). + */ export function mapBrowserDataException( error: unknown, operation: BrowserDataOperation, @@ -89,6 +95,81 @@ export function mapBrowserDataException( } } +function exceptionName(error: unknown): string { + if ( + error && + typeof error === "object" && + "name" in error && + typeof error.name === "string" + ) { + return error.name; + } + return ""; +} + +/** + * 05-11. The one table for native IndexedDB errors. It lives in this kernel + * exception file so the OPFS journal no longer reaches into the IndexedDB + * runtime's folder for it. It maps the closed DOMException vocabulary without + * exposing an exception object, message, key or stored value across the + * adapter boundary. + * + * Differences from `mapBrowserDataException`, on purpose: a missing store or + * index, an inactive or read-only transaction and a `VersionError` are schema + * problems (`MIGRATION_FAILED`, READ_ONLY), not a missing file or a transient + * failure; quota and constraint failures are not retried blindly. + */ +export function mapIndexedDbException( + error: unknown, + operation: BrowserDataOperation, +): BrowserDataResult { + switch (exceptionName(error)) { + case "AbortError": + return browserDataFailure("ABORTED", operation); + case "ConstraintError": + return browserDataFailure("CONFLICT", operation); + case "DataCloneError": + case "DataError": + return browserDataFailure("CORRUPT_DATA", operation, { + recovery: "READ_ONLY", + }); + case "InvalidAccessError": + case "InvalidStateError": + case "NotFoundError": + case "ReadOnlyError": + case "TransactionInactiveError": + case "VersionError": + return browserDataFailure("MIGRATION_FAILED", operation, { + recovery: "READ_ONLY", + }); + case "NotAllowedError": + case "SecurityError": + return browserDataFailure("PERMISSION_DENIED", operation, { + recovery: "ONLINE_ONLY", + }); + case "NotReadableError": + return browserDataFailure("NOT_READABLE", operation, { + retryable: true, + recovery: "REOPEN", + }); + case "QuotaExceededError": + case "NS_ERROR_DOM_QUOTA_REACHED": + return browserDataFailure("QUOTA_EXCEEDED", operation, { + recovery: "READ_ONLY", + }); + case "UnknownError": + return browserDataFailure("UNAVAILABLE", operation, { + retryable: true, + recovery: "REOPEN", + }); + default: + return browserDataFailure("UNAVAILABLE", operation, { + retryable: true, + recovery: "RETRY", + }); + } +} + export function observeBrowserData( observer: BrowserDataObserver | undefined, observation: BrowserDataObservation, diff --git a/src/adapters/storage/index.ts b/src/adapters/storage/index.ts index 43e058d7..2d895502 100644 --- a/src/adapters/storage/index.ts +++ b/src/adapters/storage/index.ts @@ -2,9 +2,11 @@ * 최상위 storage 배럴은 Web Storage 어댑터만 내보낸다. * * `./indexeddb/index.ts`와 `./opfs/index.ts`를 여기서 재수출하지 말 것. - * `scripts/test-browser-file-storage-runtime-removal.ts:23-34`가 그 두 폴더만 - * 삭제한 뒤 잔존 import를 예외로 잡는다 — 재수출하면 제거 드릴이 죽는다. - * 두 서브배럴이 각자 제거 가능한 런타임의 경계다. + * `scripts/test-browser-file-storage-runtime-removal.ts`의 `runtimePaths`는 이 두 + * 폴더를 browser-file-storage 번들 전체(ports, browser-files, browser-transfer, + * cache-storage 등)와 함께 삭제한 뒤 잔존 import를 예외로 잡는다 — 재수출하면 + * 제거 드릴이 죽는다. 드릴은 번들을 통째로만 지운다. 두 폴더 중 하나만 지우는 + * 경우는 드릴이 검증하지 않는다. */ export { createBrowserStorageAdapter, diff --git a/src/adapters/storage/indexeddb/indexeddb-failure.ts b/src/adapters/storage/indexeddb/indexeddb-failure.ts deleted file mode 100644 index 70c78355..00000000 --- a/src/adapters/storage/indexeddb/indexeddb-failure.ts +++ /dev/null @@ -1,72 +0,0 @@ -import type { - BrowserDataOperation, - BrowserDataResult, -} from "../../../application/ports/browser-file-storage/shared.ts"; -import { browserDataFailure } from "../../browser-file-storage/result.ts"; - -function exceptionName(error: unknown): string { - if ( - error && - typeof error === "object" && - "name" in error && - typeof error.name === "string" - ) { - return error.name; - } - return ""; -} - -/** - * Maps the closed DOMException vocabulary without exposing an exception - * object, message, key or stored value across the adapter boundary. - */ -export function mapIndexedDbException( - error: unknown, - operation: BrowserDataOperation, -): BrowserDataResult { - switch (exceptionName(error)) { - case "AbortError": - return browserDataFailure("ABORTED", operation); - case "ConstraintError": - return browserDataFailure("CONFLICT", operation); - case "DataCloneError": - case "DataError": - return browserDataFailure("CORRUPT_DATA", operation, { - recovery: "READ_ONLY", - }); - case "InvalidAccessError": - case "InvalidStateError": - case "NotFoundError": - case "ReadOnlyError": - case "TransactionInactiveError": - case "VersionError": - return browserDataFailure("MIGRATION_FAILED", operation, { - recovery: "READ_ONLY", - }); - case "NotAllowedError": - case "SecurityError": - return browserDataFailure("PERMISSION_DENIED", operation, { - recovery: "ONLINE_ONLY", - }); - case "NotReadableError": - return browserDataFailure("NOT_READABLE", operation, { - retryable: true, - recovery: "REOPEN", - }); - case "QuotaExceededError": - case "NS_ERROR_DOM_QUOTA_REACHED": - return browserDataFailure("QUOTA_EXCEEDED", operation, { - recovery: "READ_ONLY", - }); - case "UnknownError": - return browserDataFailure("UNAVAILABLE", operation, { - retryable: true, - recovery: "REOPEN", - }); - default: - return browserDataFailure("UNAVAILABLE", operation, { - retryable: true, - recovery: "RETRY", - }); - } -} diff --git a/src/adapters/storage/indexeddb/indexeddb-maintenance.ts b/src/adapters/storage/indexeddb/indexeddb-maintenance.ts index 7d8debee..dafa7b6a 100644 --- a/src/adapters/storage/indexeddb/indexeddb-maintenance.ts +++ b/src/adapters/storage/indexeddb/indexeddb-maintenance.ts @@ -12,6 +12,7 @@ import { abortedResult, browserDataFailure, browserDataSuccess, + mapIndexedDbException, } from "../../browser-file-storage/result.ts"; import { openIndexedDbDatabase, @@ -24,7 +25,6 @@ import { type IndexedDbBudget, type IndexedDbTransactionContext, } from "../../platform/indexeddb-transaction.ts"; -import { mapIndexedDbException } from "./indexeddb-failure.ts"; import { createIndexedDbDatasetBinding, indexedDbPhysicalDatabaseName, @@ -322,10 +322,9 @@ export function createIndexedDbMaintenance( } /** - * STO-06. Maintenance keeps `mapIndexedDbException`, which the runtime and - * the OPFS journal share, rather than the checkpoint store's own table: the - * same native error is a different answer in the two families, and unifying - * them is a separate change from moving the mechanics onto the kernel. + * STO-06. Maintenance uses `mapIndexedDbException`, the one IndexedDB table + * in `browser-file-storage/result.ts` that the runtime and the OPFS journal + * share (05-11). * * One translator covers the whole adapter because the operation label is the * constant `INDEXEDDB_MIGRATE` here — the runtime needs one per operation. diff --git a/src/adapters/storage/indexeddb/indexeddb-runtime.ts b/src/adapters/storage/indexeddb/indexeddb-runtime.ts index abb7059d..31a2072c 100644 --- a/src/adapters/storage/indexeddb/indexeddb-runtime.ts +++ b/src/adapters/storage/indexeddb/indexeddb-runtime.ts @@ -20,6 +20,7 @@ import { abortedResult, browserDataFailure, browserDataSuccess, + mapIndexedDbException, } from "../../browser-file-storage/result.ts"; import { snapshotAbortTimers } from "../../platform/abortable-operation.ts"; import { @@ -36,7 +37,6 @@ import { type IndexedDbCursorVisit, type IndexedDbTransactionContext, } from "../../platform/indexeddb-transaction.ts"; -import { mapIndexedDbException } from "./indexeddb-failure.ts"; import { createIndexedDbDatasetBinding, indexedDbPhysicalDatabaseName, @@ -559,10 +559,9 @@ export function createIndexedDbRuntime( } /** - * STO-06. The runtime keeps `mapIndexedDbException`, which maintenance and - * the OPFS journal share, rather than the checkpoint store's own table: the - * same native error is a different answer in the two families, and unifying - * them is a separate change from moving the mechanics onto the kernel. + * STO-06. The runtime uses `mapIndexedDbException`, the one IndexedDB table + * in `browser-file-storage/result.ts` that maintenance and the OPFS journal + * share (05-11). * * A translator per operation, because a read, a write and an open carry * different labels. `CLOSED` is mapped explicitly: closing the handle while diff --git a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts index e1dcb5d2..9a7a2358 100644 --- a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts +++ b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts @@ -17,6 +17,7 @@ import { import { browserDataFailure, browserDataSuccess, + mapIndexedDbException, } from "../../browser-file-storage/result.ts"; import { snapshotAbortTimers } from "../../platform/abortable-operation.ts"; import { @@ -31,7 +32,6 @@ import { type IndexedDbRequestSink, type IndexedDbTransactionContext, } from "../../platform/indexeddb-transaction.ts"; -import { mapIndexedDbException } from "../indexeddb/indexeddb-failure.ts"; import { isValidOpfsStorageScope } from "./opfs-policy.ts"; import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts"; @@ -1676,10 +1676,9 @@ function limitExceeded( } /** - * STO-01. The journal keeps `mapIndexedDbException`, which the IndexedDB - * runtime and maintenance share, rather than the checkpoint store's own table: - * the same native error is a different answer in the two families and unifying - * them is a separate change from moving the mechanics onto the kernel. + * STO-01. The journal uses `mapIndexedDbException`, the one IndexedDB table + * in `browser-file-storage/result.ts` that the IndexedDB runtime and + * maintenance share (05-11). It imports nothing from `storage/indexeddb/`. * * A translator per operation, because the journal labels a read and a write * differently. The connection always translates as `INDEXEDDB_OPEN`: an open diff --git a/tests/unit/indexeddb-runtime.test.ts b/tests/unit/indexeddb-runtime.test.ts index 064d6317..1d3e7588 100644 --- a/tests/unit/indexeddb-runtime.test.ts +++ b/tests/unit/indexeddb-runtime.test.ts @@ -6,7 +6,7 @@ import type { IndexedDbObservation, IndexedDbRuntimeDependencies, } from "../../src/adapters/storage/indexeddb/indexeddb-types.ts"; -import { mapIndexedDbException } from "../../src/adapters/storage/indexeddb/indexeddb-failure.ts"; +import { mapIndexedDbException } from "../../src/adapters/browser-file-storage/result.ts"; import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; type Item = Readonly<{ From e505a65c8087ef0d27a9a8b09ce3af85a0040d60 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:54:48 +0900 Subject: [PATCH 12/14] refactor(storage): verify the IndexedDB dataset binding on the kernel transaction (05-12) verifyIndexedDbDatasetBinding wired oncomplete, onabort, onerror and the caller abort by hand, the last copy of the transaction state machine outside the kernel, and missed the kernel's rule for an abort after commit. It now runs on runIndexedDbTransaction and onIndexedDbRequest with the same verdicts. Co-Authored-By: Claude Opus 5.5 --- .../storage/indexeddb/indexeddb-governance.ts | 157 +++++++----------- 1 file changed, 64 insertions(+), 93 deletions(-) diff --git a/src/adapters/storage/indexeddb/indexeddb-governance.ts b/src/adapters/storage/indexeddb/indexeddb-governance.ts index 1fc0c6c5..296f7c37 100644 --- a/src/adapters/storage/indexeddb/indexeddb-governance.ts +++ b/src/adapters/storage/indexeddb/indexeddb-governance.ts @@ -3,6 +3,10 @@ import { assertValidStoragePolicy, type BrowserStoragePolicy, } from "../../../application/ports/browser-file-storage/shared.ts"; +import { + onIndexedDbRequest, + runIndexedDbTransaction, +} from "../../platform/indexeddb-transaction.ts"; import { INDEXEDDB_DATASET_BUDGET_KEY, isStoredDatasetBudget, @@ -219,105 +223,72 @@ export function queueIndexedDbUpgradeBinding( /** * Post-open verification protects non-upgrade opens and maintenance callers. + * 05-12. It runs on the kernel transaction, so settle-once, caller abort and + * the abort-after-commit rule (CP-4) are the kernel's, not a local copy's. */ -export function verifyIndexedDbDatasetBinding( +export async function verifyIndexedDbDatasetBinding( database: IDBDatabase, governanceStore: string, expected: StoredDatasetBinding, signal?: AbortSignal, ): Promise { - if (signal?.aborted) { - return Promise.resolve({ ok: false, reason: "ABORTED" }); - } - let transaction: IDBTransaction; - try { - transaction = database.transaction(governanceStore, "readonly"); - } catch (error) { - return Promise.resolve({ - ok: false, - reason: "NATIVE_ERROR", - error, - }); - } - - return new Promise((resolve) => { - let settled = false; - let observed: unknown; - let observedBudget: unknown; - let requestError: unknown; - let callerAborted = false; - const finish = (result: IndexedDbBindingVerification) => { - if (settled) return; - settled = true; - signal?.removeEventListener("abort", onAbort); - resolve(result); - }; - function onAbort(): void { - callerAborted = true; - try { - transaction.abort(); - } catch { - // Completion determines the race. - } - } - signal?.addEventListener("abort", onAbort, { once: true }); - - transaction.onerror = () => { - requestError ??= transaction.error; - }; - transaction.onabort = () => - finish( - callerAborted - ? { ok: false, reason: "ABORTED" } - : { - ok: false, - reason: "NATIVE_ERROR", - error: requestError ?? transaction.error, - }, + const outcome = await runIndexedDbTransaction< + IndexedDbBindingVerification, + BindingFailure + >({ + database, + stores: [governanceStore], + mode: "readonly", + signal, + translate: (cause) => + cause.kind === "CALLER_ABORT" + ? { ok: false, reason: "ABORTED" } + : { + ok: false, + reason: "NATIVE_ERROR", + error: cause.kind === "NATIVE_EXCEPTION" ? cause.error : undefined, + }, + queue: (transaction, context) => { + const store = transaction.objectStore(governanceStore); + let observed: unknown; + onIndexedDbRequest( + store.get(INDEXEDDB_DATASET_BINDING_KEY), + context, + (value) => { + observed = value; + }, ); - transaction.oncomplete = () => { - if (observed === undefined) { - finish({ ok: false, reason: "MISSING" }); - } else if (!isStoredDatasetBinding(observed)) { - finish({ ok: false, reason: "CORRUPT" }); - } else if (!sameIndexedDbDatasetBinding(observed, expected)) { - finish({ ok: false, reason: "MISMATCH" }); - } else if ( - !isStoredDatasetBudget(observedBudget) || - observedBudget.usedBytes > expected.storagePolicy.hardBudgetBytes - ) { - finish({ ok: false, reason: "CORRUPT" }); - } else { - finish({ ok: true }); - } - }; - - try { - const request = transaction - .objectStore(governanceStore) - .get(INDEXEDDB_DATASET_BINDING_KEY); - request.onerror = () => { - requestError ??= request.error; - }; - request.onsuccess = () => { - observed = request.result; - }; - const budgetRequest = transaction - .objectStore(governanceStore) - .get(INDEXEDDB_DATASET_BUDGET_KEY); - budgetRequest.onerror = () => { - requestError ??= budgetRequest.error; - }; - budgetRequest.onsuccess = () => { - observedBudget = budgetRequest.result; - }; - } catch (error) { - requestError = error; - try { - transaction.abort(); - } catch { - finish({ ok: false, reason: "NATIVE_ERROR", error }); - } - } + onIndexedDbRequest( + store.get(INDEXEDDB_DATASET_BUDGET_KEY), + context, + (budget) => { + context.succeed(bindingVerdict(observed, budget, expected)); + }, + ); + }, }); + return outcome.ok ? outcome.value : outcome.error; +} + +type BindingFailure = Extract; + +function bindingVerdict( + observed: unknown, + budget: unknown, + expected: StoredDatasetBinding, +): IndexedDbBindingVerification { + if (observed === undefined) return { ok: false, reason: "MISSING" }; + if (!isStoredDatasetBinding(observed)) { + return { ok: false, reason: "CORRUPT" }; + } + if (!sameIndexedDbDatasetBinding(observed, expected)) { + return { ok: false, reason: "MISMATCH" }; + } + if ( + !isStoredDatasetBudget(budget) || + budget.usedBytes > expected.storagePolicy.hardBudgetBytes + ) { + return { ok: false, reason: "CORRUPT" }; + } + return { ok: true }; } From 9733ea8eaaa898e42ae728852ab1aea96b9b9a2b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:57:51 +0900 Subject: [PATCH 13/14] fix(storage): close an IndexedDB connection that gets versionchange during admission (05-13) The versionchange handler was installed only after the asynchronous admission finished, so another tab's upgrade that arrived in that window waited blocked until its deadline and failed. The kernel now installs a handler for the admission window that closes the connection and ends the open as CLOSED. Co-Authored-By: Claude Opus 5.5 --- src/adapters/platform/indexeddb-connection.ts | 10 ++++++ tests/unit/indexeddb-connection.test.ts | 32 +++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/src/adapters/platform/indexeddb-connection.ts b/src/adapters/platform/indexeddb-connection.ts index b7476442..9ba02c16 100644 --- a/src/adapters/platform/indexeddb-connection.ts +++ b/src/adapters/platform/indexeddb-connection.ts @@ -427,6 +427,16 @@ export function openIndexedDbDatabase( settle(succeeded(database)); return; } + // 05-13. Admission is asynchronous and nothing else answers another + // context's upgrade until the caller adopts the connection, so that + // upgrade would wait blocked until its deadline. While admission runs, a + // versionchange closes this connection and ends the open as CLOSED. An + // `admit` that installs its own handler replaces this one. + database.onversionchange = () => { + if (settled) return; + closeQuietly(database); + settleFailure({ kind: "CLOSED" }); + }; let admission: IndexedDbAdmission | Promise; try { admission = input.admit(database); diff --git a/tests/unit/indexeddb-connection.test.ts b/tests/unit/indexeddb-connection.test.ts index 636f0bf5..d6b102fa 100644 --- a/tests/unit/indexeddb-connection.test.ts +++ b/tests/unit/indexeddb-connection.test.ts @@ -943,3 +943,35 @@ describe("IndexedDB database deletion", () => { }); }); }); + +describe("05-13 a versionchange that arrives while admission runs", () => { + it("closes the connection and ends the open instead of blocking the upgrade", async () => { + const memory = new MemoryIndexedDbFactory(); + let admitting!: () => void; + const admissionStarted = new Promise((resolve) => { + admitting = resolve; + }); + let finishAdmission!: () => void; + const pending = openIndexedDbDatabase({ + factory: memory.factory, + databaseName: "kernel", + version: 1, + translate: recordingTranslate([]), + upgrade: () => ({ kind: "APPLIED" }), + admit: async () => { + admitting(); + await new Promise((resolve) => { + finishAdmission = resolve; + }); + return { kind: "ADMIT" }; + }, + }); + await admissionStarted; + + // Another context asks to upgrade while this one is still admitting. + memory.triggerVersionChange(2); + expect(memory.isConnectionClosed()).toBe(true); + finishAdmission(); + expect(await pending).toEqual({ ok: false, error: { cause: "CLOSED" } }); + }); +}); From e872bfa27dee6455175a257db9fa7bf2b8ba0dc0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:59:43 +0900 Subject: [PATCH 14/14] docs(storage): state that a stream can outlive a replaced OPFS generation (05-14) Orphan GC counts its grace from when a chunk was written, so a read of an older generation can lose its chunks once a newer put commits. Refreshing every dropped chunk would rewrite whole objects, so the port now states the contract instead: the stream ends NOT_FOUND / REHYDRATE and a reopen reads the new generation. A test pins that outcome. Co-Authored-By: Claude Opus 5.5 --- .../ports/browser-file-storage/opfs-ports.ts | 8 +++ tests/unit/opfs-worker-runtime.test.ts | 51 +++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index 7091ab07..b0971694 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -85,6 +85,14 @@ export interface DurableObjectStorePort { put( request: PutDurableObjectRequest, ): Promise>; + /** + * 05-14. `open` checks the manifest; the bytes are read and verified while + * the source streams. A put that replaces the object meanwhile leaves the + * older generation's chunks to orphan GC, whose grace counts from when a + * chunk was written, not from when it lost its last reference. A stream + * that reaches a chunk GC already took ends with `NOT_FOUND` / `REHYDRATE`. + * Nothing is lost: open again to read the generation that replaced it. + */ open( request: OpenDurableObjectRequest, ): Promise>; diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index d1b1bae3..b36b5115 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -2454,3 +2454,54 @@ describe("05-10 the object id grammar is the prepared-object grammar", () => { ).toThrow(TypeError); }); }); + +describe("05-14 a read that outlives its generation", () => { + it("ends with NOT_FOUND / REHYDRATE once GC took the replaced chunks, and a reopen reads the new generation", async () => { + const { root, tab } = sharedRootTabs(); + const store = tab("r"); + const put = (bytes: number[], expectedGeneration: number | null) => + store.objects.put({ + objectId: "object_12345678", + expectedGeneration, + mediaType: "application/octet-stream", + source: bytesSource(new Uint8Array(bytes)), + }); + expect(await put([1], null)).toMatchObject({ ok: true }); + const opened = await store.objects.open({ objectId: "object_12345678" }); + if (!opened.ok) throw new Error(opened.error.code); + + // Generation 2 replaces it, and its old chunk is past the GC grace. + expect(await put([2], 1)).toMatchObject({ ok: true }); + const digest = Array.from( + new Uint8Array( + await globalThis.crypto.subtle.digest("SHA-256", new Uint8Array([1])), + ), + (byte) => byte.toString(16).padStart(2, "0"), + ).join(""); + memoryFileAt(root, chunkFilePath(scopeA, digest)).lastModified = 0; + expect(await store.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { deletedOrphanChunks: 1 }, + }); + + const chunks = []; + for await (const chunk of opened.value.source.stream( + new AbortController().signal, + )) { + chunks.push(chunk); + } + expect(chunks).toEqual([ + expect.objectContaining({ + ok: false, + error: expect.objectContaining({ + code: "NOT_FOUND", + recovery: "REHYDRATE", + }), + }), + ]); + expect(await openedBytes(store, "object_12345678")).toEqual({ + generation: 2, + bytes: [2], + }); + }); +});