diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index d7ff38e6..eb2982ff 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -743,6 +743,13 @@ analytics는 제품 presentation이 소유한다. 재인증은 앱 세션 계층 몫이다. PUT 403은 서명 만료가 보통 원인이라 새 capability로 풀리므로 `RESUME`이다. +서버의 `Retry-After`가 runtime 정책의 `maxRetryAfterMs`보다 길면 runtime은 +기다리지 않고 멈춘다. 이때 앱에 주는 실패는 `RESUME`, `retryable:false`다 +(`resumable-upload-runtime.ts` `stripProviderFailure`, 2026-11-03 01-02). control +plane 전송이 상한 밖 429를 끝내는 규칙과 같다. 그래서 part 발급·PUT과 control +plane, 그리고 전송과 정책 중 어느 쪽 `maxRetryAfterMs`가 크든 같은 답이 나온다. +앱은 사람이 누르는 재시도로 넘긴다. + 관측성에는 operation, safe outcome, byte/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 011ca6aa..ac6cbb33 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -572,7 +572,7 @@ async function reconcileActiveCheckpoint( Object.freeze({ kind: "TERMINAL" as const }), ); } - return stripProviderFailure(statusResult); + return stripProviderFailure(statusResult, dependencies.policy); } const status = validateStatus( statusResult.value, @@ -674,7 +674,7 @@ async function createUploadSession( signal: attemptSignal, }), ); - if (!created.ok) return stripProviderFailure(created); + if (!created.ok) return stripProviderFailure(created, dependencies.policy); const session = validateSession( created.value, requestBindingSha256, @@ -995,7 +995,7 @@ async function uploadPartWithRetry( } lastFailure = issued.error; if (!canRetry(issued.error, attempt, dependencies.policy)) { - return stripProviderFailure(issued); + return stripProviderFailure(issued, dependencies.policy); } continue; } @@ -1075,12 +1075,13 @@ async function uploadPartWithRetry( dependencies.policy, ) ) { - return stripProviderFailure(uploaded); + return stripProviderFailure(uploaded, dependencies.policy); } } return lastFailure ? stripProviderFailure( Object.freeze({ ok: false, error: lastFailure }), + dependencies.policy, ) : browserDataFailure("UNAVAILABLE", "UPLOAD_PART", { recovery: "RESUME", @@ -1130,7 +1131,9 @@ async function completeUpload( signal: attemptSignal, }), ); - if (!completed.ok) return stripProviderFailure(completed); + if (!completed.ok) { + return stripProviderFailure(completed, dependencies.policy); + } const value = completed.value; if ( !exactRecord(value, [ @@ -1244,7 +1247,7 @@ async function executeAbort( ) : remapResult(removed, "UPLOAD_ABORT"); } - return stripProviderFailure(aborted); + return stripProviderFailure(aborted, dependencies.policy); } if ( !exactRecord(aborted.value, ["state"]) || @@ -1308,7 +1311,10 @@ async function readCompletedResourceId( return status.error.code === "NOT_FOUND" || status.error.code === "EXPIRED_RESOURCE" ? browserDataSuccess(null) - : remapResult(stripProviderFailure(status), "UPLOAD_ABORT"); + : remapResult( + stripProviderFailure(status, dependencies.policy), + "UPLOAD_ABORT", + ); } const value = status.value; return browserDataSuccess( @@ -1673,12 +1679,26 @@ function providerFailureValue( return Object.freeze({ code, operation, retryable, recovery }); } +/** + * The one place a provider failure becomes the app's failure. The server's + * wait (`retryAfterMs`) does not cross the port. + * + * 2026-11-03 01-02. A wait longer than `maxRetryAfterMs` is one the runtime + * refused to sit out, so the app is not told to retry at once either + * (`retryable: false`). The control-plane transport already ends a 429 past + * its own ceiling this way; doing it here makes both stages, and either + * factory's ceiling being the larger, give the same answer. + */ function stripProviderFailure( result: UploadProviderResult, + policy: ResumableUploadRuntimePolicy, ): BrowserDataResult { if (result.ok) return browserDataSuccess(result.value); + const waitRefused = + result.error.retryAfterMs !== undefined && + !(result.error.retryAfterMs <= policy.maxRetryAfterMs); return browserDataFailure(result.error.code, result.error.operation, { - retryable: result.error.retryable, + retryable: result.error.retryable && !waitRefused, recovery: result.error.recovery, }); } diff --git a/src/application/ports/browser-transfer/resumable-upload.ts b/src/application/ports/browser-transfer/resumable-upload.ts index d18811e3..46851e50 100644 --- a/src/application/ports/browser-transfer/resumable-upload.ts +++ b/src/application/ports/browser-transfer/resumable-upload.ts @@ -120,7 +120,10 @@ export interface ResumableUploadPort { * | | only replay. | * * No other recovery value is returned from `upload()`. `NONE` and - * `RESELECT` always come with `retryable: false` (0929/01-01). + * `RESELECT` always come with `retryable: false` (0929/01-01). A server + * `Retry-After` longer than the runtime's `maxRetryAfterMs` comes back as + * `RESUME` with `retryable: false`: the runtime did not wait that long, so + * the caller does not resend at once either (2026-11-03 01-02). */ upload( request: ResumableUploadRequest, diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index b46b6e57..29a8a843 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -11,6 +11,8 @@ import { browserDataSuccess, } from "../../src/adapters/browser-file-storage/result.ts"; import { sha256Hex } from "../../src/adapters/browser-transfer/presigned/incremental-sha256.ts"; +import { createResumableUploadFetchJsonTransport } from "../../src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts"; +import { createResumableUploadHttpControlPlane } from "../../src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.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"; @@ -369,9 +371,16 @@ describe("part-stage Retry-After (2026-11-01 01-01)", () => { request("upload_key_part_retry_after_over"), ); + // 2026-11-03 01-02. The server asked for a longer wait than the runtime + // gives, so the app is not invited to call again at once either. expect(result).toMatchObject({ ok: false, - error: { code: "UNAVAILABLE", operation: "UPLOAD_PART" }, + error: { + code: "UNAVAILABLE", + operation: "UPLOAD_PART", + retryable: false, + recovery: "RESUME", + }, }); expect(real.sleeps).toEqual([]); expect(real.issuance()).toBe(1); @@ -379,6 +388,79 @@ describe("part-stage Retry-After (2026-11-01 01-01)", () => { ); }); +/** + * 2026-11-03 01-02. A control-plane 429 past the ceiling ends the same way + * as a part-stage one, whichever of the two factories' `maxRetryAfterMs` is + * larger: the transport's (it decides `retryable`) or the runtime policy's + * (it decides whether to wait). + */ +describe("control-plane Retry-After past the ceiling (2026-11-03 01-02)", () => { + const API = "https://api.example"; + const endpoints = Object.freeze({ + CREATE_SESSION: `${API}/uploads/create`, + GET_STATUS: `${API}/uploads/status`, + COMPLETE: `${API}/uploads/complete`, + ABORT: `${API}/uploads/abort`, + }); + + it.each([ + { transportMaxRetryAfterMs: 30_000 }, + { transportMaxRetryAfterMs: 60_000 }, + ])( + "createSession 429 Retry-After: 45 with transport ceiling $transportMaxRetryAfterMs and policy ceiling 30000", + async ({ transportMaxRetryAfterMs }) => { + const fetcher = vi.fn(async (input: RequestInfo | URL) => + responseWithUrl( + new Response(null, { status: 429, headers: { "Retry-After": "45" } }), + String(input), + ), + ); + const sleeps: number[] = []; + const runtime = createResumableUploadRuntime({ + controlPlane: createResumableUploadHttpControlPlane({ + transport: createResumableUploadFetchJsonTransport({ + endpoints, + allowedOrigins: [API], + credentials: "same-origin", + fetcher: fetcher as unknown as typeof fetch, + timeoutMs: 100, + maxRequestBytes: 4_096, + maxResponseBytes: 4_096, + maxRetryAfterMs: transportMaxRetryAfterMs, + nowEpochMs: () => NOW, + }), + partCapabilities: { issueUploadPart: vi.fn() }, + }), + partExecutor: { uploadPart: vi.fn() }, + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 3, maxRetryAfterMs: 30_000 }), + now: () => NOW, + sleep: async (milliseconds: number) => { + sleeps.push(milliseconds); + }, + }); + + const result = await runtime.upload( + request("upload_key_control_retry_after_over"), + ); + + expect(result).toEqual({ + ok: false, + error: { + code: "UNAVAILABLE", + operation: "UPLOAD_SESSION", + retryable: false, + recovery: "RESUME", + }, + }); + expect(fetcher).toHaveBeenCalledTimes(1); + expect(sleeps).toEqual([]); + }, + ); +}); + describe("resumable upload idempotency keys (01-04)", () => { const unavailable = ( operation: