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:
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user