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" }, + }); + }); +});