fix(browser-transfer): part 발급 401/403을 NONE으로 낸다 (0929/01-01)

문제: part 발급(BFF)이 401/403으로 거절하면 upload()가
{PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다.
세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다.
그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(9142390)은 이 경로를
남겼다. object store PUT 403과 code·단계·recovery가 모두 같아서
toUploadAction 한 곳에서 가를 수 없었다.

고른 방법: 실패의 출처를 아는 곳에서 표시한다. runtime의
uploadPartWithRetry 발급 분기만 그 실패가 BFF 발급에서 왔다는 것을
안다. 그 분기에서 PERMISSION_DENIED를 {retryable:false, NONE}으로
만든다. 표시는 별도 필드 대신 기존 recovery 값(NONE)이다. 번역
(toUploadAction)은 NONE을 그대로 두고 retryable:false를 강제한다. 공개
타입은 바뀌지 않는다. 발급 분기는 모든 control plane 구현이 지나는
곳이라 http-control-plane-adapter 말고 다른 구현에도 같은 답이 나온다.
PUT 403은 그대로 RESUME이다. 서명 만료가 보통 원인이고 다음 시도가 새
capability를 받는다(지난 수정의 보존 조건).

버린 대안:
- 백엔드가 code를 나눈다: 두 repo 계약이 바뀌고 다른 백엔드에도 기대야
  한다.
- code만 보고 번역에서 추측한다: 두 출처의 code가 같아 불가능하다.
  PERMISSION_DENIED를 모두 NONE으로 하면 PUT 403 테스트 2건이 깨진다.
- 실패의 stage(operation) union에 발급 값을 더한다: 공개 타입 변경이라
  [계약]이다. 같은 일을 기존 값으로 할 수 있다.
- 내부 표시 필드나 WeakSet: 발급 분기와 번역 사이에서 실패는 공개
  BrowserDataFailure로 오간다. 필드를 실으려면 타입 단언이 필요하고,
  WeakSet은 객체 동일성에 기대는 숨은 결합이다. 중간에 실패를 다시
  만들면 말없이 표시가 사라진다.
- control plane adapter에서 바꾼다: 다른 control plane 구현은 여전히
  RESUME을 낸다.

위험·한계:
- BFF 발급 401/403의 recovery가 RESUME → NONE으로 바뀐다. 다운스트림
  화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다.
- control plane이 발급 거절을 retryable:true로 줘도 이제 재시도하지
  않는다. 재인증 전에는 결과가 같기 때문이다.
- 재인증 자체는 앱 세션 계층 몫이라 다루지 않았다.
- 실제 BFF·object store가 아니라 fetch 가짜 서버로 확인했다.
- file-transfer 레시피 번들 56,031 → 56,053 gzip B(예산 56,100).

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 3건 중
  BFF 발급 401·403 2건 실패(recovery 기대 NONE, 실제 RESUME). PUT 403
  1건은 수정 전에도 RESUME으로 통과(보존 조건 고정).
- GREEN: 같은 파일 37건 통과. 세 경로 모두 retryable:false를 단언한다.
- 변이: 번역에 "PERMISSION_DENIED → NONE"을 넣으면 PUT 403 2건(새
  테스트, 기존 01-05 표 테스트)이 실패한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
  image-cdn 단위 20파일 329건 통과. tsc app·test·recipes 통과. 바꾼
  파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
  check-optional-recipes(source) file-transfer 56053/56100.
- 미실행: check:architecture(pnpm 필요).

Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
This commit is contained in:
DongHyeonka
2026-11-03 00:36:28 +09:00
parent 7a70cea631
commit c5f87aaef5
3 changed files with 47 additions and 2 deletions
@@ -737,8 +737,11 @@ analytics는 제품 presentation이 소유한다.
번역은 recovery 값만이 아니라 code도 본다(0929/01-01). `POLICY_REJECTED`는
`NONE`, file store의 `NOT_READABLE`/`REOPEN`은 `RESELECT`, `UPLOAD_PART`의
`NOT_FOUND`는 `RECONCILE`이다. 표 밖 값 중 `retryable:true`인 일시 오류는
`RESUME`이다. part 발급(BFF)의 401/403은 아직 `RESUME`으로 나온다. object store
PUT 403(재발급으로 풀리는 경우)과 같은 code·단계라 번역 한 곳에서 가를 수 없다.
`RESUME`이다. part 발급(BFF)의 401/403과 object store PUT 403은 code·단계가
같다. 그래서 출처를 아는 runtime의 발급 분기가 발급 거절을 `NONE`(retryable
`false`)으로 만든다. 세션 만료·권한 회수라 재인증 전에는 다시 불러도 같은 답이고,
재인증은 앱 세션 계층 몫이다. PUT 403은 서명 만료가 보통 원인이라 새 capability로
풀리므로 `RESUME`이다.
관측성에는 operation, safe outcome, byte/candidate bucket, retry bucket과
failure code만 기록한다. capability ID, URL, query, asset/resource/session ID,
@@ -986,6 +986,13 @@ async function uploadPartWithRetry<Capability>(
}),
);
if (!issued.ok) {
// 0929/01-01. Only this branch knows a 401/403 came from the BFF's
// issuance: the session expired or the permission was revoked, and no
// new call succeeds before the app's session layer re-authenticates. A
// PUT 403 below has the same code and stays reissuable (RESUME).
if (issued.error.code === "PERMISSION_DENIED") {
return browserDataFailure("PERMISSION_DENIED", "UPLOAD_PART");
}
lastFailure = issued.error;
if (!canRetry(issued.error, attempt, dependencies.policy)) {
return stripProviderFailure(issued);
@@ -292,6 +292,41 @@ describe("resumable upload capability reissue (01-01)", () => {
});
});
/**
* 0929/01-01 ④. Both servers' 401/403 reach the runtime as the same
* PERMISSION_DENIED/UPLOAD_PART/REISSUE_CAPABILITY. A refused issuance means
* the session expired or the permission was revoked: no new call succeeds
* before re-authentication. A refused PUT means the signature expired: the
* runtime's next capability recovers it.
*/
describe("issuance refusal versus PUT refusal (0929/01-01)", () => {
it.each([
["the BFF refuses issuance with 401", "NONE", [401], [], 0],
["the BFF refuses issuance with 403", "NONE", [403], [], 0],
["the object store refuses every PUT with 403", "RESUME", [], [403, 403, 403, 403], 4],
] as const)(
"%s → %s",
async (_scenario, recovery, issueStatuses, putStatuses, puts) => {
const real = presignedRuntime(putStatuses, undefined, { issueStatuses });
const result = await real.runtime.upload(
request("upload_key_permission_denied"),
);
expect(result).toMatchObject({
ok: false,
error: {
code: "PERMISSION_DENIED",
operation: "UPLOAD_PART",
retryable: false,
recovery,
},
});
expect(real.puts()).toBe(puts);
},
);
});
describe("part-stage Retry-After (2026-11-01 01-01)", () => {
const stages = [
{ stage: "BFF issuance", issueStatuses: [429], putStatuses: [] },