diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 074dd405..ddf1006d 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -489,7 +489,10 @@ VD-15 목표 runtime을 먼저 구현한다. approved purge meets another tab's put parked before …"(5가지 순서). - 한계: 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle bound(05-07)까지 삭제를 붙잡는다. purge의 `signal`을 abort하면 기다림을 - 멈추고 `ABORTED`를 반환한다. purge가 journal row를 센 뒤에 시작한 put, 삭제가 + 멈추고 `ABORTED`를 반환한다. 삭제 뒤에 줄 선 put·delete도 자기 `signal`로 + 기다림을 멈춘다. 어느 쪽이든 partition lock 기다림은 + `mutationLockWaitTimeoutMs`(기본 10분)에서 `BLOCKED`(retryable)로 끝난다 + (2026-11-03 05-02). purge가 journal row를 센 뒤에 시작한 put, 삭제가 lock을 요청한 뒤 온 put의 데이터는 남는다(point-in-time). purge 전에 그 partition의 쓰기를 멈추는 것이 composition의 몫이다. - lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index f2b8e2ad..3912218f 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -23,6 +23,7 @@ import { browserDataFailure, browserDataSuccess, } from "../../browser-file-storage/result.ts"; +import { createAbortableOperation } from "../../platform/abortable-operation.ts"; import { byteBucket, observeOpfsSafely, @@ -221,6 +222,7 @@ export function createOpfsByteStoreAdapter( return await withTransactionLock( transactionId, "OBJECT_WRITE", + request.signal, async () => { // STO-01. The logical generation is reused across transactions; this // token makes the physical target unique so a late compensation can never @@ -495,6 +497,7 @@ export function createOpfsByteStoreAdapter( return await withTransactionLock( transactionId, "OBJECT_DELETE", + request.signal, async () => { const begun = await dependencies.journal.begin({ transactionId, @@ -1118,6 +1121,7 @@ export function createOpfsByteStoreAdapter( async function withTransactionLock( transactionId: string, operation: "OBJECT_WRITE" | "OBJECT_DELETE", + signal: AbortSignal | undefined, run: () => Promise>, ): Promise> { let release: (() => void) | null; @@ -1132,7 +1136,7 @@ export function createOpfsByteStoreAdapter( // A fresh transaction id is never held; a holder means a duplicate id. if (!release) return browserDataFailure("CONFLICT", operation); try { - return await withPartitionLock("shared", operation, undefined, run); + return await withPartitionLock("shared", operation, signal, run); } finally { release(); } @@ -1147,6 +1151,11 @@ export function createOpfsByteStoreAdapter( * files after the directory went, the second step took its journal row, and * nothing was left to clean those files. Tested by "leaves no partition * bytes when an approved purge meets another tab's put parked before …". + * + * 2026-11-03 05-02. The wait ends on the caller's own abort and, like the + * worker's origin lease, at `mutationLockWaitTimeoutMs` as a retryable + * BLOCKED. A put or delete queued behind a long partition delete used to + * ignore its signal until that delete let go. */ async function withPartitionLock( mode: LockMode, @@ -1154,24 +1163,34 @@ export function createOpfsByteStoreAdapter( signal: AbortSignal | undefined, run: () => Promise>, ): Promise> { + const wait = createAbortableOperation({ + ...(signal ? { signal } : {}), + timeoutMs: policy.mutationLockWaitTimeoutMs, + }); let granted = false; try { return await requestLock( `${policy.mutationLockName}:partition:${scope.authorityToken}:${scope.namespaceToken}:${scope.partitionToken}`, - { mode, ...(signal ? { signal } : {}) }, + { mode, signal: wait.signal }, async () => { granted = true; + // Only the wait is bounded; aborting a granted request is a no-op. + wait.close(); return await run(); }, ); } catch (error) { if (granted) throw error; - return signal?.aborted + const terminal = wait.terminal(); + return terminal === "CALLER_ABORT" ? browserDataFailure("ABORTED", operation) - : browserDataFailure("UNAVAILABLE", operation, { - retryable: true, - recovery: "RETRY", - }); + : browserDataFailure( + terminal === "DEADLINE" ? "BLOCKED" : "UNAVAILABLE", + operation, + { retryable: true, recovery: "RETRY" }, + ); + } finally { + wait.close(); } } diff --git a/src/adapters/storage/opfs/opfs-policy.ts b/src/adapters/storage/opfs/opfs-policy.ts index c0776aa8..f15e415d 100644 --- a/src/adapters/storage/opfs/opfs-policy.ts +++ b/src/adapters/storage/opfs/opfs-policy.ts @@ -17,7 +17,9 @@ export type OpfsRuntimePolicy = Readonly<{ /** * R-5.3 (D-3). How long a request may queue for the origin mutation lock. * Another context's put holds that lock for its whole upload, so this wait - * is bounded on its own and never counted against `rpcTimeoutMs`. + * is bounded on its own and never counted against `rpcTimeoutMs`. The page + * bounds its wait for the partition lock by the same value (2026-11-03 + * 05-02). */ mutationLockWaitTimeoutMs: number; /** diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index 5e1aa194..35d66fcd 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -2900,6 +2900,131 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh }); }); +// 2026-11-03 05-02. A put or delete queued behind a partition delete held the +// partition lock request without its caller's signal and without a bound, so +// cancelling it did nothing until the delete let go. +describe("05-02 a put or delete waiting on the partition lock", () => { + const lockName = (policy: typeof runtimePolicy) => + `${policy.mutationLockName}:partition:${scopeA.authorityToken}:${scopeA.namespaceToken}:${scopeA.partitionToken}`; + + afterEach(() => { + vi.useRealTimers(); + }); + + /** Another tab's partition delete holds the lock until `release`. */ + async function heldPartitionLock(policy: typeof runtimePolicy) { + const holding = checkpoint(); + const holder = navigator.locks.request( + lockName(policy), + { mode: "exclusive" }, + () => holding.pass(), + ); + await holding.reached; + return { + async release() { + holding.open(); + await holder; + }, + }; + } + + async function queuedOnPartitionLock( + policy: typeof runtimePolicy, + tick: () => Promise, + ) { + while ( + !(await navigator.locks.query()).pending?.some( + (lock) => lock.name === lockName(policy) && lock.mode === "shared", + ) + ) { + await tick(); + } + } + + const settledWithin = async (work: Promise, ms: number) => + await Promise.race([ + work, + new Promise<"STILL_WAITING">((resolve) => + setTimeout(() => resolve("STILL_WAITING"), ms), + ), + ]); + + it("ends a queued put and a queued delete as soon as their caller aborts", async () => { + const { tab } = sharedRootTabs(); + const store = tab("s"); + expect( + await store.objects.put({ + objectId: "object_kept_0001", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }), + ).toMatchObject({ ok: true }); + const held = await heldPartitionLock(runtimePolicy); + const controller = new AbortController(); + + const put = store.objects.put({ + objectId: "object_aborted01", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + signal: controller.signal, + }); + const removal = store.objects.remove({ + objectId: "object_kept_0001", + expectedGeneration: 1, + signal: controller.signal, + }); + await queuedOnPartitionLock( + runtimePolicy, + () => new Promise((resolve) => setTimeout(resolve, 1)), + ); + controller.abort(); + + expect(await settledWithin(put, 200)).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "OBJECT_WRITE" }, + }); + expect(await settledWithin(removal, 200)).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "OBJECT_DELETE" }, + }); + await held.release(); + expect(await openedBytes(store, "object_aborted01")).toBe("NOT_FOUND"); + expect(await openedBytes(store, "object_kept_0001")).toEqual({ + generation: 1, + bytes: [6], + }); + }); + + it("ends a partition lock wait at the policy bound as a retryable BLOCKED", async () => { + const policy = resolveOpfsRuntimePolicy({ + ...runtimePolicy, + mutationLockWaitTimeoutMs: 300_000, + }); + const { tab } = sharedRootTabs(policy); + const store = tab("s"); + const held = await heldPartitionLock(policy); + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); + + const put = store.objects.put({ + objectId: "object_blocked01", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }); + await queuedOnPartitionLock(policy, () => vi.advanceTimersByTimeAsync(1)); + await vi.advanceTimersByTimeAsync(policy.mutationLockWaitTimeoutMs); + + expect(await put).toMatchObject({ + ok: false, + error: { code: "BLOCKED", operation: "OBJECT_WRITE", retryable: true }, + }); + vi.useRealTimers(); + await held.release(); + }); +}); + /** A step that parks until opened and says when something reached it. */ function checkpoint(): Readonly<{ reached: Promise;