fix(storage): 소속 partition이 없는 손상 journal 행을 따로 세고 경보에서 뺀다
문제: partition 삭제는 journal 행을 LOGICAL_KEY_INDEX로 찾는다. 인덱스에는 logicalKey 값이 있는 행만 들어가므로, 그 값까지 깨진 행은 승인된 ACCOUNT_DELETION으로도 지워지지 않는다(X4: partition 파일 0개인데 행은 남음). 그 행은 reconcile마다 corruptTransactions 1, OBJECT_RECONCILE DEGRADED/CORRUPT_DATA로 남는다. runbook은 "키로 찾으므로 손상 row도 지워진다", "partition이 승인된 purge로 지워질 때만 함께 지워진다"고 적고 수동 삭제를 금지한다. 운영자는 늘 켜진 경보를 받지만 할 수 있는 일이 없고, 그 경보가 진짜 손상을 가린다. 고른 방법(리뷰 (a)+(b)): 소속을 모르는 행은 지울 근거가 없으므로 지우지 않는다. 대신 - journal의 listIncomplete가 손상 행 가운데 이 authority의 partition 키 범위에 들지 않는 행을 unattributedRows로 따로 센다(0이면 칸 없음). - reconcile report에 unattributedCorruptTransactions를 싣고(0이면 칸 없음), DEGRADED 관측은 purge가 지울 수 있는 손상 행이 있을 때만 낸다. - runbook §0·§7 문장을 코드와 맞추고, 이런 행에 대해 할 일(같은 수면 없음, 늘면 writer를 찾음, 수동 삭제 금지)을 적었다. 버린 대안: (a)만 — 경보가 계속 켜진다. (c) 소속을 모르는 행 자동 삭제 — 그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번). 위험·한계: 공개 타입에 선택 칸 두 개가 는다(OpfsJournalPage .unattributedRows, OpfsReconciliationReport .unattributedCorruptTransactions). 직접 만든 journal이 칸을 채우지 않으면 지금처럼 모든 손상 행이 경보에 남는다. 소속 없는 행만 있을 때 관측이 SUCCEEDED가 되므로, 그 수는 report로만 보인다. 이런 행의 staging은 purge의 partition 삭제 조건(countPartitionTransactions)에 잡히지 않는다. offline-indexeddb 번들 37,555 → 37,705 / 38,500 gzip B. 검증: - RED: indexeddb-opfs-journal.test.ts 새 테스트가 unattributedRows 없음, opfs-worker-runtime.test.ts 새 X4 테스트가 unattributedCorruptTransactions 없음으로 실패. - GREEN: 키 있는 손상 행은 removePartition이 지우고 키 없는 행은 남는다. 키 없는 행만 있으면 관측 SUCCEEDED, 키 있는 손상 행이 더해지면 DEGRADED:CORRUPT_DATA. OPFS 단위 3파일 + optional-runtime-host + tests/recipes + tests/contract 176건 통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-03
This commit is contained in:
@@ -38,8 +38,18 @@ cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답
|
||||
저장소 손상이다. 예전에는 이런 row 하나가 목록 전체를 실패시켜 authority의
|
||||
모든 partition에서 reconcile과 GC가 멈췄다. 이제 나머지 row와 orphan GC는
|
||||
계속 돌고, 관측은 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 남는다
|
||||
([0929] 05-01). reconcile은 그 row를 지우지 않는다. 그 row가 속한
|
||||
partition이 승인된 purge로 통째로 지워질 때만 함께 지워진다(§7).
|
||||
([0929] 05-01). reconcile은 그 row를 지우지 않는다. 그 partition이 승인된
|
||||
purge로 통째로 지워질 때 함께 지워지는 것은 partition 키(`logicalKey`)를
|
||||
읽을 수 있는 row뿐이다(§7). 승인된 LOGOUT/ACCOUNT_DELETION purge는 그런
|
||||
row를 보면 그 partition을 지운다(2026-11-03 05-01).
|
||||
- `unattributedCorruptTransactions`: 위 수 가운데 `logicalKey`까지 읽을 수
|
||||
없는 row 수다. 어느 partition에도 속하지 않아 partition 삭제도 지우지
|
||||
못한다. 그래서 따로 세고 `DEGRADED` 관측에서 뺀다(2026-11-03 05-03). 예전에는
|
||||
이런 row 하나가 reconcile마다 `DEGRADED`를 남겨 경보가 늘 켜졌다. 같은 수로
|
||||
남아 있으면 할 일이 없다. 수가 늘면 키 없는 row를 쓴 writer(다른 release,
|
||||
외부 도구)를 찾는다. 이 row도 수동으로 지우지 않는다(3번). 그 row의
|
||||
staging은 partition 디렉터리 안에 있어 그 partition이 지워지면 함께
|
||||
지워지지만, 이 row는 purge의 partition 삭제 조건에 들지 않는다.
|
||||
3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할
|
||||
근거가 사라지고 quota만 누수된다.
|
||||
4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지
|
||||
@@ -466,8 +476,10 @@ VD-15 목표 runtime을 먼저 구현한다.
|
||||
- 범위: worker가 origin mutation lease를 쥔 채
|
||||
`authorities/<authorityToken>/<namespaceToken>/<partitionToken>` 디렉터리를
|
||||
지우고, 이어서 journal에서 그 partition 키로 시작하는 object·journal·chunk
|
||||
reference row와 budget row를 지운다. 값을 읽지 않고 키로 찾으므로 손상 row도
|
||||
지워진다. scope binding row는 남긴다. 다른 partition은 건드리지 않는다.
|
||||
reference row와 budget row를 지운다. 값을 읽지 않고 키로 찾으므로 키가 남은
|
||||
손상 row도 지워진다. journal row는 `logicalKey` 인덱스로 찾으므로 그 값까지
|
||||
깨진 row는 남는다(§0 2번 `unattributedCorruptTransactions`). scope binding
|
||||
row는 남긴다. 다른 partition은 건드리지 않는다.
|
||||
- 결과: `partitionDeleted: true`, `moreObjectsAvailable: false`, 건너뛴 row 수
|
||||
`corruptObjects`. 이 report면 그 partition의 bytes는 모두 지워진 것이다.
|
||||
`chunkSweep`은 없다. 디렉터리는 지웠는데 journal 정리가 실패하면 실패를
|
||||
|
||||
@@ -699,6 +699,7 @@ export function createIndexedDbOpfsJournal(
|
||||
(transaction, context) => {
|
||||
const rows: OpfsJournalTransaction[] = [];
|
||||
let corruptRows = 0;
|
||||
let unattributedRows = 0;
|
||||
walkIndexedDbCursor<BrowserDataFailure>({
|
||||
request: transaction
|
||||
.objectStore(JOURNAL_STORE)
|
||||
@@ -720,6 +721,8 @@ export function createIndexedDbOpfsJournal(
|
||||
rows.push(cursor.value);
|
||||
} else {
|
||||
corruptRows += 1;
|
||||
// 2026-11-03 05-03. No partition's key range holds it.
|
||||
if (!hasPartitionKey(cursor.value)) unattributedRows += 1;
|
||||
}
|
||||
return { kind: "CONTINUE" };
|
||||
},
|
||||
@@ -730,6 +733,7 @@ export function createIndexedDbOpfsJournal(
|
||||
moreAvailable:
|
||||
summary.reason === "STOPPED" && rows.length === limit,
|
||||
corruptRows,
|
||||
...(unattributedRows ? { unattributedRows } : {}),
|
||||
}),
|
||||
);
|
||||
},
|
||||
@@ -969,6 +973,27 @@ export function createIndexedDbOpfsJournal(
|
||||
|
||||
return Object.freeze(journal);
|
||||
|
||||
/**
|
||||
* 2026-11-03 05-03. Whether a row's `logicalKey` lies in the key range
|
||||
* `removePartition` deletes for some partition of this authority.
|
||||
*/
|
||||
function hasPartitionKey(value: unknown): boolean {
|
||||
const key =
|
||||
value && typeof value === "object" && "logicalKey" in value
|
||||
? value.logicalKey
|
||||
: undefined;
|
||||
if (typeof key !== "string") return false;
|
||||
const [authority, namespaceToken, partitionToken, objectId] =
|
||||
key.split("|");
|
||||
return (
|
||||
authority === dependencies.authorityToken &&
|
||||
objectId !== undefined &&
|
||||
[namespaceToken, partitionToken].every(
|
||||
(token) => token !== undefined && SAFE_BOUNDARY_ID.test(token),
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
async function commitMutation(
|
||||
transactionId: string,
|
||||
fencingToken: string,
|
||||
|
||||
@@ -639,6 +639,7 @@ export function createOpfsByteStoreAdapter(
|
||||
// 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<string, () => void>();
|
||||
let unattributed: number;
|
||||
try {
|
||||
for (const transaction of listed.value.transactions) {
|
||||
let release: (() => void) | null;
|
||||
@@ -663,6 +664,7 @@ export function createOpfsByteStoreAdapter(
|
||||
report.moreTransactionsAvailable = page.value.moreAvailable;
|
||||
// [0929] 05-01. The journal skipped these rows; they stop nothing now.
|
||||
report.corruptTransactions = page.value.corruptRows;
|
||||
unattributed = page.value.unattributedRows ?? 0;
|
||||
for (const transaction of page.value.transactions) {
|
||||
if (!held.has(transaction.transactionId)) continue;
|
||||
if (request.signal?.aborted) {
|
||||
@@ -709,12 +711,19 @@ export function createOpfsByteStoreAdapter(
|
||||
operation: "OBJECT_RECONCILE",
|
||||
transactionBucket: transactionBucket(report.inspectedTransactions),
|
||||
// A skipped corrupt row is observed, not hidden behind a success.
|
||||
...(report.corruptTransactions
|
||||
// 2026-11-03 05-03. One no partition owns is reported, not observed:
|
||||
// nothing clears it, so it would keep the signal on for good.
|
||||
...(report.corruptTransactions > unattributed
|
||||
? { outcome: "DEGRADED", failureCode: "CORRUPT_DATA" }
|
||||
: { outcome: "SUCCEEDED" }),
|
||||
});
|
||||
return browserDataSuccess<OpfsReconciliationReport>(
|
||||
Object.freeze({ ...report }),
|
||||
Object.freeze({
|
||||
...report,
|
||||
...(unattributed
|
||||
? { unattributedCorruptTransactions: unattributed }
|
||||
: {}),
|
||||
}),
|
||||
);
|
||||
},
|
||||
|
||||
|
||||
@@ -131,6 +131,13 @@ export type OpfsReconciliationReport = Readonly<{
|
||||
* zero is storage damage for an operator to look at.
|
||||
*/
|
||||
corruptTransactions: number;
|
||||
/**
|
||||
* 2026-11-03 05-03. Of `corruptTransactions`, the rows whose partition key
|
||||
* cannot be read either. No approved partition delete takes them, so they
|
||||
* stay; they are not observed as `DEGRADED`, which is kept for damage a
|
||||
* purge can clear. Present only when there were some.
|
||||
*/
|
||||
unattributedCorruptTransactions?: number;
|
||||
}>;
|
||||
|
||||
export type OpfsPolicyMaintenanceReport = Readonly<{
|
||||
@@ -324,6 +331,12 @@ export type OpfsJournalPage = Readonly<{
|
||||
transactions: readonly OpfsJournalTransaction[];
|
||||
moreAvailable: boolean;
|
||||
corruptRows: number;
|
||||
/**
|
||||
* 2026-11-03 05-03. Of `corruptRows`, the rows without a readable partition
|
||||
* key, which `removePartition` never reaches. Absent means none, or a
|
||||
* journal that does not tell them apart.
|
||||
*/
|
||||
unattributedRows?: number;
|
||||
}>;
|
||||
|
||||
export type OpfsCommittedObjectPage = Readonly<{
|
||||
|
||||
@@ -508,7 +508,12 @@ describe("IndexedDB OPFS journal", () => {
|
||||
// [0929] 05-01. The row is counted, not returned and not deleted.
|
||||
expect(await journal.listIncomplete(10)).toEqual({
|
||||
ok: true,
|
||||
value: { transactions: [], moreAvailable: false, corruptRows: 1 },
|
||||
value: {
|
||||
transactions: [],
|
||||
moreAvailable: false,
|
||||
corruptRows: 1,
|
||||
unattributedRows: 1,
|
||||
},
|
||||
});
|
||||
expect(factory.readRaw("opfs-journal", "transaction_88888888")).toMatchObject({
|
||||
corrupt: true,
|
||||
@@ -865,6 +870,54 @@ describe("[0929] 05-01 a corrupt row is skipped and counted; a partition's rows
|
||||
).toMatchObject({ preparedObject: { corrupt: true } });
|
||||
});
|
||||
|
||||
// 2026-11-03 05-03. The partition delete finds journal rows by their
|
||||
// `logicalKey`. A damaged row that still has one goes with its partition; a
|
||||
// row without one belongs to no partition, so no delete takes it. The page
|
||||
// tells the two apart so an operator can.
|
||||
it("tells a damaged journal row its partition delete takes from one no partition owns", async () => {
|
||||
const { factory, journal } = createHarness();
|
||||
// Opens the database the seeds below write into.
|
||||
expect(await journal.listIncomplete(10)).toMatchObject({ ok: true });
|
||||
factory.seed("opfs-journal", {
|
||||
transactionId: "transaction_keyed001",
|
||||
logicalKey: `${scopeKeyOf(scope)}|object_aaaa0001`,
|
||||
startedAtEpochMs: 1,
|
||||
phase: "GARBLED",
|
||||
});
|
||||
factory.seed("opfs-journal", {
|
||||
transactionId: "transaction_keyless1",
|
||||
startedAtEpochMs: 2,
|
||||
corrupt: true,
|
||||
});
|
||||
|
||||
expect(await journal.listIncomplete(10)).toEqual({
|
||||
ok: true,
|
||||
value: {
|
||||
transactions: [],
|
||||
moreAvailable: false,
|
||||
corruptRows: 2,
|
||||
unattributedRows: 1,
|
||||
},
|
||||
});
|
||||
expect(await journal.removePartition(scope)).toMatchObject({ ok: true });
|
||||
|
||||
expect(
|
||||
factory.readRaw("opfs-journal", "transaction_keyed001"),
|
||||
).toBeUndefined();
|
||||
expect(
|
||||
factory.readRaw("opfs-journal", "transaction_keyless1"),
|
||||
).toMatchObject({ corrupt: true });
|
||||
expect(await journal.listIncomplete(10)).toEqual({
|
||||
ok: true,
|
||||
value: {
|
||||
transactions: [],
|
||||
moreAvailable: false,
|
||||
corruptRows: 1,
|
||||
unattributedRows: 1,
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("counts the unfinished rows of one partition, a damaged one included (2026-11-03 05-01)", async () => {
|
||||
const { factory, journal } = createHarness();
|
||||
await commitObject(journal, "transaction_obj00001", "object_aaaa0001", 1);
|
||||
|
||||
@@ -2720,6 +2720,60 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh
|
||||
});
|
||||
});
|
||||
|
||||
// 2026-11-03 05-03 X4. A damaged journal row without a readable partition
|
||||
// key outlives every approved partition delete. It used to keep each
|
||||
// reconcile DEGRADED for good, with nothing the runbook lets anyone do. It
|
||||
// is now counted apart and kept out of the partition damage signal; a row
|
||||
// its partition delete would take still raises it.
|
||||
it("reports a damaged journal row no partition owns apart from partition damage", async () => {
|
||||
const { root, idb, tab } = sharedRootTabs();
|
||||
const outcomes: string[] = [];
|
||||
const store = tab("s", {
|
||||
...authority,
|
||||
observer: (observation) => {
|
||||
if (
|
||||
observation.operation === "OBJECT_RECONCILE" &&
|
||||
observation.outcome !== "STARTED"
|
||||
) {
|
||||
outcomes.push(`${observation.outcome}:${observation.failureCode ?? ""}`);
|
||||
}
|
||||
},
|
||||
});
|
||||
expect(await putBytes(store, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true });
|
||||
idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2"));
|
||||
idb.seed("opfs-journal", {
|
||||
transactionId: "transaction_corrupt1",
|
||||
startedAtEpochMs: 1,
|
||||
corrupt: true,
|
||||
});
|
||||
|
||||
expect(
|
||||
await store.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }),
|
||||
).toMatchObject({ ok: true, value: { partitionDeleted: true } });
|
||||
expect(filesUnder(root, scopeA)).toEqual([]);
|
||||
expect(idb.readRaw("opfs-journal", "transaction_corrupt1")).toMatchObject({
|
||||
corrupt: true,
|
||||
});
|
||||
|
||||
expect(await store.maintenance.reconcile()).toMatchObject({
|
||||
ok: true,
|
||||
value: { corruptTransactions: 1, unattributedCorruptTransactions: 1 },
|
||||
});
|
||||
expect(outcomes).toEqual(["SUCCEEDED:"]);
|
||||
|
||||
idb.seed("opfs-journal", {
|
||||
transactionId: "transaction_keyed001",
|
||||
logicalKey: `${scopeA.authorityToken}|${scopeA.namespaceToken}|${scopeA.partitionToken}|object_secret_3`,
|
||||
startedAtEpochMs: 2,
|
||||
phase: "GARBLED",
|
||||
});
|
||||
expect(await store.maintenance.reconcile()).toMatchObject({
|
||||
ok: true,
|
||||
value: { corruptTransactions: 2, unattributedCorruptTransactions: 1 },
|
||||
});
|
||||
expect(outcomes.at(-1)).toBe("DEGRADED:CORRUPT_DATA");
|
||||
});
|
||||
|
||||
it("removes a partition directory only under the origin mutation lease", async () => {
|
||||
const root = new MemoryDirectory();
|
||||
const leases = exclusiveLeases();
|
||||
|
||||
Reference in New Issue
Block a user