diff --git a/config/recipes/frontend-capability-recipes.json b/config/recipes/frontend-capability-recipes.json index 0ba4f87e..386e792f 100644 --- a/config/recipes/frontend-capability-recipes.json +++ b/config/recipes/frontend-capability-recipes.json @@ -196,7 +196,7 @@ "owner": "project-owner-required", "securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."], "bundleBudgetGzipBytes": 57800, - "fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation.", + "fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation. The paired backend template has no presigned or direct multipart server (removed 2026-09-25): with it, upload through its Fileserver (POST /v1/files) with createFileserverUploadClient from src/adapters/http.", "removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."], "serverStatePolicy": "query-cache-metadata-only" }, diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index d7ff38e6..bd36689b 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -11,6 +11,17 @@ authorization owner는 아직 조합하지 않는다. 이 개별 runtime은 표처럼 다른 상태다. 어느 경로도 임의의 URL이나 object key를 application caller가 직접 전달하는 범용 HTTP facade가 아니다. +> **짝 백엔드와 맞지 않는다(2026-11-03 리뷰 01-01).** 이 문서의 presigned·resumable +> 프로토콜(`PRESIGNED_MULTIPART_V1`)을 받는 서버가 짝 백엔드 템플릿에는 없다. 짝 백엔드는 +> 2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일을 자기 Fileserver로 직접 +> 받는다(`POST /v1/files` multipart 한 번, `POST /v1/files:raw`, tus `/v1/uploads`). 두 템플릿을 +> 그대로 쓰는 업로드는 그 Fileserver로 올리는 것이다. 프론트 client는 +> `src/adapters/http/fileserver-upload.ts`의 `createFileserverUploadClient`(`POST /v1/files`)이고, +> 재개가 없다(`docs/manual/02-decision-tables.md` 「파일 업로드」). 이 문서의 경로는 제품 +> backend가 같은 BFF 계약을 직접 만들 때 쓴다 +> ([`server-file-capability-infrastructure.md`](./server-file-capability-infrastructure.md)). +> presigned 다운로드와 private Image CDN descriptor 발급 서버도 같은 이유로 짝 백엔드에 없다. + ## 0. 현재 구현과 목표 상태 이 문서에서 “설계됨”, “reference source가 있음”, “제품에 조합됨”과 “target @@ -381,7 +392,9 @@ complete 결과를 모를 때 클라이언트는 다음처럼 동작한다. resourceId 없이 닫는다(`resumable-upload-runtime.ts` `readCompletedResourceId`). - 서버가 complete를 반영한 뒤 로컬 checkpoint 삭제가 실패해도(IndexedDB 오류, complete 직후 caller abort) `upload()`는 성공을 돌려준다. 남은 행은 다음 - `upload()`나 `abort()`가 같은 자원으로 정리한다. + `upload()`나 `abort()`가 같은 자원으로 정리한다. 응답을 잃은 complete를 다음 + `upload()`가 재조정해 서버 status `QUARANTINED`를 찾았을 때도 같다 + (0929/01-02, `reconcileActiveCheckpoint`). 서버 계약 — complete 진행 중(`ResumableUploadControlPlane.complete` 주석): @@ -743,6 +756,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에 diff --git a/docs/architecture/server-file-capability-infrastructure.md b/docs/architecture/server-file-capability-infrastructure.md index 9a20b9c5..c02dfa2d 100644 --- a/docs/architecture/server-file-capability-infrastructure.md +++ b/docs/architecture/server-file-capability-infrastructure.md @@ -1,10 +1,22 @@ # Server file capability infrastructure handoff -- 상태: 설계 완료, 서버 구현 대기 +- 상태: 설계 완료. 짝 백엔드 템플릿은 구현하지 않음(2026-09-25 제거) - 목표 상태: `AVAILABLE_NOT_COMPOSED` -- 대상: 이후 서버 template 또는 제품 backend에서 구현할 공통 file capability +- 대상: 제품 backend가 직접 구현할 공통 file capability - 비대상: 제품 domain, 제품 use case, HTTP route/controller, provider 선택 -- 기준일: 2026-07-28 +- 기준일: 2026-07-28 (상태 줄은 2026-11-04에 고침) + +> **짝 백엔드와 맞지 않는다.** 짝 백엔드 템플릿(`clean-architecture-backend-template`)은 +> 2026-09-25에 presigned·direct multipart 코드를 지웠다(그 repo의 +> `docs/storage-capability-boundary.md`, `docs/capability-status.md` 「제거된 코드」). +> 그래서 이 문서의 server port와 프론트 `PRESIGNED_MULTIPART_V1` 레시피를 받는 서버가 +> 짝 백엔드에는 없다. 짝 백엔드는 파일을 자기 Fileserver가 직접 받는다 +> (`POST /v1/files` multipart 한 번, `POST /v1/files:raw`, tus `/v1/uploads`). +> 두 템플릿을 그대로 쓰는 업로드는 짝 백엔드 Fileserver로 올리는 것이다. 프론트 client는 +> `src/adapters/http/fileserver-upload.ts`의 `createFileserverUploadClient`(`POST /v1/files`)다. +> 고르는 기준과 기능에 붙이는 법은 +> `docs/manual/02-decision-tables.md` 「파일 업로드」에 있다. 이 문서는 제품 backend가 +> presigned 경로를 직접 만들기로 할 때의 설계로 남긴다. 이 문서는 frontend에 준비된 File/Blob/picker/download capability와 이후 연결할 서버측 기반을 정의한다. 서버는 object storage, multipart, integrity, diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 305b2605..0b740878 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -1,6 +1,6 @@ # 02. 결정표 -기능을 만들며 고르는 여섯 가지다. 각 절은 같은 순서로 쓴다. +기능을 만들며 고르는 일곱 가지다. 각 절은 같은 순서로 쓴다. ```text 무엇을 고르나 → 선택지 비교 → 고르는 기준 → 어디에 적나 → 틀리면 무엇이 잡나 @@ -227,3 +227,129 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 템플릿은 데이터를 가져오지 않는다. 데이터와 동작은 props로 받는다. 템플릿 파일이 application·어댑터를 import하면 `check:architecture`가 `page-templates-own-layout-only`로 막는다. - 디자인 시스템 하위 경로를 import하면 `design-system-is-reached-through-its-index`로 막는다. - 템플릿을 잘못 고른 것은 검사가 잡지 못한다. + +--- + +## 7. 파일 업로드 + +**무엇을 고르나**: 기능이 파일을 서버에 올리는 경로. + +**두 템플릿을 짝으로 쓰면 presigned 레시피는 맞지 않는다.** + +- 프론트 `src/adapters/browser-transfer/`의 resumable upload는 `PRESIGNED_MULTIPART_V1` 서버를 가정한다. 브라우저가 object store에 바로 PUT하는 방식이다. +- 짝 백엔드는 2026-09-25에 그 서버 코드(presigned·direct multipart)를 지웠다. 파일은 자기 Fileserver가 직접 받는다(`clean-architecture-backend-template/docs/fileserver/http-contract.md`). +- 이 레시피를 짝 백엔드에 그대로 붙이면 첫 응답부터 읽지 못한다. 백엔드는 응답을 Envelope로 감싸고, 레시피의 control plane은 감싸지 않은 DTO를 기대한다. +- 짝으로 쓰는 경로는 Fileserver의 multipart 한 번 업로드(`POST /v1/files`)다. 프론트 client는 `src/adapters/http/fileserver-upload.ts`의 `createFileserverUploadClient`다. + +```text +사용자가 파일을 고른다 (FilePickerPort → LocalFileRef) + → FileContentPort.openSource(ref) → FileByteSource + → 기능 어댑터: upload({ source, filename, mediaType, idempotencyKey, signal }) + → POST /v1/files (multipart, 파트 이름 file) + → 201 READY 또는 202 VERIFYING + 저장된 파일 정보(fileId, sha256 …) +``` + +- `FileByteSource`: 고른 파일의 바이트를 조각으로 읽는 값이다. `File`·`Blob`은 파일 어댑터 밖으로 나오지 않는다. +- 파일 선택·읽기(`createBrowserFileRuntime`, `src/adapters/browser-files/index.ts`)도 `file-transfer` 레시피라 제품이 조립한다(`productionComposition: false`). + +| | Fileserver 한 번 업로드 | presigned resumable 레시피 | +|---|---|---| +| 짝 백엔드 | 맞는다 | 서버가 없다 | +| 코드 | `src/adapters/http/fileserver-upload.ts` | `src/adapters/browser-transfer/index.ts` | +| 끊긴 뒤 | 처음부터 다시 보낸다 | part 단위로 이어 간다 | +| 메모리 | 파일 전체를 한 번 읽는다. `maxFileBytes`까지 | part 크기 × 동시 수 | +| 바이트 경로 | 앱 서버를 지난다 | 브라우저 → object store | + +**기준** + +- 짝 백엔드를 그대로 쓰면 Fileserver 한 번 업로드를 쓴다. +- 큰 파일을 끊긴 데서 이어 올려야 하면 지금 템플릿에는 짝 경로가 없다. 짝 백엔드의 tus(`/v1/uploads`)를 부르는 프론트 client는 아직 없다. +- presigned 레시피는 제품 backend가 그 BFF 계약(`docs/architecture/server-file-capability-infrastructure.md`)을 직접 만들 때만 쓴다. + +**결과 읽기**: `upload()`는 `Result`를 돌려준다. + +- 성공 `state`가 `READY`(201)면 바로 내려받을 수 있다. 그 밖(202 `VERIFYING` 등)은 서버가 아직 검사 중이다. +- 실패 `effect`: + - `NOT_STARTED`: 보내지 않았다. 입력, 크기, 자격 증명에서 거절했다. + - `NOT_APPLIED`: 서버가 거절했고 파일은 없다. Fileserver는 모호하지 않은 실패에서 업로드를 취소한다. 아래 `MAYBE_APPLIED` 경우를 뺀 4xx와, 5xx 중 정한 code(`STORAGE_UNAVAILABLE` 등)다. + - `MAYBE_APPLIED`: 올라갔을 수도 있다. 응답을 잃음, 시간 초과, `details.ambiguous: true`, 409 `IDEMPOTENT_IN_FLIGHT`, 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, 그 밖의 5xx다. 다시 보낼 때는 같은 `idempotencyKey`를 쓴다. + - `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다. +- `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 화면 문구는 기능이 code로 고른다. +- client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. + +**주의 — 멱등 키**: 짝 백엔드(`bbe944bd`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). + +- 그래서 `MAYBE_APPLIED` 뒤 다시 보내면 같은 파일이 두 개 생길 수 있다. +- 같은 키 재전송이 중복을 막는 것은 배포가 업로드를 백엔드 멱등성 executor 뒤에 둘 때뿐이다. +- 그 전에는 다시 보내기 전에 업무 데이터(파일 목록 등)로 먼저 확인한다. + +**어디에 적나**: 두 곳이다. + +1. `src/bootstrap/product-composition.ts`: client를 만들 재료(주소, 인증 프로필, 자격 증명, 크기 상한)를 capability로 넘긴다. client 코드는 넘기지 않는다. 기능 adapter는 기능 runtime과 함께 늦게 적재되므로, 업로드 코드가 boot 번들이 아니라 기능 chunk에 든다. +2. 기능 `adapters/create--feature-input.ts`: `needs`에 그 capability를 적고, 거기서 `createFileserverUploadClient`를 부른다. + +```ts +// src/bootstrap/product-composition.ts (제품 소유). BACKEND_SESSION은 +// src/contracts/product-contracts.ts에 더한 쿠키 세션 프로필이다. +import type { FileserverUploadClientDependencies } from "../adapters/http/index.ts"; +import { PRODUCT_REST_AUTH_PROFILES } from "../contracts/product-contracts.ts"; +// 파일에 이미 있는 import에 ProductCredentialProvider를 더한다. +import type { ProductCredentialProvider } from "./product-composition-contract.ts"; + +declare module "../features/feature-adapter-contribution.ts" { + interface FeaturePlatformCapabilities { + readonly fileserverUpload: FileserverUploadClientDependencies; + } +} + +export function composeProduct(context: ProductCompositionContext) { + const sessionCredentials: ProductCredentialProvider = () => { + if (!context.isScopeReady()) return { kind: "SCOPE_FENCED" }; + const csrf = context.readCookie("XSRF-TOKEN"); + return csrf === undefined + ? { kind: "UNAUTHENTICATED" } + : { kind: "READY", headers: { "x-xsrf-token": csrf } }; + }; + return { + capabilities: { + fileserverUpload: { + baseUrl: context.config.API_BASE_URL, + authProfile: PRODUCT_REST_AUTH_PROFILES.BACKEND_SESSION, + attachCredentials: sessionCredentials, + maxFileBytes: 20 * 1024 * 1024, + ...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }), + }, + }, + credentialProviders: { BACKEND_SESSION: sessionCredentials }, + } satisfies ProductComposition; +} +``` + +```ts +// src/features//adapters/create--feature-input.ts +import { createFileserverUploadClient } from "../../../adapters/http/index.ts"; +import { defineFeatureAdapterContribution } from "../../feature-adapter-contribution.ts"; + +export const createAttachmentFeatureInput = defineFeatureAdapterContribution({ + featureId: "attachment", + needs: ["http", "fileserverUpload"], + createInput: ({ http, fileserverUpload }) => { + const uploads = createFileserverUploadClient(fileserverUpload); + return { + featureId: "attachment", + // 기능 port 구현이 uploads.upload({ source, filename, mediaType, idempotencyKey, signal })를 부른다. + input: { /* … */ }, + }; + }, +}); +``` + +- `baseUrl`은 끝이 `/`여야 한다. `v1/files`를 그 아래에 붙인다. 경로가 base 밖으로 나가면 조립할 때 `TypeError`다. +- 자격 증명 함수는 V3 실행기의 `attachCredentials`와 계약이 같다. 같은 프로필의 `credentialProviders`를 그대로 쓴다. 프로필이 허락하지 않은 헤더를 주면 보내지 않고 `AUTH_INTEGRATION_FAILURE`다. + +**틀리면** + +- 프로필의 필수 헤더가 없으면 `fetch`를 부르지 않고 `MISSING_REQUIRED_CREDENTIAL_HEADER`로 끝난다. +- 파일이 `maxFileBytes`보다 크면 읽기 전에 `FILE_TOO_LARGE`(`NOT_STARTED`)다. +- 백엔드가 Fileserver 응답 모양이나 code를 바꾸면 검사가 잡지 못한다. 실패 판정 표(`fileserver-upload.ts`의 `NOT_APPLIED_5XX_CODES`, `MAYBE_APPLIED_CODES`)는 백엔드 `bbe944bd` 기준이다. 백엔드 SHA가 바뀌면 같이 다시 본다. +- 테스트 예: `tests/integration/fileserver-upload.test.ts`(백엔드 계약대로 답하는 MSW). diff --git a/docs/manual/README.md b/docs/manual/README.md index 8550e843..c252c66a 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -28,7 +28,7 @@ README (이 문서) | 문서 | 내용 | |---|---| | [`01-add-a-feature.md`](01-add-a-feature.md) | 0~11단계. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것, 쓸 스킬 | -| [`02-decision-tables.md`](02-decision-tables.md) | context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿 | +| [`02-decision-tables.md`](02-decision-tables.md) | context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드 | | [`03-outside-feature-folder.md`](03-outside-feature-folder.md) | 기능 폴더 밖 파일. 생성 명령이 하는 것과 사람이 하는 것 | | [`04-paired-backend-session.md`](04-paired-backend-session.md) | 짝 백엔드의 두 인증 모드(JWT·Keycloak, Redis session)에 맞는 세션 owner를 붙이는 법 | | [`reference/create-feature.md`](reference/create-feature.md) | `create:feature`의 인자, 만드는 파일, 거부 조건, 출력 | diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index b7cb7bf3..a584972c 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -87,6 +87,7 @@ const search = (q: string) => | 문제 응답 → 업무 실패 | `mapProblem` (HTTP 바인딩) | 참조 기능 `adapters/reference-http-gateway.ts` (409, 422) | 기능 테스트 | | 결과와 실패 | `src/contracts/result.ts`, `src/contracts/errors.ts` | 생성 뼈대 `application/-feature-api.ts` | `FailureKind` 닫힌 어휘(타입) | | 실패 → 화면 행동 | `src/contracts/errors.ts`의 `action` | 참조 기능 `presentation/use-reference-failure-action.ts` | 페이지 테스트 | +| 파일 업로드 (짝 백엔드 Fileserver) | `src/adapters/http/index.ts`의 `createFileserverUploadClient` (`POST /v1/files`) | 없음 (기능 예제). 조립은 [02 결정표 7절](../02-decision-tables.md#7-파일-업로드) | `tests/integration/fileserver-upload.test.ts` | ## 서버 상태 diff --git a/docs/reviews/adapters/01-network-and-state.md b/docs/reviews/adapters/01-network-and-state.md index 1859961f..550a28f3 100644 --- a/docs/reviews/adapters/01-network-and-state.md +++ b/docs/reviews/adapters/01-network-and-state.md @@ -62,6 +62,7 @@ All 24 files below were read in full. | src/adapters/http/bounded-body-reader.ts | Declared-length and streamed byte ceilings, stream cancellation/release isolation, forbidden-body probing, strict UTF-8/JSON decode | V3 executor; bounded-body-reader tests | Keep as the single bounded response primitive. It already contains the cleanup behavior missing from bounded-json.ts. | | src/adapters/http/bounded-json.ts | Legacy response stream reader and JSON decoder | legacy client.ts | Replace internals with bounded-body-reader delegation, then remove with V2 retirement. Current cancel/release failures can reject. Deleted 2026-11-03 with the V2 client (V3 is the only HTTP path). | | src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Not a drop-in rollback for V3: V2 validates the `{success,data,meta}` envelope and V3 the bare DTO, so a rollback needs the four slots and a V2-envelope server (Q-6.3-11). 401 recovery is a single replay outside the retry budget. Deprecate after callers are migrated. Deleted 2026-11-03 with the V2 client (V3 is the only HTTP path). | +| src/adapters/http/fileserver-upload.ts | The paired backend Fileserver multipart single upload (`POST /v1/files`): reads a FileByteSource into one multipart body, sends it under the auth profile, reads the Envelope answer into a Result with an effect verdict | backend-envelope.ts, bounded-body-reader.ts, http-contract-bridge.ts credential admission; kernel abort and Retry-After; product composition builds it | Added 2026-11-03 (review 01-01). Keep in the http adapter so the backend wire stays read in one place; one request per call, no automatic resend. | | src/adapters/http/http-contract-bridge.ts | V3 request projection, URL/body bounds, credential patch type, final request invariant | external-contract-runtime.ts; V3 executor | Preserve descriptor-owned request projection. Change credential authority: patch cannot own credentials or transport headers; final invariant must compare exact resolved profile. | | src/adapters/http/http-effect-certainty.ts | Converts physical-attempt state and problem descriptors into mutation certainty/UI projection | V3 executor; contracts | Preserve explicit certainty vocabulary. Add a monotonic logical-execution certainty join used across retries. | | src/adapters/http/http-execution-v3.ts | Descriptor-driven V3 lifetime: validation, projection, credentials, deadline, retry, fetch, response admission, effect verdict and observation | external contracts, scope, mutation intent, bridge, bounded reader, certainty, retry policy | Main correction site for N-01, N-02, N-03 and cooperative cancellation. Keep one retry authority and closed result union. | diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index d86ef817..7531aafe 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -148,6 +148,7 @@ | 138 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) | | 139 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | | 140 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 141 | `src/adapters/http/fileserver-upload.ts` | [Network/state](./01-network-and-state.md) | -합계: **140/140**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. +합계: **141/141**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. 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 011ca6aa..da280ebe 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -572,7 +572,7 @@ async function reconcileActiveCheckpoint( Object.freeze({ kind: "TERMINAL" as const }), ); } - return stripProviderFailure(statusResult); + return stripProviderFailure(statusResult, dependencies.policy); } const status = validateStatus( statusResult.value, @@ -582,12 +582,11 @@ async function reconcileActiveCheckpoint( ); if (!status.ok) return status; if (status.value.state === "QUARANTINED") { - const removed = await removeCheckpoint( - dependencies, - checkpoint, - request.signal, - ); - if (!removed.ok) return removed; + // 0929/01-02. The server already holds the resource. A failed local + // cleanup leaves the row for the next upload() or abort(), which finds the + // same resource; it does not cost this caller the resourceId, as on the + // complete path. + await removeCheckpoint(dependencies, checkpoint, request.signal); return browserDataSuccess( Object.freeze({ kind: "COMPLETED" as const, @@ -674,7 +673,7 @@ async function createUploadSession( signal: attemptSignal, }), ); - if (!created.ok) return stripProviderFailure(created); + if (!created.ok) return stripProviderFailure(created, dependencies.policy); const session = validateSession( created.value, requestBindingSha256, @@ -879,6 +878,9 @@ async function transferMissingParts( { recovery: "RESELECT" }, ); } + // 1101/01-02. An accepted part is not sent, so it is not hashed either; + // the manifest above already checked the file against the checkpoint. + if (accepted.has(part.partNumber)) continue; const verified = await verifyUploadPartBytes({ bytes: partResult.value.bytes, part, @@ -886,7 +888,6 @@ async function transferMissingParts( signal: request.signal, }); if (!verified.ok) return verified; - if (accepted.has(part.partNumber)) continue; const attempts = { count: 0 }; const uploaded = await uploadPartWithRetry( dependencies, @@ -995,7 +996,7 @@ async function uploadPartWithRetry( } lastFailure = issued.error; if (!canRetry(issued.error, attempt, dependencies.policy)) { - return stripProviderFailure(issued); + return stripProviderFailure(issued, dependencies.policy); } continue; } @@ -1075,12 +1076,13 @@ async function uploadPartWithRetry( 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 +1132,9 @@ async function completeUpload( 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 +1248,7 @@ async function executeAbort( ) : remapResult(removed, "UPLOAD_ABORT"); } - return stripProviderFailure(aborted); + return stripProviderFailure(aborted, dependencies.policy); } if ( !exactRecord(aborted.value, ["state"]) || @@ -1308,7 +1312,10 @@ async function readCompletedResourceId( 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 +1680,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( result: UploadProviderResult, + policy: ResumableUploadRuntimePolicy, ): BrowserDataResult { 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, }); } diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts new file mode 100644 index 00000000..b9171dfb --- /dev/null +++ b/src/adapters/http/fileserver-upload.ts @@ -0,0 +1,717 @@ +import type { FileByteSource } from "../../application/ports/browser-file-storage/file.ts"; +import { + createFailure, + type AppFailure, + type FailureEffectCertainty, + type FailureKind, +} from "../../contracts/errors.ts"; +import { isValidIdempotencyKey } from "../../contracts/mutation-intent.ts"; +import type { RestAuthProfile } from "../../contracts/rest-profiles.ts"; +import type { Result } from "../../contracts/result.ts"; +import { z } from "../../contracts/zod.ts"; +import { + cancelBody, + createAbortableOperation, + type AbortableOperation, +} from "../platform/abortable-operation.ts"; +import { parseRetryAfterDelay } from "../platform/retry-after.ts"; +import { + envelopeFailureReading, + gatewayFailureOr, + readFailureEnvelope, + readSuccessEnvelope, + type EnvelopeError, +} from "./backend-envelope.ts"; +import { + declaredContentLength, + isJsonMediaType, + readBoundedBytes, +} from "./bounded-body-reader.ts"; +import { + admitCredentialHeaders, + type CredentialPatchOutcome, +} from "./http-contract-bridge.ts"; +import type { AuthOperationContext } from "./http-execution-v3.ts"; + +/** + * 2026-11-03 01-01. A client for the paired backend Fileserver's multipart + * single upload, `POST /v1/files` (clean-architecture-backend-template + * `bbe944bd`, docs/fileserver/http-contract.md; Envelope and idempotency in + * docs/web/http-contract.md §1–§2). + * + * The paired backend removed presigned and direct multipart transfer on + * 2026-09-25, so the presigned resumable recipe in `browser-transfer` has no + * server there. This is the path that pairs with it: the bytes go to the + * application server in one request, and the answer is the stored file's + * public descriptor. + * + * The file arrives as the `FileByteSource` that `FileContentPort.openSource` + * gives, so no `File` or `Blob` crosses into this adapter. Its bytes are read + * once into the multipart body, at most `maxFileBytes` of them; a file that + * declares a larger size is refused before reading. + * + * One request per call. The client never resends: the body is the whole + * file, and only the caller knows whether to spend that again. It keeps the + * recipe's transport rules: Fetch credentials from the auth profile, proof + * headers admitted against that profile, `redirect: "error"`, no referrer, no + * cache, a bounded response body, and one deadline that grows with the bytes. + */ + +export type FileserverFileState = "READY" | "UPLOADED" | "VERIFYING" | "QUARANTINED"; + +/** The stored file, as the backend's `UploadedFileResponse` describes it. */ +export type FileserverUploadedFile = Readonly<{ + fileId: string; + /** `READY` with 201. Anything else came with 202: not readable yet. */ + state: FileserverFileState; + filename: string; + mediaType: string; + size: number; + sha256: string; + etag: string; +}>; + +export type FileserverUploadRequest = Readonly<{ + source: FileByteSource; + /** The multipart filename, untrusted on the server. Defaults to `upload.bin`. */ + filename?: string; + /** The part's Content-Type, a claim the server verifies. */ + mediaType?: string; + /** + * Sent as `Idempotency-Key`. After a `MAYBE_APPLIED` failure, resend with + * the same key and never a new one. At `bbe944bd` the backend runs + * `POST /v1/files` without its idempotency executor, so the key protects + * only a deployment that routes the upload through it. + */ + idempotencyKey?: string; + signal: AbortSignal; +}>; + +export type FileserverUploadClient = Readonly<{ + upload( + request: FileserverUploadRequest, + ): Promise>; +}>; + +export type FileserverUploadClientDependencies = Readonly<{ + /** Origin and optional path prefix; `v1/files` is resolved under it. */ + baseUrl: string; + /** Owns Fetch `credentials` and the proof headers a provider may add. */ + authProfile: RestAuthProfile; + /** Same contract as the V3 executor's `attachCredentials`. */ + attachCredentials( + operation: Readonly<{ + operationId: string; + authProfileId: string; + method: string; + }>, + context: AuthOperationContext, + ): Promise | CredentialPatchOutcome; + /** A larger file is refused before it is read. */ + maxFileBytes: number; + fetcher?: typeof fetch; + /** Base deadline in ms. The transfer allowance is added on top. */ + timeoutMs?: number; + /** Lowest supported uplink; sets the per-byte allowance. */ + minTransferBytesPerSecond?: number; + maxResponseBytes?: number; + /** A longer server `Retry-After` is dropped and ends `retryable: false`. */ + maxRetryAfterMs?: number; + nowEpochMs?: () => number; + monotonicNow?: () => number; +}>; + +export const FILESERVER_UPLOAD_OPERATION_ID = "FILESERVER_UPLOAD"; + +const DEFAULTS = Object.freeze({ + timeoutMs: 30_000, + // The resumable runtime's default uplink floor (runtime-policy.ts). + minTransferBytesPerSecond: 64 * 1024, + maxResponseBytes: 16 * 1024, + maxRetryAfterMs: 30_000, + filename: "upload.bin", + mediaType: "application/octet-stream", +}); + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u; +const SHA256_HEX = /^[0-9a-f]{64}$/u; +const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/u; +const MAX_FILENAME_LENGTH = 255; + +/** + * Backend `UploadFileApplicationUseCase` cancels the upload on every failure + * except an ambiguous completion, and the Fileserver contract marks a failure + * that may already have taken effect with `details.ambiguous`. So a 4xx + * Envelope is NOT_APPLIED unless it says otherwise. A 5xx stays MAYBE_APPLIED + * except these codes, which the backend raises before the file is published + * (`FileserverErrorCode`; 503 IDEMPOTENCY_UNAVAILABLE is web contract §2). + * Recheck both lists when the backend SHA above moves. + */ +const NOT_APPLIED_5XX_CODES: ReadonlySet = new Set([ + "PARTIAL_WRITE", + "ATOMIC_PUBLISH_UNSUPPORTED", + "STORAGE_UNAVAILABLE", + "TRANSFER_TIMEOUT", + "STORAGE_FULL", + "IDEMPOTENCY_UNAVAILABLE", +]); + +/** Answers that may have taken effect whatever their status. */ +const MAYBE_APPLIED_CODES: ReadonlySet = new Set([ + "AMBIGUOUS_COMPLETION", + // Web contract §2: resend with the same key, never a new one. + "IDEMPOTENT_IN_FLIGHT", + "IDEMPOTENCY_COMPLETION_UNKNOWN", + "IDEMPOTENCY_RECOVERY_REQUIRED", +]); + +export function createFileserverUploadClient( + dependencies: FileserverUploadClientDependencies, +): FileserverUploadClient { + const settings = snapshotDependencies(dependencies); + const fetcher = dependencies.fetcher ?? fetch; + if (typeof fetcher !== "function") { + throw new TypeError("Fileserver upload dependency is invalid: fetcher."); + } + // Built here, not at module scope, so an app that never composes the client + // carries none of it in its boot bundle. + const uploadedFileSchema = z + .object({ + fileId: z.string().regex(UUID), + state: z.enum(["READY", "UPLOADED", "VERIFYING", "QUARANTINED"]), + filename: z.string().min(1).max(1_024), + mediaType: z.string().min(1).max(255), + size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), + sha256: z.string().regex(SHA256_HEX), + etag: z.string().min(1).max(256), + }) + // A field the backend adds later is ignored, not copied. + .strip(); + + return Object.freeze({ + async upload(request) { + const admitted = admitRequest(request); + if (!admitted.ok) return admitted; + const { idempotencyKey, signal } = admitted.value; + const body = await readMultipartBody(admitted.value, settings.maxFileBytes); + if (!body.ok) return body; + const timeoutMs = + settings.timeoutMs + + Math.ceil( + (body.value.fileBytes / settings.minTransferBytesPerSecond) * 1_000, + ); + const attempt = createAbortableOperation({ signal, timeoutMs }); + try { + if (attempt.terminal() !== null) { + return terminalFailure(attempt, "NOT_STARTED"); + } + const credentials = await credentialHeaders( + settings, + attempt, + settings.monotonicNow() + timeoutMs, + ); + if (!credentials.ok) return credentials; + const headers: Record = { + ...credentials.value, + accept: "application/json", + "content-type": `multipart/form-data; boundary=${body.value.boundary}`, + ...(idempotencyKey === undefined + ? {} + : { "idempotency-key": idempotencyKey }), + }; + let pendingResponse: Promise; + try { + pendingResponse = fetcher(settings.url, { + method: "POST", + headers, + body: body.value.bytes, + credentials: settings.authProfile.credentials, + redirect: "error", + referrerPolicy: "no-referrer", + cache: "no-store", + signal: attempt.signal, + }); + } catch { + // A synchronous throw from fetch means nothing went out. + return failure("NETWORK_UNREACHABLE", "NETWORK_UNREACHABLE", { + effect: "NOT_STARTED", + }); + } + const sent = await attempt.race(pendingResponse, cancelBody); + if (sent.kind === "TERMINAL") { + return terminalFailure(attempt, "MAYBE_APPLIED"); + } + if (sent.kind === "REJECTED") { + // The bytes may have reached the server before the connection broke. + return failure("NETWORK_UNREACHABLE", "NETWORK_UNREACHABLE", { + effect: "MAYBE_APPLIED", + }); + } + return await readAnswer( + sent.value, + attempt, + settings, + uploadedFileSchema, + body.value.fileBytes, + ); + } finally { + attempt.close(); + } + }, + }); +} + +type Settings = Readonly<{ + url: string; + authProfile: RestAuthProfile; + attachCredentials: FileserverUploadClientDependencies["attachCredentials"]; + maxFileBytes: number; + timeoutMs: number; + minTransferBytesPerSecond: number; + maxResponseBytes: number; + maxRetryAfterMs: number; + nowEpochMs: () => number; + monotonicNow: () => number; +}>; + +function snapshotDependencies( + dependencies: FileserverUploadClientDependencies, +): Settings { + const invalid = (field: string): never => { + throw new TypeError(`Fileserver upload dependency is invalid: ${field}.`); + }; + if (!dependencies || typeof dependencies !== "object") invalid("dependencies"); + let base: URL | null = null; + try { + base = new URL(dependencies.baseUrl); + } catch { + invalid("baseUrl"); + } + if (!base || (base.protocol !== "https:" && base.protocol !== "http:")) { + return invalid("baseUrl"); + } + // Same join as the V3 request projection: under the base path, never above. + const url = new URL("v1/files", base); + if (url.origin !== base.origin || !url.pathname.startsWith(base.pathname)) { + invalid("baseUrl"); + } + const profile = dependencies.authProfile; + if ( + !profile || + typeof profile.authProfileId !== "string" || + !["omit", "same-origin", "include"].includes(profile.credentials) || + !Array.isArray(profile.allowedCredentialHeaders) || + !Array.isArray(profile.requiredCredentialHeaders) + ) { + invalid("authProfile"); + } + if (typeof dependencies.attachCredentials !== "function") { + invalid("attachCredentials"); + } + const positive = (value: number | undefined, fallback: number, field: string) => { + const resolved = value ?? fallback; + return Number.isSafeInteger(resolved) && resolved > 0 + ? resolved + : invalid(field); + }; + return Object.freeze({ + url: url.href, + authProfile: Object.freeze({ + ...profile, + allowedCredentialHeaders: Object.freeze([...profile.allowedCredentialHeaders]), + requiredCredentialHeaders: Object.freeze([...profile.requiredCredentialHeaders]), + }), + attachCredentials: dependencies.attachCredentials, + maxFileBytes: positive(dependencies.maxFileBytes, 0, "maxFileBytes"), + timeoutMs: positive(dependencies.timeoutMs, DEFAULTS.timeoutMs, "timeoutMs"), + minTransferBytesPerSecond: positive( + dependencies.minTransferBytesPerSecond, + DEFAULTS.minTransferBytesPerSecond, + "minTransferBytesPerSecond", + ), + maxResponseBytes: positive( + dependencies.maxResponseBytes, + DEFAULTS.maxResponseBytes, + "maxResponseBytes", + ), + maxRetryAfterMs: positive( + dependencies.maxRetryAfterMs, + DEFAULTS.maxRetryAfterMs, + "maxRetryAfterMs", + ), + nowEpochMs: dependencies.nowEpochMs ?? (() => Date.now()), + monotonicNow: dependencies.monotonicNow ?? (() => performance.now()), + }); +} + +type AdmittedRequest = Readonly<{ + source: FileByteSource; + filename: string; + mediaType: string; + idempotencyKey?: string; + signal: AbortSignal; +}>; + +function admitRequest( + request: FileserverUploadRequest, +): Result { + const inputInvalid = () => + failure("UNKNOWN_CLIENT_FAILURE", "FILESERVER_UPLOAD_INPUT_INVALID", { + effect: "NOT_STARTED", + }); + if (!request || typeof request !== "object") return inputInvalid(); + const { source, idempotencyKey, signal } = request; + const filename = request.filename ?? DEFAULTS.filename; + const mediaType = request.mediaType ?? DEFAULTS.mediaType; + if ( + !source || + typeof source.stream !== "function" || + (source.byteLength !== null && !Number.isSafeInteger(source.byteLength)) || + typeof filename !== "string" || + filename.length === 0 || + filename.length > MAX_FILENAME_LENGTH || + typeof mediaType !== "string" || + !MEDIA_TYPE.test(mediaType) || + (idempotencyKey !== undefined && !isValidIdempotencyKey(idempotencyKey)) || + !(signal instanceof AbortSignal) + ) { + return inputInvalid(); + } + return Object.freeze({ + ok: true as const, + value: Object.freeze({ + source, + filename, + mediaType, + ...(idempotencyKey === undefined ? {} : { idempotencyKey }), + signal, + }), + }); +} + +type MultipartBody = Readonly<{ + bytes: Uint8Array; + boundary: string; + fileBytes: number; +}>; + +/** + * RFC 7578 with one part named `file`, the backend's `@RequestParam("file")`. + * The filename is escaped as the HTML form encoder does (`"` → `%22`, CR and + * LF → `%0D` `%0A`) and sent as UTF-8. + */ +async function readMultipartBody( + request: AdmittedRequest, + maxFileBytes: number, +): Promise> { + const notSent = { effect: "NOT_STARTED" } as const; + if (request.signal.aborted) { + return failure("REQUEST_ABORTED", "REQUEST_ABORTED", notSent); + } + const declared = request.source.byteLength; + if (declared !== null && declared > maxFileBytes) { + // The server's code for the same refusal, so a feature handles one code. + return failure("VALIDATION_REJECTED", "FILE_TOO_LARGE", notSent); + } + const random = new Uint8Array(16); + crypto.getRandomValues(random); + const boundary = `----FileserverUpload${[...random] + .map((byte) => byte.toString(16).padStart(2, "0")) + .join("")}`; + const filename = request.filename.replace( + /["\r\n]/gu, + (character) => + character === '"' ? "%22" : character === "\r" ? "%0D" : "%0A", + ); + const encoder = new TextEncoder(); + const head = encoder.encode( + `--${boundary}\r\n` + + `Content-Disposition: form-data; name="file"; filename="${filename}"\r\n` + + `Content-Type: ${request.mediaType}\r\n\r\n`, + ); + const tail = encoder.encode(`\r\n--${boundary}--\r\n`); + // A declared size is written straight into the one body buffer. Without + // one, chunks are kept (still bounded by maxFileBytes) and copied once. + const sized = + declared === null + ? null + : new Uint8Array(head.byteLength + declared + tail.byteLength); + sized?.set(head, 0); + const chunks: Uint8Array[] = []; + let fileBytes = 0; + // The file changed between selection and reading. + const changed = () => + failure("VALIDATION_REJECTED", "FILE_NOT_READABLE", notSent); + try { + for await (const chunk of request.source.stream(request.signal)) { + if (request.signal.aborted) { + return failure("REQUEST_ABORTED", "REQUEST_ABORTED", notSent); + } + if (!chunk.ok) { + return chunk.error.code === "ABORTED" + ? failure("REQUEST_ABORTED", "REQUEST_ABORTED", notSent) + : changed(); + } + if (fileBytes + chunk.value.byteLength > maxFileBytes) { + return failure("VALIDATION_REJECTED", "FILE_TOO_LARGE", notSent); + } + if (sized) { + if (fileBytes + chunk.value.byteLength > (declared ?? 0)) { + return changed(); + } + sized.set(chunk.value, head.byteLength + fileBytes); + } else { + chunks.push(chunk.value); + } + fileBytes += chunk.value.byteLength; + } + } catch { + return changed(); + } + if (request.signal.aborted) { + return failure("REQUEST_ABORTED", "REQUEST_ABORTED", notSent); + } + if (declared !== null && fileBytes !== declared) return changed(); + let bytes: Uint8Array; + if (sized) { + bytes = sized; + } else { + bytes = new Uint8Array(head.byteLength + fileBytes + tail.byteLength); + bytes.set(head, 0); + let offset = head.byteLength; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.byteLength; + } + } + bytes.set(tail, head.byteLength + fileBytes); + return Object.freeze({ + ok: true as const, + value: Object.freeze({ bytes, boundary, fileBytes }), + }); +} + +async function credentialHeaders( + settings: Settings, + attempt: AbortableOperation, + deadlineAtMonotonicMs: number, +): Promise>, AppFailure>> { + const notSent = { effect: "NOT_STARTED" } as const; + let pending: Promise; + try { + pending = Promise.resolve( + settings.attachCredentials( + Object.freeze({ + operationId: FILESERVER_UPLOAD_OPERATION_ID, + authProfileId: settings.authProfile.authProfileId, + method: "POST", + }), + Object.freeze({ signal: attempt.signal, deadlineAtMonotonicMs }), + ), + ); + } catch { + pending = Promise.reject(new Error("credential owner failed")); + } + const answered = await attempt.race(pending); + if (answered.kind === "TERMINAL") { + return terminalFailure(attempt, "NOT_STARTED"); + } + if (answered.kind === "REJECTED" || !answered.value) { + return failure("AUTH_INTEGRATION_FAILURE", "CREDENTIAL_OWNER_FAILED", notSent); + } + const patch = answered.value; + switch (patch.kind) { + case "READY": { + // The profile, not the provider, decides which proof headers go out. + const admitted = admitCredentialHeaders( + patch.headers ?? {}, + settings.authProfile, + ); + return admitted.ok + ? Object.freeze({ + ok: true as const, + value: admitted.headers as Readonly>, + }) + : failure("AUTH_INTEGRATION_FAILURE", admitted.failure, notSent); + } + case "UNAUTHENTICATED": + return failure("AUTH_REQUIRED", "UNAUTHENTICATED", notSent); + case "SCOPE_FENCED": + return failure("SCOPE_GENERATION_CHANGED", "SCOPE_FENCED", notSent); + default: + return failure( + "AUTH_INTEGRATION_FAILURE", + "CREDENTIAL_OWNER_UNAVAILABLE", + notSent, + ); + } +} + +async function readAnswer( + response: Response, + attempt: AbortableOperation, + settings: Settings, + uploadedFileSchema: z.ZodType, + sentBytes: number, +): Promise> { + const status = response.status; + const created = status === 201 || status === 202; + // A 2xx the contract does not list says something happened; what is unknown. + const effect: FailureEffectCertainty = created + ? "APPLIED_CONFIRMED" + : "MAYBE_APPLIED"; + const unreadable = (kind: FailureKind, code: string) => + failure(created ? kind : gatewayFailureOr(status, kind), code, { + httpStatus: status, + effect, + }); + if (response.type === "opaqueredirect" || response.redirected) { + cancelBody(response); + return unreadable("ENVELOPE_MISMATCH", "REDIRECT_REFUSED"); + } + if (!isJsonMediaType(response.headers.get("content-type"))) { + cancelBody(response); + return unreadable("CONTENT_TYPE_MISMATCH", "CONTENT_TYPE_MISMATCH"); + } + // Checked here as well so the refusal does not wait on the body's cancel, + // which `readBoundedBytes` awaits. + const declaredLength = declaredContentLength(response); + if (declaredLength !== null && declaredLength > settings.maxResponseBytes) { + cancelBody(response); + return unreadable("RESPONSE_BODY_LIMIT", "RESPONSE_TOO_LARGE"); + } + const read = await attempt.race( + readBoundedBytes(response, settings.maxResponseBytes, attempt.signal), + ); + if (read.kind === "TERMINAL") { + cancelBody(response); + return terminalFailure(attempt, effect, status); + } + const bytes = read.kind === "VALUE" ? read.value : null; + if (!bytes?.ok) { + return bytes?.code === "RESPONSE_TOO_LARGE" + ? unreadable("RESPONSE_BODY_LIMIT", "RESPONSE_TOO_LARGE") + : failure("NETWORK_UNREACHABLE", "RESPONSE_STREAM_FAILURE", { + httpStatus: status, + effect, + }); + } + let json: unknown; + try { + json = JSON.parse( + new TextDecoder("utf-8", { fatal: true }).decode(bytes.bytes), + ); + } catch { + return unreadable("MALFORMED_JSON", "JSON_INVALID"); + } + + if (created) { + const envelope = readSuccessEnvelope(json); + if (!envelope.ok) return unreadable("ENVELOPE_MISMATCH", "ENVELOPE_INVALID"); + const parsed = uploadedFileSchema.safeParse(envelope.value); + if ( + !parsed.success || + (status === 201) !== (parsed.data.state === "READY") || + parsed.data.size !== sentBytes + ) { + return unreadable("SCHEMA_MISMATCH", "UPLOADED_FILE_INVALID"); + } + return Object.freeze({ + ok: true as const, + value: Object.freeze({ ...parsed.data }), + }); + } + if (status < 400) return unreadable("ENVELOPE_MISMATCH", "STATUS_UNEXPECTED"); + const envelope = readFailureEnvelope(json); + if (!envelope.ok) return unreadable("ENVELOPE_MISMATCH", "ENVELOPE_INVALID"); + return envelopeFailure(status, envelope.value, response, settings); +} + +function envelopeFailure( + status: number, + error: EnvelopeError, + response: Response, + settings: Settings, +): Result { + const effect = fileserverFailureEffect(status, error); + const retryAfterMs = parseRetryAfterDelay( + response.headers.get("retry-after"), + settings.nowEpochMs(), + ); + // 2026-11-03 01-02. A wait past the ceiling is not passed on as one to + // honour, and the failure is not retryable at once either. + const waitRefused = + retryAfterMs !== null && retryAfterMs > settings.maxRetryAfterMs; + const reading = envelopeFailureReading(status, error); + // A file the server refuses by size or type is the user's to replace, as + // the same refusal before sending is (`readMultipartBody`). + const kind: FailureKind = + status === 413 || status === 415 ? "VALIDATION_REJECTED" : reading.kind; + const created = createFailure(kind, FILESERVER_UPLOAD_OPERATION_ID, 0, { + code: reading.code, + httpStatus: status, + effect, + ...(retryAfterMs === null || waitRefused ? {} : { retryAfterMs }), + ...(reading.validationIssues === undefined + ? {} + : { validationIssues: reading.validationIssues }), + }); + // `retryable` in the Envelope is the server's decision for this answer and + // can only narrow the client's. + const retryable = + created.retryable && error.retryable !== false && !waitRefused; + return Object.freeze({ + ok: false as const, + error: + retryable === created.retryable + ? created + : Object.freeze({ ...created, retryable }), + }); +} + +/** See `NOT_APPLIED_5XX_CODES`. */ +export function fileserverFailureEffect( + status: number, + error: EnvelopeError, +): "NOT_APPLIED" | "MAYBE_APPLIED" { + const details = error.details; + const ambiguous = + details !== null && + typeof details === "object" && + !Array.isArray(details) && + (details as Readonly>)["ambiguous"] === true; + if (ambiguous || MAYBE_APPLIED_CODES.has(error.code)) return "MAYBE_APPLIED"; + if (status >= 400 && status < 500) return "NOT_APPLIED"; + return NOT_APPLIED_5XX_CODES.has(error.code) ? "NOT_APPLIED" : "MAYBE_APPLIED"; +} + +function terminalFailure( + attempt: AbortableOperation, + effect: FailureEffectCertainty, + httpStatus?: number, +): Result { + const details = { + effect, + ...(httpStatus === undefined ? {} : { httpStatus }), + }; + return attempt.terminal() === "DEADLINE" + ? failure("REQUEST_TIMEOUT", "TIMEOUT", details) + : failure("REQUEST_ABORTED", "REQUEST_ABORTED", details); +} + +function failure( + kind: FailureKind, + code: string, + details: Readonly<{ + effect: FailureEffectCertainty; + httpStatus?: number; + }>, +): Result { + return Object.freeze({ + ok: false as const, + error: createFailure(kind, FILESERVER_UPLOAD_OPERATION_ID, 0, { + code, + ...details, + }), + }); +} diff --git a/src/adapters/http/index.ts b/src/adapters/http/index.ts index c1af125a..c690584c 100644 --- a/src/adapters/http/index.ts +++ b/src/adapters/http/index.ts @@ -37,3 +37,16 @@ export { } from "./feature-http-binding.ts"; /** V3 `attachCredentials` 콜백이 반환해야 하는 결과 타입. */ export type { CredentialPatchOutcome } from "./http-contract-bridge.ts"; +/** + * 2026-11-03 01-01. 짝 백엔드 Fileserver의 multipart 한 번 업로드 + * (`POST /v1/files`). 제품 조립(`product-composition.ts`)이 만들어 기능에 넘긴다. + */ +export { + createFileserverUploadClient, + FILESERVER_UPLOAD_OPERATION_ID, + type FileserverFileState, + type FileserverUploadClient, + type FileserverUploadClientDependencies, + type FileserverUploadedFile, + type FileserverUploadRequest, +} from "./fileserver-upload.ts"; diff --git a/src/application/ports/browser-transfer/resumable-upload.ts b/src/application/ports/browser-transfer/resumable-upload.ts index d18811e3..46851e50 100644 --- a/src/application/ports/browser-transfer/resumable-upload.ts +++ b/src/application/ports/browser-transfer/resumable-upload.ts @@ -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, diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts new file mode 100644 index 00000000..0d8d8904 --- /dev/null +++ b/tests/integration/fileserver-upload.test.ts @@ -0,0 +1,557 @@ +import { delay, HttpResponse, http, type JsonBodyType } from "msw"; +import { setupServer } from "msw/node"; +import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest"; + +import type { FileByteSource } from "../../src/application/ports/browser-file-storage/file.ts"; +import { + createFileserverUploadClient, + type CredentialPatchOutcome, + type FileserverUploadClientDependencies, +} from "../../src/adapters/http/index.ts"; +import type { RestAuthProfile } from "../../src/contracts/rest-profiles.ts"; + +/** + * 2026-11-03 01-01. The paired backend Fileserver's `POST /v1/files`, answered + * exactly as clean-architecture-backend-template `bbe944bd` documents it: + * docs/fileserver/http-contract.md (201 READY / 202 VERIFYING, Envelope + * failure body, `details.ambiguous`, `Retry-After`) and docs/web/http-contract.md + * §1–§2 (Envelope keys, 409 IDEMPOTENT_IN_FLIGHT with `Retry-After: 2`). + * The success body is `UploadedFileResponse` wrapped by `EnvelopeBodyAdvice`. + */ +const BASE_URL = "https://api.test/api/"; +const UPLOAD_URL = "https://api.test/api/v1/files"; +const FILE_ID = "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f"; +const SHA256 = "a".repeat(64); +const META = Object.freeze({ requestId: "req-1", traceId: "trace-1" }); + +const COOKIE_PROFILE: RestAuthProfile = Object.freeze({ + authProfileId: "BACKEND_SESSION", + transport: "SAME_ORIGIN_COOKIE", + credentials: "same-origin", + allowedCredentialHeaders: Object.freeze(["x-xsrf-token"] as const), + requiredCredentialHeaders: Object.freeze(["x-xsrf-token"] as const), +}); + +const server = setupServer(); +beforeAll(() => server.listen({ onUnhandledRequest: "error" })); +afterEach(() => server.resetHandlers()); +afterAll(() => server.close()); + +function byteSource( + bytes: Uint8Array, + options: Readonly<{ byteLength?: number | null; chunkBytes?: number }> = {}, +): FileByteSource { + const chunkBytes = options.chunkBytes ?? 3; + return Object.freeze({ + byteLength: + options.byteLength === undefined ? bytes.byteLength : options.byteLength, + async *stream() { + for (let offset = 0; offset < bytes.byteLength; offset += chunkBytes) { + yield Object.freeze({ + ok: true as const, + value: bytes.slice(offset, offset + chunkBytes), + }); + } + }, + }); +} + +const FILE_BYTES = new TextEncoder().encode("%PDF-1.7 tiny file"); + +function uploaded(state: string, overrides: Readonly> = {}) { + return { + fileId: FILE_ID, + state, + filename: "report.pdf", + mediaType: "application/pdf", + size: FILE_BYTES.byteLength, + sha256: SHA256, + etag: `"${SHA256}"`, + ...overrides, + }; +} + +const successEnvelope = (data: unknown) => ({ success: true, data, meta: META }); + +const failureEnvelope = ( + code: string, + category: string, + retryable: boolean, + details?: Readonly>, +) => ({ + success: false, + error: { + code, + category, + message: "현재 상태에서는 요청을 처리할 수 없습니다.", + retryable, + ...(details === undefined ? {} : { details }), + }, + meta: META, +}); + +type Captured = Readonly<{ + headers: Headers; + form: FormData; +}>; + +/** Answers every upload with `answers[i]`, the last one repeating. */ +function answer( + ...answers: readonly (Readonly<{ + status: number; + body: JsonBodyType; + headers?: Record; + }> | "NETWORK_ERROR")[] +): Captured[] { + const captured: Captured[] = []; + server.use( + http.post(UPLOAD_URL, async ({ request }) => { + captured.push({ + headers: request.headers, + form: await request.formData(), + }); + const next = answers[Math.min(captured.length, answers.length) - 1]; + if (!next || next === "NETWORK_ERROR") return HttpResponse.error(); + return HttpResponse.json(next.body, { + status: next.status, + ...(next.headers === undefined ? {} : { headers: next.headers }), + }); + }), + ); + return captured; +} + +function client(overrides: Partial = {}) { + const attachCredentials = vi.fn( + (): CredentialPatchOutcome => ({ + kind: "READY", + headers: { "x-xsrf-token": "csrf-token-1" }, + }), + ); + return { + attachCredentials, + client: createFileserverUploadClient({ + baseUrl: BASE_URL, + authProfile: COOKIE_PROFILE, + attachCredentials, + maxFileBytes: 1_024, + nowEpochMs: () => 1_000_000, + ...overrides, + }), + }; +} + +const upload = ( + overrides: Readonly> = {}, +) => ({ + source: byteSource(FILE_BYTES), + filename: "report.pdf", + mediaType: "application/pdf", + idempotencyKey: "upload-key-01", + signal: new AbortController().signal, + ...overrides, +}); + +describe("Fileserver multipart upload — success", () => { + it("sends one multipart part named file and reads 201 READY", async () => { + const captured = answer({ status: 201, body: successEnvelope(uploaded("READY")) }); + const { client: uploader, attachCredentials } = client(); + + const result = await uploader.upload(upload()); + + expect(result).toEqual({ ok: true, value: uploaded("READY") }); + expect(captured).toHaveLength(1); + const [request] = captured; + const part = request?.form.get("file"); + expect(part).toBeInstanceOf(File); + expect((part as File).name).toBe("report.pdf"); + expect((part as File).type).toBe("application/pdf"); + expect(new Uint8Array(await (part as File).arrayBuffer())).toEqual(FILE_BYTES); + expect([...(request?.form.keys() ?? [])]).toEqual(["file"]); + expect(request?.headers.get("idempotency-key")).toBe("upload-key-01"); + expect(request?.headers.get("x-xsrf-token")).toBe("csrf-token-1"); + expect(request?.headers.get("accept")).toBe("application/json"); + expect(request?.headers.get("content-type")).toMatch( + /^multipart\/form-data; boundary=----FileserverUpload[0-9a-f]{32}$/u, + ); + expect(attachCredentials).toHaveBeenCalledWith( + { operationId: "FILESERVER_UPLOAD", authProfileId: "BACKEND_SESSION", method: "POST" }, + expect.objectContaining({ signal: expect.any(AbortSignal) }), + ); + }); + + it("reads 202 VERIFYING as a stored file that is not readable yet", async () => { + answer({ status: 202, body: successEnvelope(uploaded("VERIFYING")) }); + + const result = await client().client.upload(upload()); + + expect(result).toEqual({ ok: true, value: uploaded("VERIFYING") }); + }); + + it("sends a source whose size is not declared up front", async () => { + const captured = answer({ status: 201, body: successEnvelope(uploaded("READY")) }); + + const result = await client().client.upload( + upload({ source: byteSource(FILE_BYTES, { byteLength: null }) }), + ); + + expect(result).toEqual({ ok: true, value: uploaded("READY") }); + const part = captured[0]?.form.get("file") as File; + expect(new Uint8Array(await part.arrayBuffer())).toEqual(FILE_BYTES); + }); + + it("ignores a field the backend adds later instead of copying it", async () => { + answer({ + status: 201, + body: successEnvelope(uploaded("READY", { storageKey: "never-copied" })), + }); + + const result = await client().client.upload(upload()); + + expect(result).toEqual({ ok: true, value: uploaded("READY") }); + }); + + it("sends a UTF-8 filename and no key when the caller gives none", async () => { + const captured = answer({ + status: 201, + body: successEnvelope(uploaded("READY", { filename: "보고서.pdf" })), + }); + + const result = await client().client.upload( + upload({ filename: "보고서.pdf", idempotencyKey: undefined }), + ); + + expect(result.ok).toBe(true); + expect((captured[0]?.form.get("file") as File).name).toBe("보고서.pdf"); + expect(captured[0]?.headers.has("idempotency-key")).toBe(false); + }); + + it("uses the profile's Fetch policy, never the provider's", async () => { + const fetcher = vi.fn( + async (_input: RequestInfo | URL, _init?: RequestInit) => + new Response(JSON.stringify(successEnvelope(uploaded("READY"))), { + status: 201, + headers: { "content-type": "application/json" }, + }), + ); + + const result = await client({ + fetcher: fetcher as unknown as typeof fetch, + }).client.upload(upload({ filename: 'a"b\r\nc.pdf' })); + + expect(result.ok).toBe(true); + const [url, init] = fetcher.mock.calls[0] ?? []; + expect(url).toBe(UPLOAD_URL); + expect(init).toMatchObject({ + method: "POST", + credentials: "same-origin", + redirect: "error", + referrerPolicy: "no-referrer", + cache: "no-store", + }); + const head = new TextDecoder().decode( + (init?.body as Uint8Array).subarray(0, 200), + ); + // The HTML form encoder's escaping, so the part header cannot be split. + expect(head).toContain('filename="a%22b%0D%0Ac.pdf"'); + }); +}); + +describe("Fileserver multipart upload — answers that do not match the contract", () => { + it.each([ + ["201 with a state that is not READY", 201, successEnvelope(uploaded("VERIFYING")), "SCHEMA_MISMATCH"], + ["202 with READY", 202, successEnvelope(uploaded("READY")), "SCHEMA_MISMATCH"], + ["a size other than the bytes sent", 201, successEnvelope(uploaded("READY", { size: 1 })), "SCHEMA_MISMATCH"], + ["the DTO without its Envelope", 201, uploaded("READY"), "ENVELOPE_MISMATCH"], + ] as const)("%s is a created file the client cannot read", async (_label, status, body, kind) => { + answer({ status, body }); + + const result = await client().client.upload(upload()); + + // Created, so the user must not upload it again; the id is not known. + expect(result).toMatchObject({ + ok: false, + error: { kind, effect: "APPLIED_CONFIRMED", retryable: false, httpStatus: status }, + }); + }); + + it("reads a gateway 502 without an Envelope as a server outage that may have applied", async () => { + server.use( + http.post(UPLOAD_URL, () => + new HttpResponse("bad gateway", { + status: 502, + headers: { "content-type": "text/html" }, + }), + ), + ); + + const result = await client().client.upload(upload()); + + expect(result).toMatchObject({ + ok: false, + error: { kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", retryable: false }, + }); + }); + + it("refuses a response body above maxResponseBytes", async () => { + answer({ + status: 201, + body: successEnvelope(uploaded("READY", { filename: "x".repeat(900) })), + }); + + const result = await client({ maxResponseBytes: 256 }).client.upload(upload()); + + expect(result).toMatchObject({ + ok: false, + error: { kind: "RESPONSE_BODY_LIMIT", effect: "APPLIED_CONFIRMED" }, + }); + }); +}); + +describe("Fileserver multipart upload — Envelope failures", () => { + it.each([ + { status: 400, code: "IDEMPOTENCY_KEY_INVALID", category: "VALIDATION", retryable: false, kind: "UNKNOWN_CLIENT_FAILURE", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 401, code: "UNAUTHENTICATED", category: "AUTH", retryable: false, kind: "AUTH_REQUIRED", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 403, code: "ACCESS_DENIED", category: "AUTHZ", retryable: false, kind: "FORBIDDEN", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 413, code: "FILE_TOO_LARGE", category: "VALIDATION", retryable: false, kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 413, code: "QUOTA_EXCEEDED", category: "CONFLICT", retryable: false, kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 415, code: "UNSUPPORTED_MEDIA_TYPE", category: "VALIDATION", retryable: false, kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 422, code: "MALWARE_DETECTED", category: "DATA_INTEGRITY", retryable: false, kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 422, code: "IDEMPOTENT_REQUEST_MISMATCH", category: "VALIDATION", retryable: false, kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 500, code: "PARTIAL_WRITE", category: "TRANSIENT_DEPENDENCY", retryable: false, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: false }, + { status: 500, code: "AMBIGUOUS_COMPLETION", category: "DATA_INTEGRITY", retryable: false, details: { ambiguous: true, reconciliationRequired: true }, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, + { status: 500, code: "INTERNAL_ERROR", category: "INTERNAL", retryable: false, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, + { status: 503, code: "STORAGE_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: true }, + { status: 503, code: "STORAGE_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, details: { ambiguous: true }, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, + { status: 503, code: "IDEMPOTENCY_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: true }, + { status: 503, code: "IDEMPOTENCY_COMPLETION_UNKNOWN", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, + { status: 507, code: "STORAGE_FULL", category: "TRANSIENT_DEPENDENCY", retryable: false, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: false }, + ])( + "$status $code → $kind, $effect, retryable $clientRetryable", + async ({ status, code, category, retryable, details, kind, effect, clientRetryable }) => { + answer({ status, body: failureEnvelope(code, category, retryable, details) }); + + const result = await client().client.upload(upload()); + + expect(result).toMatchObject({ + ok: false, + error: { + kind, + code, + httpStatus: status, + effect, + retryable: clientRetryable, + operationId: "FILESERVER_UPLOAD", + }, + }); + }, + ); + + it("409 IDEMPOTENT_IN_FLIGHT keeps the server's wait and asks for the same key", async () => { + const captured = answer( + { + status: 409, + body: failureEnvelope("IDEMPOTENT_IN_FLIGHT", "CONFLICT", true), + headers: { "Retry-After": "2" }, + }, + { status: 201, body: successEnvelope(uploaded("READY")) }, + ); + const { client: uploader } = client(); + + const inFlight = await uploader.upload(upload()); + expect(inFlight).toMatchObject({ + ok: false, + error: { + kind: "CONFLICT", + code: "IDEMPOTENT_IN_FLIGHT", + effect: "MAYBE_APPLIED", + // Not a fresh retry: the caller resends the same request on purpose. + retryable: false, + retryAfterMs: 2_000, + }, + }); + // The client never resends on its own. + expect(captured).toHaveLength(1); + + const resent = await uploader.upload(upload()); + expect(resent).toEqual({ ok: true, value: uploaded("READY") }); + expect(captured.map(({ headers }) => headers.get("idempotency-key"))).toEqual([ + "upload-key-01", + "upload-key-01", + ]); + }); + + it.each([ + { retryAfter: "3", retryable: true, retryAfterMs: 3_000 }, + // 2026-11-03 01-02: past the ceiling, neither the wait nor an immediate retry. + { retryAfter: "45", retryable: false, retryAfterMs: undefined }, + ])( + "429 TRANSFER_ADMISSION_REJECTED with Retry-After $retryAfter", + async ({ retryAfter, retryable, retryAfterMs }) => { + answer({ + status: 429, + body: failureEnvelope("TRANSFER_ADMISSION_REJECTED", "RATE_LIMIT", true), + headers: { "Retry-After": retryAfter }, + }); + + const result = await client().client.upload(upload()); + + expect(result).toMatchObject({ + ok: false, + error: { kind: "RATE_LIMITED", effect: "NOT_APPLIED", retryable }, + }); + expect(result.ok ? undefined : result.error.retryAfterMs).toBe(retryAfterMs); + }, + ); +}); + +describe("Fileserver multipart upload — unknown results", () => { + it("a network failure after sending is MAYBE_APPLIED, and the resend keeps the key", async () => { + const captured = answer("NETWORK_ERROR", { + status: 201, + body: successEnvelope(uploaded("READY")), + }); + const { client: uploader } = client(); + + const lost = await uploader.upload(upload()); + expect(lost).toMatchObject({ + ok: false, + error: { kind: "NETWORK_UNREACHABLE", effect: "MAYBE_APPLIED", retryable: false }, + }); + + const resent = await uploader.upload(upload()); + expect(resent).toEqual({ ok: true, value: uploaded("READY") }); + expect(captured.map(({ headers }) => headers.get("idempotency-key"))).toEqual([ + "upload-key-01", + "upload-key-01", + ]); + }); + + it("ends at the deadline as REQUEST_TIMEOUT that may have applied", async () => { + server.use( + http.post(UPLOAD_URL, async () => { + await delay("infinite"); + return HttpResponse.json({}); + }), + ); + + const result = await client({ + timeoutMs: 30, + minTransferBytesPerSecond: 1_000_000_000, + }).client.upload(upload()); + + expect(result).toMatchObject({ + ok: false, + error: { kind: "REQUEST_TIMEOUT", effect: "MAYBE_APPLIED", retryable: false }, + }); + }); + + it("a caller abort after sending may have applied; before sending it did not", async () => { + const controller = new AbortController(); + let arrived: () => void = () => {}; + const requestArrived = new Promise((resolve) => { + arrived = resolve; + }); + server.use( + http.post(UPLOAD_URL, async () => { + arrived(); + await delay("infinite"); + return HttpResponse.json({}); + }), + ); + const { client: uploader } = client(); + + const pending = uploader.upload(upload({ signal: controller.signal })); + await requestArrived; + controller.abort(); + expect(await pending).toMatchObject({ + ok: false, + error: { kind: "REQUEST_ABORTED", effect: "MAYBE_APPLIED" }, + }); + + const fetcher = vi.fn(); + const aborted = await client({ + fetcher: fetcher as unknown as typeof fetch, + }).client.upload(upload({ signal: controller.signal })); + expect(aborted).toMatchObject({ + ok: false, + error: { kind: "REQUEST_ABORTED", effect: "NOT_STARTED" }, + }); + expect(fetcher).not.toHaveBeenCalled(); + }); +}); + +describe("Fileserver multipart upload — refused before sending", () => { + const unsent = async ( + overrides: Partial, + request: Readonly>, + ) => { + const fetcher = vi.fn(); + const result = await client({ + fetcher: fetcher as unknown as typeof fetch, + ...overrides, + }).client.upload(upload(request)); + expect(fetcher).not.toHaveBeenCalled(); + return result; + }; + + it.each([ + ["a declared size above maxFileBytes", { source: byteSource(new Uint8Array(2_000)) }, "VALIDATION_REJECTED", "FILE_TOO_LARGE"], + ["an undeclared size that grows past maxFileBytes", { source: byteSource(new Uint8Array(2_000), { byteLength: null, chunkBytes: 512 }) }, "VALIDATION_REJECTED", "FILE_TOO_LARGE"], + ["a file that shrank after selection", { source: byteSource(FILE_BYTES, { byteLength: FILE_BYTES.byteLength + 1 }) }, "VALIDATION_REJECTED", "FILE_NOT_READABLE"], + ["a file that grew after selection", { source: byteSource(FILE_BYTES, { byteLength: FILE_BYTES.byteLength - 1 }) }, "VALIDATION_REJECTED", "FILE_NOT_READABLE"], + ["a key outside the backend's key grammar", { idempotencyKey: "has space" }, "UNKNOWN_CLIENT_FAILURE", "FILESERVER_UPLOAD_INPUT_INVALID"], + ["a media type that is not a type/subtype", { mediaType: "pdf" }, "UNKNOWN_CLIENT_FAILURE", "FILESERVER_UPLOAD_INPUT_INVALID"], + ] as const)("%s", async (_label, request, kind, code) => { + expect(await unsent({}, request)).toMatchObject({ + ok: false, + error: { kind, code, effect: "NOT_STARTED" }, + }); + }); + + it("a source that fails mid-stream is not readable", async () => { + const source: FileByteSource = { + byteLength: 6, + async *stream() { + yield { ok: true as const, value: new Uint8Array(3) }; + yield { + ok: false as const, + error: { + code: "NOT_READABLE", + operation: "FILE_READ", + retryable: false, + recovery: "REOPEN", + }, + }; + }, + }; + expect(await unsent({}, { source })).toMatchObject({ + ok: false, + error: { kind: "VALIDATION_REJECTED", code: "FILE_NOT_READABLE", effect: "NOT_STARTED" }, + }); + }); + + it.each([ + ["no session", { kind: "UNAUTHENTICATED" }, "AUTH_REQUIRED", "UNAUTHENTICATED"], + ["a header the profile does not allow", { kind: "READY", headers: { authorization: "Bearer t" } }, "AUTH_INTEGRATION_FAILURE", "CREDENTIAL_HEADER_NOT_ALLOWED"], + ["the profile's required header missing", { kind: "READY", headers: {} }, "AUTH_INTEGRATION_FAILURE", "MISSING_REQUIRED_CREDENTIAL_HEADER"], + ["a session change in progress", { kind: "SCOPE_FENCED" }, "SCOPE_GENERATION_CHANGED", "SCOPE_FENCED"], + ] as const)("credentials: %s", async (_label, outcome, kind, code) => { + const result = await unsent( + { attachCredentials: () => outcome as CredentialPatchOutcome }, + {}, + ); + expect(result).toMatchObject({ + ok: false, + error: { kind, code, effect: "NOT_STARTED" }, + }); + }); + + it.each([ + ["a base URL whose path does not end in a slash", { baseUrl: "https://api.test/api" }], + ["no maxFileBytes", { maxFileBytes: undefined as unknown as number }], + ["a non-http base URL", { baseUrl: "file:///tmp/" }], + ])("refuses to compose with %s", (_label, overrides) => { + expect(() => client(overrides)).toThrow(TypeError); + }); +}); diff --git a/tests/unit/resumable-upload-fetch-transport.test.ts b/tests/unit/resumable-upload-fetch-transport.test.ts index 869e9752..add1791e 100644 --- a/tests/unit/resumable-upload-fetch-transport.test.ts +++ b/tests/unit/resumable-upload-fetch-transport.test.ts @@ -319,6 +319,33 @@ describe("resumable upload fetch transport", () => { expect(cancel).toHaveBeenCalledTimes(1); }); + // 2026-11-03 01-03 (N17). Without a usable wait the transport does not + // invite a retry (presigned-transfer-and-image-cdn.md, Retry-After). + it.each }>>([ + { label: "no Retry-After", headers: {} }, + { label: "Retry-After past the ceiling", headers: { "retry-after": "4" } }, + ])("classifies a 429 with $label as not retryable", async ({ headers }) => { + const fetcher = vi.fn(async () => + responseAt(ENDPOINTS.GET_STATUS, null, { status: 429, headers }), + ) as unknown as typeof fetch; + + const result = await createTransport(fetcher).execute({ + operation: "GET_STATUS", + body: {}, + signal: activeSignal, + }); + + expect(result).toEqual({ + ok: false, + error: { + code: "UNAVAILABLE", + operation: "UPLOAD_RECONCILE", + retryable: false, + recovery: "RESUME", + }, + }); + }); + it.each([500, 599])( "classifies HTTP %s as retryable; runtime attempt limits remain authoritative", async (status) => { diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index 14f069ae..35959762 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -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"; @@ -328,13 +330,17 @@ describe("issuance refusal versus PUT refusal (0929/01-01)", () => { }); describe("part-stage Retry-After (2026-11-01 01-01)", () => { + // 2026-11-03 01-03 (N2). A 503 carries the server's Retry-After as a 429 + // does (`statusFailure` in presigned/http-common.ts). const stages = [ - { stage: "BFF issuance", issueStatuses: [429], putStatuses: [] }, - { stage: "object-store PUT", issueStatuses: [], putStatuses: [429] }, + { stage: "BFF issuance", status: 429, issueStatuses: [429], putStatuses: [] }, + { stage: "object-store PUT", status: 429, issueStatuses: [], putStatuses: [429] }, + { stage: "BFF issuance", status: 503, issueStatuses: [503], putStatuses: [] }, + { stage: "object-store PUT", status: 503, issueStatuses: [], putStatuses: [503] }, ] as const; it.each(stages)( - "waits the server's Retry-After before retrying a $stage 429", + "waits the server's Retry-After before retrying a $stage $status", async ({ issueStatuses, putStatuses }) => { const real = presignedRuntime(putStatuses, undefined, { issueStatuses, @@ -353,7 +359,7 @@ describe("part-stage Retry-After (2026-11-01 01-01)", () => { ); it.each(stages)( - "does not retry a $stage 429 whose Retry-After exceeds maxRetryAfterMs", + "does not retry a $stage $status whose Retry-After exceeds maxRetryAfterMs", async ({ issueStatuses, putStatuses }) => { const real = presignedRuntime(putStatuses, undefined, { issueStatuses, @@ -365,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); @@ -375,9 +388,86 @@ 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: "UPLOAD_SESSION" | "UPLOAD_PART" | "UPLOAD_COMPLETE", + operation: + | "UPLOAD_SESSION" + | "UPLOAD_PART" + | "UPLOAD_COMPLETE" + | "UPLOAD_ABORT", ) => browserDataFailure("UNAVAILABLE", operation, { retryable: true, @@ -531,6 +621,49 @@ describe("resumable upload idempotency keys (01-04)", () => { complete.mock.calls[0]?.[0].idempotencyKey, ); }); + + // 2026-11-03 01-03 (N10). The same key is how the server recognises an + // abort whose answer was lost as the same abort. + it("retries abort with the same key, within one abort() and from the next", async () => { + const harness = createControlHarness(); + const abort = vi.fn( + async ( + _input: Parameters[0], + ): ReturnType => + abort.mock.calls.length <= 2 + ? unavailable("UPLOAD_ABORT") + : browserDataSuccess({ state: "ABORTED" as const }), + ); + harness.control.abort = abort; + const checkpoints = new MemoryCheckpointStore(); + const runtime = createResumableUploadRuntime({ + controlPlane: harness.control, + // Every PUT fails, so upload() leaves an ACTIVE checkpoint to abort. + partExecutor: { uploadPart: async () => unavailable("UPLOAD_PART") }, + checkpoints, + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 1 }), + now: () => 1_000, + sleep: async () => {}, + }); + const key = "upload_key_abort_retry"; + expect((await runtime.upload(request(key))).ok).toBe(false); + + // Two attempts inside the first abort() both fail; the next abort() wins. + const failed = await runtime.abort({ uploadKey: key, signal: activeSignal }); + expect(failed).toMatchObject({ + ok: false, + error: { operation: "UPLOAD_ABORT" }, + }); + const retried = await runtime.abort({ uploadKey: key, signal: activeSignal }); + + expect(retried).toEqual({ ok: true, value: { state: "ABORTED" } }); + expect(abort).toHaveBeenCalledTimes(3); + const keys = abort.mock.calls.map(([input]) => input.idempotencyKey); + expect(keys[0]).toMatch(/\S/u); + expect(new Set(keys).size).toBe(1); + }); }); describe("resumable upload completed-result reporting (01-02)", () => { @@ -618,6 +751,56 @@ describe("resumable upload completed-result reporting (01-02)", () => { expect(checkpoints.rows.has(key)).toBe(false); }); + // 0929/01-02 (2026-11-03 리뷰 2절). The reconcile path finds the lost + // complete applied; a failed local cleanup must not cost the caller the + // resourceId, exactly as on the complete path above. + it("reports the reconciled resource even when the local checkpoint cleanup fails", async () => { + const harness = committingHarness("LOST"); + const checkpoints = new MemoryCheckpointStore(); + const remove = checkpoints.remove.bind(checkpoints); + let failRemove = false; + checkpoints.remove = async (input) => + failRemove + ? browserDataFailure("UNAVAILABLE", "UPLOAD_RECONCILE", { + retryable: true, + recovery: "RESUME", + }) + : await remove(input); + const runtime = createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: executorFor(harness), + checkpoints, + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 0 }), + now: () => 1_000, + sleep: async () => {}, + }); + const key = "upload_key_reconcile_cleanup_fails"; + expect((await runtime.upload(request(key))).ok).toBe(false); + + failRemove = true; + const reconciled = await runtime.upload(request(key)); + + expect(reconciled).toEqual({ + ok: true, + value: { + state: "QUARANTINED", + resourceId: "resource_01", + byteLength: 4, + replayed: true, + }, + }); + // The stale row is the next call's to clean up, with the same resource. + expect(checkpoints.rows.has(key)).toBe(true); + failRemove = false; + expect(await runtime.upload(request(key))).toMatchObject({ + ok: true, + value: { resourceId: "resource_01", replayed: true }, + }); + expect(checkpoints.rows.has(key)).toBe(false); + }); + it("returns the resourceId when abort() finds the lost complete already applied", async () => { const harness = committingHarness("LOST"); const checkpoints = new MemoryCheckpointStore(); @@ -1188,6 +1371,93 @@ describe("resume after a policy change (01-08)", () => { }); }); +/** + * 1101/01-02 (2026-11-03 리뷰 2절). A resumed FILE_BYTE_SOURCE upload reads + * the whole stream again, but hashes only the parts it still has to send, + * as the RANGE_READER path already does. The manifest hashes every part once. + */ +describe("resumed stream upload hashing (1101/01-02)", () => { + const PARTS = Array.from({ length: 8 }, (_, index) => + Uint8Array.from([1, 2, 3, 4], (offset) => index * 4 + offset), + ); + const FILE = Uint8Array.from(PARTS.flatMap((part) => [...part])); + + const streamSource = () => + Object.freeze({ + kind: "FILE_BYTE_SOURCE" as const, + bytes: Object.freeze({ + byteLength: FILE.byteLength, + async *stream() { + for (let offset = 0; offset < FILE.byteLength; offset += 5) { + yield browserDataSuccess(FILE.slice(offset, offset + 5)); + } + }, + }), + }); + + /** Counts SHA-256 digests whose input is exactly one part's bytes. */ + function countingCrypto() { + let partDigests = 0; + const isPart = (data: Uint8Array) => + PARTS.some( + (part) => + part.byteLength === data.byteLength && + part.every((byte, index) => byte === data[index]), + ); + const counting = { + subtle: { + async digest(algorithm: AlgorithmIdentifier, data: Uint8Array) { + if (isPart(data)) partDigests += 1; + return await crypto.subtle.digest(algorithm, data); + }, + }, + } as unknown as Crypto; + return { crypto: counting, partDigests: () => partDigests }; + } + + it("hashes only the two parts the server has not accepted", async () => { + const harness = createControlHarness(); + const checkpoints = new MemoryCheckpointStore(); + const key = "upload_key_stream_resume_hash"; + const partial = await createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: { + async uploadPart(input) { + return input.part.partNumber >= 7 + ? browserDataFailure("UNAVAILABLE", "UPLOAD_PART", { + recovery: "RESUME", + }) + : await executorFor(harness).uploadPart(input); + }, + }, + checkpoints, + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 0 }), + now: () => 1_000, + sleep: async () => {}, + }).upload({ ...request(key), source: streamSource() }); + expect(partial.ok).toBe(false); + expect(harness.accepted.size).toBe(6); + + const counted = countingCrypto(); + const resumed = await createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: executorFor(harness), + checkpoints, + mutationLock: noContentionLock, + crypto: counted.crypto, + policy: runtimePolicy({ maxRetries: 0 }), + now: () => 1_000, + sleep: async () => {}, + }).upload({ ...request(key), source: streamSource() }); + + expect(resumed).toMatchObject({ ok: true, value: { state: "QUARANTINED" } }); + // 8 for the manifest, 2 for the parts sent. The old order made it 16. + expect(counted.partDigests()).toBe(10); + }); +}); + describe("upload part observation (01-10)", () => { it("records a part that succeeded on its second attempt as one UPLOAD_PART", async () => { const observations: BrowserDataObservation[] = [];