diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 3a96f604..b0a6a2e8 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -360,7 +360,10 @@ resume through upload() 정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다. 현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체 -삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local +삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는 +`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로 +보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다. +`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은 다음을 제공한다. diff --git a/src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts b/src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts index 1861697d..51fc327f 100644 --- a/src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts +++ b/src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts @@ -415,6 +415,45 @@ export function createIndexedDbResumableUploadCheckpointRuntime( ); }, + async removeUnreadable( + inputValue: Parameters< + NonNullable + >[0], + ): Promise> { + if (!SAFE_UPLOAD_KEY.test(inputValue.uploadKey)) { + return browserDataFailure("INVALID_INPUT", OPERATION); + } + const opened = await connection.acquire(inputValue.signal); + if (!opened.ok) return opened; + return await runCheckpointTransaction( + opened.value, + "readwrite", + inputValue.signal, + (nativeStore, context) => { + const request = nativeStore.get(inputValue.uploadKey); + request.onerror = () => context.fail(mappedFailure(request.error)); + request.onsuccess = () => { + // Checked in the same transaction as the delete, so a row another + // context rewrote as a valid checkpoint is never dropped. + if (request.result === undefined) { + context.succeed(undefined); + return; + } + if (isResumableUploadCheckpoint(request.result)) { + context.fail( + checkpointFailure("CONFLICT", { recovery: "RECONCILE" }), + ); + return; + } + const deletion = nativeStore.delete(inputValue.uploadKey); + deletion.onerror = () => + context.fail(mappedFailure(deletion.error)); + deletion.onsuccess = () => context.succeed(undefined); + }; + }, + ); + }, + close() { connection.close(); }, diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index a8868837..315b9626 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -1168,6 +1168,21 @@ async function executeAbort( signal: AbortSignal, ): Promise> { const found = await dependencies.checkpoints.read(uploadKey, signal); + if ( + !found.ok && + found.error.code === "CORRUPT_DATA" && + dependencies.checkpoints.removeUnreadable + ) { + // Q-6.1-6. A row this build cannot read names no session to abort, so + // explicit abort drops it and leaves the server session to expire. + const removed = await dependencies.checkpoints.removeUnreadable({ + uploadKey, + signal, + }); + return removed.ok + ? browserDataSuccess(Object.freeze({ state: "ORPHANED" as const })) + : remapResult(removed, "UPLOAD_ABORT"); + } if (!found.ok) return remapResult(found, "UPLOAD_ABORT"); if (!found.value) { return browserDataSuccess(Object.freeze({ state: "NOT_FOUND" })); @@ -1977,11 +1992,14 @@ function snapshotCheckpointStore( const read = value?.read; const compareAndSwap = value?.compareAndSwap; const remove = value?.remove; + const removeUnreadable = value?.removeUnreadable; const close = value?.close; if ( typeof read !== "function" || typeof compareAndSwap !== "function" || typeof remove !== "function" || + (removeUnreadable !== undefined && + typeof removeUnreadable !== "function") || typeof close !== "function" ) { throw new TypeError("Upload checkpoint store is invalid."); @@ -2005,6 +2023,15 @@ function snapshotCheckpointStore( ) { return await remove.call(value, input); }, + ...(removeUnreadable + ? { + async removeUnreadable( + input: Parameters[0], + ) { + return await removeUnreadable.call(value, input); + }, + } + : {}), close() { close.call(value); }, diff --git a/src/application/ports/browser-transfer/resumable-upload.ts b/src/application/ports/browser-transfer/resumable-upload.ts index 8195ce33..34762ad5 100644 --- a/src/application/ports/browser-transfer/resumable-upload.ts +++ b/src/application/ports/browser-transfer/resumable-upload.ts @@ -273,6 +273,18 @@ export interface ResumableUploadCheckpointStore { expectedRevision: number; signal?: AbortSignal; }>): Promise>; + /** + * Q-6.1-6. Deletes the row only when it cannot be read as a checkpoint + * (corrupt, or written by a schema this build does not know); a readable row + * is left alone and reported as `CONFLICT`. An absent row is a success. + * Explicit abort uses it so such a row does not block the upload key until + * the whole partition is deleted. Optional: a store without it keeps the + * old behavior. + */ + removeUnreadable?(input: Readonly<{ + uploadKey: string; + signal?: AbortSignal; + }>): Promise>; close(): void; } diff --git a/tests/unit/resumable-upload-checkpoint.test.ts b/tests/unit/resumable-upload-checkpoint.test.ts index 88aca0bf..e96c8906 100644 --- a/tests/unit/resumable-upload-checkpoint.test.ts +++ b/tests/unit/resumable-upload-checkpoint.test.ts @@ -317,6 +317,43 @@ describe("IndexedDB resumable upload checkpoint", () => { }); }); + // Q-6.1-6. The revision-free delete exists only for rows this build cannot + // read; a readable checkpoint still needs the exact-revision remove. + it("removes only an unreadable row without a revision", async () => { + const memory = new MemoryIndexedDbFactory(); + const store = createIndexedDbResumableUploadCheckpointStore({ + scope, + factory: memory.factory, + }); + const readable = checkpoint(1); + expect( + await store.compareAndSwap({ expectedRevision: null, checkpoint: readable }), + ).toMatchObject({ ok: true }); + expect( + await store.removeUnreadable?.({ uploadKey: readable.uploadKey }), + ).toMatchObject({ + ok: false, + error: { code: "CONFLICT", recovery: "RECONCILE" }, + }); + expect(await store.read(readable.uploadKey)).toEqual({ + ok: true, + value: readable, + }); + + memory.seed("checkpoints", { ...readable, schemaVersion: 2 }); + expect(await store.read(readable.uploadKey)).toMatchObject({ + ok: false, + error: { code: "CORRUPT_DATA" }, + }); + expect( + await store.removeUnreadable?.({ uploadKey: readable.uploadKey }), + ).toEqual({ ok: true, value: undefined }); + expect(await store.read(readable.uploadKey)).toEqual({ + ok: true, + value: null, + }); + }); + it("closes the bound partition before successful lifecycle deletion", async () => { const memory = new MemoryIndexedDbFactory(); const runtime = createIndexedDbResumableUploadCheckpointRuntime({ diff --git a/tests/unit/resumable-upload-runtime.test.ts b/tests/unit/resumable-upload-runtime.test.ts index 35695abc..a6d51dbe 100644 --- a/tests/unit/resumable-upload-runtime.test.ts +++ b/tests/unit/resumable-upload-runtime.test.ts @@ -23,6 +23,7 @@ import { browserDataFailure, browserDataSuccess, } from "../../src/adapters/browser-file-storage/result.ts"; +import { createIndexedDbResumableUploadCheckpointStore } from "../../src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts"; import { createPresignedUploadPartExecutor } from "../../src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts"; import { createResumableUploadRuntime } from "../../src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts"; import { resolveResumableUploadRuntimePolicy } from "../../src/adapters/browser-transfer/resumable-upload/runtime-policy.ts"; @@ -31,6 +32,7 @@ import type { UploadCancellationListener, } from "../../src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts"; import type { UploadMutationLock } from "../../src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts"; +import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; import { activeSignal, @@ -810,6 +812,56 @@ describe("production resumable upload runtime", () => { ); }); + // Q-6.1-6. A row this build cannot read (here a newer schemaVersion left by + // a rolled-back release) used to fail both upload and abort with + // CORRUPT_DATA until the whole partition was deleted. + it("removes an unreadable checkpoint row on abort and reports ORPHANED", async () => { + const memory = new MemoryIndexedDbFactory(); + const checkpoints = createIndexedDbResumableUploadCheckpointStore({ + scope: { + authorityToken: "authority_token_01", + namespaceToken: "namespace_token_01", + partitionToken: "partition_token_01", + }, + factory: memory.factory, + }); + // Opens the database so the object stores exist before seeding. + expect(await checkpoints.read("upload_key_unreadable")).toEqual({ + ok: true, + value: null, + }); + memory.seed("checkpoints", { + schemaVersion: 2, + uploadKey: "upload_key_unreadable", + revision: 7, + state: "PAUSED", + }); + const harness = createControlHarness(); + const serverAbort = vi.spyOn(harness.control, "abort"); + const runtime = createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: executorFor(harness), + checkpoints, + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy(), + now: () => 1_000, + sleep: async () => {}, + }); + + expect( + await runtime.abort({ + uploadKey: "upload_key_unreadable", + signal: activeSignal, + }), + ).toEqual({ ok: true, value: { state: "ORPHANED" } }); + // No session id can be read from the row, so the server is not called. + expect(serverAbort).not.toHaveBeenCalled(); + expect(memory.readRaw("checkpoints", "upload_key_unreadable")).toBe( + undefined, + ); + }); + it("interrupts a same-runtime active upload before explicit abort waits for the key lock", async () => { const checkpoints = new MemoryCheckpointStore(); const harness = createControlHarness();