From 648fe4e9f7a36dae03b8cba4b2425592ab6f93c4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:03:50 +0900 Subject: [PATCH] fix(browser-transfer): reissue the part capability after a PUT 401/403 or expiry (01-01) A single object-store refusal ended the whole upload as PERMISSION_DENIED with retryable:false. The next attempt already issues a fresh capability, so REISSUE_CAPABILITY PUT failures now retry within maxRetries; BFF issuance refusals still stop at once. Co-Authored-By: Claude Opus 5.5 --- .../presigned-transfer-and-image-cdn.md | 3 + .../resumable-upload-runtime.ts | 14 +- .../resumable-upload-runtime-recovery.test.ts | 241 ++++++++++++++++++ 3 files changed, 257 insertions(+), 1 deletion(-) create mode 100644 tests/unit/resumable-upload-runtime-recovery.test.ts diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 2a07e968..461f53da 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -261,6 +261,9 @@ session state 검사를 대체하지 않는다. - 429/모든 `5xx`/network retry는 composition의 bounded attempt, bounded `Retry-After`와 abortable backoff 안에서만 수행한다. - 만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다. + object store PUT의 401/403/409/410과 실행기의 만료 판정(`REISSUE_CAPABILITY`)은 + `maxRetries` 안에서 다음 시도가 새 capability로 다시 보낸다. BFF 발급 단계의 + 401/403은 재시도하지 않는다(`resumable-upload-runtime.ts` `uploadPartWithRetry`). - upload response의 opaque receipt/ETag를 whole-file digest로 해석하지 않는다. - PUT capability는 성공 status, receipt header와 `expectedResponseByteLength`를 묶는다. runtime은 exact `Content-Length`를 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 1023cf5e..7f60ab0b 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -1015,7 +1015,19 @@ async function uploadPartWithRetry( ); } lastFailure = uploaded.error; - if (!canRetry(uploaded.error, attempt, dependencies.policy)) { + // 01-01. A PUT refused with REISSUE_CAPABILITY (401/403, gone, or the + // executor's own expiry check) is what the next attempt's fresh capability + // recovers. A refused issuance above still stops at once. + const reissuable = + uploaded.error.retryable || + uploaded.error.recovery === "REISSUE_CAPABILITY"; + if ( + !canRetry( + { ...uploaded.error, retryable: reissuable }, + attempt, + dependencies.policy, + ) + ) { return stripProviderFailure(uploaded); } } diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts new file mode 100644 index 00000000..80546ff3 --- /dev/null +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -0,0 +1,241 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { PresignedUploadPartCapability } from "../../src/application/ports/browser-transfer/presigned-transfer.ts"; +import type { + ResumableUploadControlPlane, + UploadPartExecutor, +} from "../../src/application/ports/browser-transfer/resumable-upload.ts"; +import { + browserDataFailure, + browserDataSuccess, +} from "../../src/adapters/browser-file-storage/result.ts"; +import { sha256Hex } from "../../src/adapters/browser-transfer/presigned/incremental-sha256.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 { + CONTROL_ENDPOINT, + NOW, + POLICY_HEADER, + createHarness, + jsonResponse, + responseWithUrl, + uploadCapabilityPayload, +} from "./presigned-transfer-fixture.ts"; +import { + activeSignal, + createControlHarness, + MemoryCheckpointStore, + noContentionLock, + rangeSource, + runtimePolicy, + type TestCapability, +} from "./resumable-upload-runtime-fixture.ts"; + +const request = (uploadKey: string) => + ({ + uploadKey, + purpose: "attachment", + mediaType: "application/octet-stream", + source: rangeSource(new Uint8Array([1, 2, 3, 4])), + signal: activeSignal, + }) as const; + +/** What `statusFailure(403)` hands the runtime through the part executor. */ +const putForbidden = () => + browserDataFailure("PERMISSION_DENIED", "PRESIGNED_TRANSFER", { + retryable: false, + recovery: "REISSUE_CAPABILITY", + }); + +describe("resumable upload capability reissue (01-01)", () => { + it("reissues the capability after an object-store PUT 403 and completes", async () => { + const harness = createControlHarness(); + let attempts = 0; + const partExecutor: UploadPartExecutor = { + async uploadPart(input) { + attempts += 1; + if (attempts === 1) return putForbidden(); + const receipt = Object.freeze({ + ...input.part, + receiptToken: "etag-after-reissue", + }); + harness.accepted.set(input.part.partNumber, receipt); + return browserDataSuccess(receipt); + }, + }; + const runtime = createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor, + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 3 }), + now: () => 1_000, + sleep: async () => {}, + }); + + const result = await runtime.upload(request("upload_key_put_403")); + + expect(result).toMatchObject({ ok: true, value: { state: "QUARANTINED" } }); + expect(attempts).toBe(2); + expect(harness.issued).toHaveBeenCalledTimes(2); + }); + + it("stops after maxRetries when every PUT keeps refusing the capability", async () => { + const harness = createControlHarness(); + const partExecutor = { uploadPart: vi.fn(async () => putForbidden()) }; + const runtime = createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: + partExecutor as unknown as UploadPartExecutor, + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 2 }), + now: () => 1_000, + sleep: async () => {}, + }); + + const result = await runtime.upload(request("upload_key_put_403_always")); + + expect(result).toMatchObject({ + ok: false, + error: { code: "PERMISSION_DENIED", operation: "UPLOAD_PART" }, + }); + expect(partExecutor.uploadPart).toHaveBeenCalledTimes(3); + expect(harness.issued).toHaveBeenCalledTimes(3); + }); + + it("does not retry a capability issuance the BFF itself refuses with 403", async () => { + const harness = createControlHarness({ + issueCapability: () => + browserDataFailure("PERMISSION_DENIED", "PRESIGNED_TRANSFER", { + retryable: false, + recovery: "REISSUE_CAPABILITY", + }), + }); + const partExecutor = { uploadPart: vi.fn() }; + const runtime = createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: + partExecutor as unknown as UploadPartExecutor, + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 3 }), + now: () => 1_000, + sleep: async () => {}, + }); + + const result = await runtime.upload(request("upload_key_issue_403")); + + expect(result).toMatchObject({ + ok: false, + error: { code: "PERMISSION_DENIED", retryable: false }, + }); + expect(harness.issued).toHaveBeenCalledTimes(1); + expect(partExecutor.uploadPart).not.toHaveBeenCalled(); + }); + + it("recovers a real presigned PUT 403 through a freshly issued capability", async () => { + const bytes = new Uint8Array([1, 2, 3, 4]); + const checksum = sha256Hex(bytes); + let issuance = 0; + let puts = 0; + const fetcher = vi.fn( + async (input: RequestInfo | URL, init?: RequestInit) => { + if (String(input) === CONTROL_ENDPOINT) { + issuance += 1; + const body = JSON.parse(String(init?.body)) as Readonly<{ + binding: Readonly>; + }>; + return jsonResponse( + uploadCapabilityPayload( + { bytes, checksum }, + { + capabilityReceipt: `capability-upload-${issuance}`, + binding: body.binding, + maxBytes: bytes.byteLength, + expiresAtEpochMs: NOW + 4_000, + }, + ), + ); + } + puts += 1; + const href = String(input); + return responseWithUrl( + puts === 1 + ? new Response(null, { status: 403 }) + : new Response(null, { + status: 200, + headers: { + [POLICY_HEADER]: "v1", + "Content-Length": "0", + ETag: "\"part-etag-reissued\"", + }, + }), + href, + ); + }, + ) as unknown as typeof fetch; + const { provider, executor } = createHarness({ fetcher }); + const harness = createControlHarness({ now: NOW }); + const control = harness.control as unknown as ResumableUploadControlPlane< + PresignedUploadPartCapability + >; + control.issuePartCapability = async (input) => { + const issued = await provider.issueUploadPart({ + sessionId: input.sessionId, + requestBindingSha256: input.requestBindingSha256, + uploadBindingSha256: input.uploadBindingSha256, + partNumber: input.part.partNumber, + offset: input.part.offset, + byteLength: input.part.byteLength, + checksumSha256: input.part.checksumSha256, + mediaType: input.mediaType, + idempotencyKey: input.idempotencyKey, + signal: input.signal, + }); + return issued.ok + ? browserDataSuccess({ + capability: issued.value, + uploadBindingSha256: input.uploadBindingSha256, + expiresAtEpochMs: issued.value.expiresAtEpochMs, + }) + : issued; + }; + const realPart = createPresignedUploadPartExecutor( + executor.uploadParts, + () => NOW, + ); + const runtime = createResumableUploadRuntime({ + controlPlane: control, + partExecutor: { + async uploadPart(input) { + const uploaded = await realPart.uploadPart(input); + // The fake server lists what the object store accepted. + if (uploaded.ok) { + harness.accepted.set(uploaded.value.partNumber, uploaded.value); + } + return uploaded; + }, + }, + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 3 }), + now: () => NOW, + sleep: async () => {}, + }); + + const result = await runtime.upload(request("upload_key_real_put_403")); + + expect(result).toMatchObject({ ok: true, value: { state: "QUARANTINED" } }); + expect(harness.completedParts).toEqual([ + [expect.objectContaining({ receiptToken: "part-etag-reissued" })], + ]); + expect(issuance).toBe(2); + expect(puts).toBe(2); + }); +});