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 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
2b24f6d8f0
commit
4d8ceade21
@@ -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이 실패해도 같다.
|
||||
|
||||
@@ -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 후 제거
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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 =
|
||||
|
||||
@@ -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,
|
||||
),
|
||||
|
||||
Reference in New Issue
Block a user