fix(browser-transfer): 상한보다 긴 Retry-After는 앱에도 retryable:false로 준다

문제: part 단계(BFF 발급, object store PUT)가 상한(maxRetryAfterMs, 기본
30초)보다 긴 Retry-After로 429·503을 받으면 runtime은 기다리지 않고
멈춘다. 그런데 앱에 주는 실패는 retryable:true다. 포트 표대로면 "자동
재시도해도 된다"는 뜻이라, 서버가 45초 기다리라고 한 요청을 앱이 바로
다시 보낸다. 같은 429에 control plane 전송은 retryable:false를 준다.
control plane도 전송 상한이 정책 상한보다 크면 retryable:true가 된다.

고친 방법: provider 실패를 앱 실패로 바꾸는 한 곳(stripProviderFailure)이
정책 상한을 받아, 지우는 retryAfterMs가 상한을 넘었으면 retryable을
false로 만든다. control plane 전송이 이미 쓰는 규칙이다. 한 곳에서 하므로
두 단계와 두 factory 상한 조합이 모두 같은 답을 낸다. 포트 주석과 설계
문서(presigned-transfer-and-image-cdn.md 7절)에 같은 규칙을 적었다.

버린 대안: 현상 유지 + 포트 주의 한 줄은 앱이 기다릴 값을 모르므로 지킬
수 없다. 앱 실패에 retryAfterMs를 싣는 안은 공유 타입 BrowserDataFailure를
바꿔 다른 포트까지 퍼진다. 상한 밖 값도 기다리는 안은 한 호출이 끝없이
늘어지지 않는다는 상한의 목적을 깬다(리뷰 5절 D2).

위험·한계: upload()·abort()의 실패 값이 바뀐다. 상한 밖 Retry-After는
RESUME에 retryable:false가 되어, 자동 재시도하던 다운스트림은 사람이
누르는 재시도로 넘어간다. 상한 안 대기, PUT 403 재발급, 발급 401/403
NONE은 바뀌지 않는다(기존 테스트 그대로 통과). 헤더 없는 part 단계 429가
backoff로 재시도하는 차이는 이 변경 범위 밖이다.

검증:
- 고치기 전: 새 단언 5건 실패(part 단계 4건, 전송 상한 60초 조합 1건)
- 고친 뒤: 영역 단위 테스트 15파일 274건 통과
- check:types, eslint(바꾼 파일) 통과

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-02
This commit is contained in:
DongHyeonka
2026-11-04 20:21:39 +09:00
parent 3af2c8ea2b
commit c695898aee
4 changed files with 122 additions and 10 deletions
@@ -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에
@@ -572,7 +572,7 @@ async function reconcileActiveCheckpoint<Capability>(
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<Capability>(
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<Capability>(
}
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<Capability>(
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<Capability>(
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<Capability>(
)
: remapResult(removed, "UPLOAD_ABORT");
}
return stripProviderFailure(aborted);
return stripProviderFailure(aborted, dependencies.policy);
}
if (
!exactRecord(aborted.value, ["state"]) ||
@@ -1308,7 +1311,10 @@ async function readCompletedResourceId<Capability>(
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<Value>(
result: UploadProviderResult<Value>,
policy: ResumableUploadRuntimePolicy,
): BrowserDataResult<Value> {
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,
});
}
@@ -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,
@@ -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: