From 426b6b8eecd911abcbc51a90c07c5cecc4e07a79 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:22:27 +0900 Subject: [PATCH] fix(browser-transfer): map each upload() failure recovery to one caller action (01-05) ABORT_PENDING and a checkpoint CAS race returned the same failure, and some recoveries (REISSUE_CAPABILITY, RESTART for a replayed create) named actions the caller cannot take or that repeat the failure. The port now documents a five-value recovery table and upload() returns only those values. Co-Authored-By: Claude Opus 5.5 --- .../presigned-transfer-and-image-cdn.md | 12 ++ .../resumable-upload-runtime.ts | 58 ++++++- .../upload-response-validation.ts | 20 ++- .../browser-transfer/resumable-upload.ts | 19 ++ .../resumable-upload-runtime-contract.test.ts | 18 +- .../resumable-upload-runtime-recovery.test.ts | 163 ++++++++++++++++++ tests/unit/resumable-upload-runtime.test.ts | 4 +- 7 files changed, 269 insertions(+), 25 deletions(-) diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 5513f8ea..d729f8e7 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -683,6 +683,18 @@ analytics는 제품 presentation이 소유한다. | network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff | | complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) | +`ResumableUploadPort.upload()` 실패의 `recovery`는 호출자가 할 행동 하나를 +가리킨다(`resumable-upload.ts` port 주석, `resumable-upload-runtime.ts` +`toUploadAction`). 이 다섯 값 밖의 값은 `upload()`에서 나오지 않는다. + +| recovery | 호출자 행동 | +| --- | --- | +| `RESUME` | 같은 파일·key로 `upload()`를 다시 부른다. `retryable:true`면 자동 재시도해도 된다. capability 재발급이 필요한 실패도 여기로 온다 | +| `RECONCILE` | `upload()`를 다시 부른다. 서버 상태를 먼저 읽는다(예: 다른 문맥이 checkpoint를 먼저 씀) | +| `RESTART` | `abort()` 뒤 `upload()`로 새 session을 연다. abort가 남아 있음(operation `UPLOAD_ABORT`), 읽을 수 없는 checkpoint 행, 서버 part가 파일과 다름 | +| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 | +| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) | + 관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과 failure code만 기록한다. capability ID, URL, query, asset/resource/session ID, file name, digest, raw ETag, receipt와 backend message는 log/diagnostics/telemetry에 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 df7f707f..f6461efd 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -131,6 +131,15 @@ const RECOVERIES: ReadonlySet = new Set([ "RECONCILE", ]); +/** 01-05. The recoveries `ResumableUploadPort.upload()` documents. */ +const UPLOAD_ACTIONS: ReadonlySet = new Set([ + "RESUME", + "RECONCILE", + "RESTART", + "RESELECT", + "NONE", +]); + export function createResumableUploadRuntime( inputDependencies: ResumableUploadRuntimeDependencies, ): ResumableUploadRuntime { @@ -197,12 +206,14 @@ export function createResumableUploadRuntime( request.uploadKey, operationScope.signal, async () => - await executeUpload( - dependencies, - Object.freeze({ - ...request, - signal: operationScope.signal, - }), + toUploadAction( + await executeUpload( + dependencies, + Object.freeze({ + ...request, + signal: operationScope.signal, + }), + ), ), ); // Tracked until terminal settlement so dispose() can prove quiescence. @@ -375,7 +386,14 @@ async function executeUpload( request.uploadKey, request.signal, ); - if (!stored.ok) return remapResult(stored, "UPLOAD_RECONCILE"); + if (!stored.ok) { + // 01-05. A row this build cannot read is cleared only by `abort()`. + return stored.error.code === "CORRUPT_DATA" + ? browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", { + recovery: "RESTART", + }) + : remapResult(stored, "UPLOAD_RECONCILE"); + } if ( stored.value && (!sameFingerprint( @@ -389,8 +407,10 @@ async function executeUpload( }); } if (stored.value?.state === "ABORT_PENDING") { - return browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", { - recovery: "RECONCILE", + // 01-05. Only `abort()` finishes a pending abort; this must not look like + // a checkpoint write race, which `upload()` itself resolves. + return browserDataFailure("CONFLICT", "UPLOAD_ABORT", { + recovery: "RESTART", }); } @@ -1676,6 +1696,26 @@ function reportProgress( } } +/** + * 01-05. `upload()` failures carry only the recoveries the port documents as + * caller actions. Provider vocabulary the caller cannot act on itself (a + * capability to reissue, a request to retry) means "call `upload()` again"; + * anything else outside the table has no caller action. + */ +function toUploadAction( + result: BrowserDataResult, +): BrowserDataResult { + if (result.ok || UPLOAD_ACTIONS.has(result.error.recovery)) return result; + return browserDataFailure(result.error.code, result.error.operation, { + retryable: result.error.retryable, + recovery: + result.error.recovery === "REISSUE_CAPABILITY" || + result.error.recovery === "RETRY" + ? "RESUME" + : "NONE", + }); +} + function mapLockFailure( error: unknown, operation: BrowserDataOperation, diff --git a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts index 8cd48536..39cc537a 100644 --- a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts +++ b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts @@ -110,7 +110,7 @@ export function validateStatus( return browserDataFailure( "INTEGRITY_FAILED", "UPLOAD_RECONCILE", - { recovery: "RECONCILE" }, + { recovery: "RESTART" }, ); } const receipts = validateServerReceipts( @@ -153,7 +153,7 @@ export function validateStatus( return browserDataFailure( "INTEGRITY_FAILED", "UPLOAD_RECONCILE", - { recovery: "RECONCILE" }, + { recovery: "RESTART" }, ); } return browserDataSuccess( @@ -177,7 +177,7 @@ export function validateStatus( value.requestBindingSha256 !== checkpoint.requestBindingSha256 ) { return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_RECONCILE", { - recovery: "RECONCILE", + recovery: "RESTART", }); } return browserDataSuccess( @@ -221,18 +221,22 @@ export function validateSession( value.maxConcurrency > dependencies.policy.maxConcurrency || !Number.isSafeInteger(value.expiresAtEpochMs) ) { + // 01-05. A create is replayed under the same key, so neither calling + // `upload()` again nor restarting changes what the server answers. return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_SESSION", { - recovery: "RECONCILE", + recovery: "NONE", }); } const now = safeNow(dependencies, "UPLOAD_SESSION"); if (!now.ok) return now; if ( requireActiveExpiry && - (value.expiresAtEpochMs <= now.value || - value.expiresAtEpochMs - now.value > - dependencies.policy.maxSessionLifetimeMs) + value.expiresAtEpochMs - now.value > + dependencies.policy.maxSessionLifetimeMs ) { + return browserDataFailure("POLICY_REJECTED", "UPLOAD_SESSION"); + } + if (requireActiveExpiry && value.expiresAtEpochMs <= now.value) { return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_SESSION", { recovery: "RESTART", }); @@ -266,7 +270,7 @@ function validateServerReceipts( !verifyPartAgainstManifest(receipt, manifest) ) { return browserDataFailure("INTEGRITY_FAILED", operation, { - recovery: "RECONCILE", + recovery: "RESTART", }); } previousPart = receipt.partNumber; diff --git a/src/application/ports/browser-transfer/resumable-upload.ts b/src/application/ports/browser-transfer/resumable-upload.ts index 9e9bf207..9310b323 100644 --- a/src/application/ports/browser-transfer/resumable-upload.ts +++ b/src/application/ports/browser-transfer/resumable-upload.ts @@ -101,6 +101,25 @@ export type UploadAbortOutcome = Readonly<{ }>; export interface ResumableUploadPort { + /** + * 01-05. A failure's `recovery` names exactly one caller action: + * + * | recovery | caller action | + * | ----------- | ---------------------------------------------------------- | + * | `RESUME` | Call `upload()` again with the same file and key. With | + * | | `retryable: true` it may be retried automatically. | + * | `RECONCILE` | Call `upload()` again; it reads the server state first. | + * | `RESTART` | Call `abort()`, then `upload()` for a fresh session: an | + * | | abort is pending (operation `UPLOAD_ABORT`), the stored | + * | | row is unreadable, or the server's parts disagree with the | + * | | file. | + * | `RESELECT` | Select the file again, or use a new key for another file. | + * | `NONE` | No action on this request: invalid input, a limit, a | + * | | policy or permission refusal, the caller's own abort, or | + * | | a server answer that a new call would only replay. | + * + * No other recovery value is returned from `upload()`. + */ upload( request: ResumableUploadRequest, ): Promise>; diff --git a/tests/unit/resumable-upload-runtime-contract.test.ts b/tests/unit/resumable-upload-runtime-contract.test.ts index 8d20d545..917f279b 100644 --- a/tests/unit/resumable-upload-runtime-contract.test.ts +++ b/tests/unit/resumable-upload-runtime-contract.test.ts @@ -238,7 +238,8 @@ describe("resumable upload runtime server response validation", () => { error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_SESSION", - recovery: "RECONCILE", + // 01-05. The create key replays the same answer. + recovery: "NONE", }, }); }); @@ -251,7 +252,7 @@ describe("resumable upload runtime server response validation", () => { }); }); - it("restarts a session whose lifetime exceeds the policy ceiling", async () => { + it("refuses a session whose lifetime exceeds the policy ceiling", async () => { const harness = createControlHarness(); const create = harness.control.createSession.bind(harness.control); harness.control.createSession = async (input) => { @@ -265,10 +266,12 @@ describe("resumable upload runtime server response validation", () => { }; await expect(upload(dependencies(harness))).resolves.toMatchObject({ ok: false, + // 01-05. A restart gets the same session back, so there is no caller + // action; this is a server/policy mismatch. error: { - code: "EXPIRED_RESOURCE", + code: "POLICY_REJECTED", operation: "UPLOAD_SESSION", - recovery: "RESTART", + recovery: "NONE", }, }); }); @@ -285,10 +288,11 @@ describe("resumable upload runtime server response validation", () => { }); await expect(upload(dependencies(harness))).resolves.toMatchObject({ ok: false, + // 01-05. The caller's action for a capability refusal is upload(). error: { code: "CORRUPT_DATA", operation: "UPLOAD_PART", - recovery: "REISSUE_CAPABILITY", + recovery: "RESUME", }, }); }); @@ -307,7 +311,7 @@ describe("resumable upload runtime server response validation", () => { error: { code: "POLICY_REJECTED", operation: "UPLOAD_PART", - recovery: "REISSUE_CAPABILITY", + recovery: "RESUME", }, }); }); @@ -326,7 +330,7 @@ describe("resumable upload runtime server response validation", () => { error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_RECONCILE", - recovery: "RECONCILE", + recovery: "RESTART", }, }); }); diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index d27e028a..66802b07 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -702,3 +702,166 @@ describe("resumable upload part time limit (01-03)", () => { } }); }); + +describe("upload() failure recovery maps to one caller action (01-05)", () => { + /** The port's recovery → action table (`ResumableUploadPort.upload`). */ + const UPLOAD_ACTIONS = new Set([ + "RESUME", + "RECONCILE", + "RESTART", + "RESELECT", + "NONE", + ]); + + function runtimeFor( + harness: ReturnType, + overrides: Partial< + Parameters>[0] + > = {}, + ) { + return createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: executorFor(harness), + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 0 }), + now: () => 1_000, + sleep: async () => {}, + ...overrides, + }); + } + + const scenarios = { + "an abort is still pending": async () => { + const harness = createControlHarness(); + harness.control.complete = async () => + browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", { + retryable: true, + recovery: "RESUME", + }); + harness.control.abort = async () => + browserDataFailure("UNAVAILABLE", "UPLOAD_ABORT", { + retryable: true, + recovery: "RESUME", + }); + const runtime = runtimeFor(harness); + const key = "upload_key_abort_pending"; + await runtime.upload(request(key)); + await runtime.abort({ uploadKey: key, signal: activeSignal }); + return await runtime.upload(request(key)); + }, + "another context wrote the checkpoint first": async () => { + const checkpoints = new MemoryCheckpointStore(); + checkpoints.compareAndSwap = async () => + browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", { + recovery: "RECONCILE", + }); + return await runtimeFor(createControlHarness(), { checkpoints }).upload( + request("upload_key_cas_conflict"), + ); + }, + "the server status disagrees with the file": async () => + await runtimeFor( + createControlHarness({ + statusParts: (_session, accepted) => + [...accepted.values()].map((part) => ({ + ...part, + checksumSha256: "e".repeat(64), + })), + }), + ).upload(request("upload_key_status_mismatch")), + "the checkpoint row is unreadable": async () => { + const checkpoints = new MemoryCheckpointStore(); + checkpoints.read = async () => + browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", { + recovery: "RECONCILE", + }); + return await runtimeFor(createControlHarness(), { checkpoints }).upload( + request("upload_key_unreadable"), + ); + }, + "the server session outlives the policy": async () => { + const harness = createControlHarness(); + const create = harness.control.createSession.bind(harness.control); + harness.control.createSession = async (input) => { + const created = await create(input); + return created.ok + ? browserDataSuccess({ + ...created.value, + expiresAtEpochMs: 1_000 + 20_000, + }) + : created; + }; + return await runtimeFor(harness).upload(request("upload_key_long_session")); + }, + "every PUT refuses the capability": async () => + await runtimeFor(createControlHarness(), { + partExecutor: { uploadPart: async () => putForbidden() }, + }).upload(request("upload_key_refused_put")), + "the key belongs to another file": async () => { + const checkpoints = new MemoryCheckpointStore(); + const harness = createControlHarness(); + harness.control.complete = async () => + browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", { + retryable: true, + recovery: "RESUME", + }); + const runtime = runtimeFor(harness, { checkpoints }); + const key = "upload_key_other_file"; + await runtime.upload(request(key)); + return await runtime.upload({ + ...request(key), + source: rangeSource(new Uint8Array([9, 9, 9, 9])), + }); + }, + } as const; + + it.each([ + ["an abort is still pending", "CONFLICT", "UPLOAD_ABORT", "RESTART"], + [ + "another context wrote the checkpoint first", + "CONFLICT", + "UPLOAD_RECONCILE", + "RECONCILE", + ], + [ + "the server status disagrees with the file", + "INTEGRITY_FAILED", + "UPLOAD_RECONCILE", + "RESTART", + ], + [ + "the checkpoint row is unreadable", + "CORRUPT_DATA", + "UPLOAD_RECONCILE", + "RESTART", + ], + [ + "the server session outlives the policy", + "POLICY_REJECTED", + "UPLOAD_SESSION", + "NONE", + ], + [ + "every PUT refuses the capability", + "PERMISSION_DENIED", + "UPLOAD_PART", + "RESUME", + ], + [ + "the key belongs to another file", + "STALE_RESULT", + "UPLOAD_RECONCILE", + "RESELECT", + ], + ] as const)("%s → %s/%s/%s", async (scenario, code, operation, recovery) => { + const result = await scenarios[scenario](); + + expect(result).toMatchObject({ + ok: false, + error: { code, operation, recovery }, + }); + if (!result.ok) expect(UPLOAD_ACTIONS.has(result.error.recovery)).toBe(true); + }); +}); diff --git a/tests/unit/resumable-upload-runtime.test.ts b/tests/unit/resumable-upload-runtime.test.ts index 015c9431..5ff8cbca 100644 --- a/tests/unit/resumable-upload-runtime.test.ts +++ b/tests/unit/resumable-upload-runtime.test.ts @@ -371,12 +371,14 @@ describe("production resumable upload runtime", () => { source: rangeSource(new Uint8Array([1, 2, 3, 4])), signal: activeSignal, }); + // 01-05. Calling upload() again reads the same server parts, so the way + // out is abort() and a fresh session. expect(result).toMatchObject({ ok: false, error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_RECONCILE", - recovery: "RECONCILE", + recovery: "RESTART", }, }); expect(partExecutor.uploadPart).not.toHaveBeenCalled();