From c5f87aaef5b96242c4be34b932d745bf94808a14 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 00:36:05 +0900 Subject: [PATCH] =?UTF-8?q?fix(browser-transfer):=20part=20=EB=B0=9C?= =?UTF-8?q?=EA=B8=89=20401/403=EC=9D=84=20NONE=EC=9C=BC=EB=A1=9C=20?= =?UTF-8?q?=EB=82=B8=EB=8B=A4=20(0929/01-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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 --- .../presigned-transfer-and-image-cdn.md | 7 ++-- .../resumable-upload-runtime.ts | 7 ++++ .../resumable-upload-runtime-recovery.test.ts | 35 +++++++++++++++++++ 3 files changed, 47 insertions(+), 2 deletions(-) diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 37862c2c..d7ff38e6 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -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, 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 895af0f9..011ca6aa 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -986,6 +986,13 @@ async function uploadPartWithRetry( }), ); 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); diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index 1fddf0e8..14f069ae 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -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: [] },