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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:37:40 +09:00
co-authored by Claude Opus 5.5
parent b87ab5ee8e
commit 7f45afac7d
7 changed files with 168 additions and 3 deletions
@@ -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로 닫는다.
### 안전한 조치
@@ -285,6 +285,14 @@ function unavailable(
});
}
function incompatible(
operation: BrowserDataOperation,
): BrowserDataResult<never> {
return browserDataFailure("UNSUPPORTED", operation, {
recovery: "ONLINE_ONLY",
});
}
function mappedFailure(
error: unknown,
operation: BrowserDataOperation,
@@ -643,6 +651,7 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
// 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<Value, WireValue, Query>(
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<Value, WireValue, Query>(
: 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<Value, WireValue, Query>(
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<ResultValue, BrowserDataFailure>({
@@ -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":
@@ -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 =
@@ -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<string>((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();
}
});
+25
View File
@@ -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<void>((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" },
});
});
});
+40
View File
@@ -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" },
});
});
});