문제: part 단계(BFF capability 발급, object store PUT)의 상태표
statusFailure는 상태 코드만 받아 429의 Retry-After를 버린다. 서버가
`429 Retry-After: 5`로 답해도 runtime은 지수 backoff(기본 250·500·
1000ms)로 다시 보내고, 1.75초 안에 요청 8개를 쓴 뒤 retryable 실패를
돌려준다. 설계 문서 두 곳(presigned-transfer-and-image-cdn.md,
server-file-capability-infrastructure.md)은 part 단계도 bounded
Retry-After를 따른다고 적는다. 헤더를 읽는 곳은 control plane
transport뿐이었다.
고른 방법: statusFailure가 Response와 현재 시각을 받아 429·503이면
kernel parseRetryAfterDelay로 retryAfterMs를 채운다. 상한
maxRetryAfterMs는 runtime의 canRetry·waitForRetry가 이미 적용하므로
presigned 계층은 값을 그대로 넘긴다. 상한을 넘으면 재시도하지 않는다
(control plane과 같은 규칙). PresignedUploadPartCapabilityProvider.
issueUploadPart와 PresignedUploadPartPort.put의 반환 타입을
UploadProviderResult로 넓혔다. 기존 구현은 그대로 대입되므로
추가형이다. HTTP control plane 어댑터의 발급 브리지가 실패를 다시
만들면서 retryAfterMs를 버리던 것도 넘기게 했다.
버린 대안:
- 문서를 "part 단계는 Retry-After를 읽지 않는다"로 고친다. 재시도
증폭이 그대로 남는다.
- BFF 응답 본문에 대기 시간을 넣는 별도 계약. 표준 헤더를 두고 서버와
클라이언트를 함께 바꿔야 한다.
- download 경로만 빼고 읽는다. 하나로 합친 상태표(Q-6.1-9)를 다시
둘로 가르게 된다. download 소비자(browser-files 전달 어댑터)는
실패를 다시 만들어 이 값을 읽지 않는다.
위험·한계:
- 다른 origin의 object store가 Access-Control-Expose-Headers에
Retry-After를 넣지 않으면 헤더가 없는 것으로 읽혀 지금처럼 backoff만
쓴다. statusFailure 주석에 적었다.
- part 단계에서 Retry-After가 없거나 형식이 틀린 429는 지금처럼
retryable backoff다. control plane은 이 경우 재시도하지 않는다. 이
차이는 이번에 바꾸지 않았다.
- issueDownload·open 실패에도 retryAfterMs가 실린다. 이 두 포트의
타입(BrowserDataResult)에는 드러나지 않는다.
- file-transfer 레시피 번들이 55,623 → 55,725 gzip bytes가 되어 예산
55,700을 넘었다. 측정값 위 약 100바이트로 반올림하는 기존 규칙
(4b0e44a9)대로 55,800으로 올렸다.
- 포트 반환 타입이 넓어졌으므로 CHANGELOG [계약] 한 줄이 필요하다.
이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지 않았다.
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 4건 실패.
발급·PUT이 `429 Retry-After: 5`일 때 "expected 0 to be greater than
or equal to 5000"(첫 sleep 0ms). maxRetryAfterMs 1000을 넘을 때
재시도해서 ok:true. resumable-upload-http-control-plane.test.ts 새
1건 실패: 브리지 결과에 retryAfterMs 5000이 없다.
- GREEN: 두 파일 33건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·
upload-cancellation·json-schema 단위 21파일 322건 통과. tsc app·
test·node·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
(exec 전용 shim, pnpm 미사용) 통과, check-adapter-inventory 통과,
check-optional-recipes(source) PASS file-transfer 55725/55800.
Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md