From 6608fef4ba78c8acdcb8de2215af70798be910f7 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:07:43 +0900 Subject: [PATCH 1/4] =?UTF-8?q?fix(http):=20Fileserver=20202=20REJECTED?= =?UTF-8?q?=EB=A5=BC=20=ED=8C=8C=EC=9D=BC=20=EA=B1=B0=EC=A0=88=EB=A1=9C=20?= =?UTF-8?q?=EC=9D=BD=EA=B3=A0=20=EB=B9=88=20=ED=8C=8C=EC=9D=BC=EC=9D=80=20?= =?UTF-8?q?=EB=B3=B4=EB=82=B4=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고 READY가 아닌 state를 모두 202로 답한다(FileUploadController#created). 악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다 (FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의 첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일 하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH, APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는 안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드 문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기 검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다. 고른 방법(리뷰 01-01 최소 개선 방향 (가)): - schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패 VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다. 413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지 않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입 FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는 성공 값으로 나오지 않는다). - 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트) 보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는 이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다. - 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201 REJECTED는 여전히 SCHEMA_MISMATCH다. - MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED· REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분). - 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자 결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다. 버린 대안: - REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서 거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다. - 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는 그대로 SCHEMA_MISMATCH다. 위험·한계: - upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서 VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로 바뀐다. CHANGELOG [계약] 한 줄이 필요하다. - 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서 LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다. - 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은 백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다. - 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와 docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제 업로드 검증(미검증). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file, not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an undeclared size that turns out empty"(fetch를 부름)가 실패한다. Refs: 1105/01-01, 1103/01-01 --- docs/manual/02-decision-tables.md | 16 ++++-- src/adapters/http/fileserver-upload.ts | 45 ++++++++++++++-- tests/integration/fileserver-upload.test.ts | 59 +++++++++++++++++++-- 3 files changed, 105 insertions(+), 15 deletions(-) diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index e36381f1..95869c07 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -286,7 +286,8 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 → FileContentPort.openSource(ref) → FileByteSource → 기능 어댑터: upload({ source, filename, mediaType, idempotencyKey, signal }) → POST /v1/files (multipart, 파트 이름 file) - → 201 READY 또는 202 VERIFYING + 저장된 파일 정보(fileId, sha256 …) + → 201 READY 또는 202 VERIFYING·QUARANTINED + 저장된 파일 정보(fileId, sha256 …) + 202 REJECTED는 저장된 파일이 아니다 → 실패 FILE_REJECTED ``` - `FileByteSource`: 고른 파일의 바이트를 조각으로 읽는 값이다. `File`·`Blob`은 파일 어댑터 밖으로 나오지 않는다. @@ -308,13 +309,17 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **결과 읽기**: `upload()`는 `Result`를 돌려준다. -- 성공 `state`가 `READY`(201)면 바로 내려받을 수 있다. 그 밖(202 `VERIFYING` 등)은 서버가 아직 검사 중이다. +- 성공 `state`가 `READY`(201)면 바로 내려받을 수 있다. 202는 아직 내려받을 수 없다. 짝 백엔드는 업로드 요청 안에서 검증을 끝내고, `READY`가 아닌 state는 모두 202로 답한다. + - `VERIFYING`: 검증기가 나중에 다시 보자고 했다. 서버가 다시 검사하면 `READY`가 될 수 있다. + - `QUARANTINED`: 격리됐다. 이름·타입 불일치, 스크립트 같은 이유다. 관리자가 정하기 전까지 내려받을 수 없다. "검사 중"으로 보이면 화면이 끝나지 않는 대기가 된다. + - `REJECTED`: 검증기가 거절했다(악성 코드 말고 다른 이유). 저장된 파일이 아니므로 성공으로 돌려주지 않는다. 실패 `VALIDATION_REJECTED`, code `FILE_REJECTED`, `NOT_APPLIED`다. 사용자가 다른 파일을 골라야 한다. +- 빈 파일은 보내지 않는다. 짝 백엔드 기본 검증기가 빈 파일을 거절하기 때문이다. `VALIDATION_REJECTED`, code `FILE_EMPTY`, `NOT_STARTED`다. - 실패 `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로 고른다. +- `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다. - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. **주의 — 멱등 키**: 짝 백엔드(`bbe944bd`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). @@ -390,6 +395,7 @@ export const createAttachmentFeatureInput = defineFeatureAdapterContribution({ **틀리면** - 프로필의 필수 헤더가 없으면 `fetch`를 부르지 않고 `MISSING_REQUIRED_CREDENTIAL_HEADER`로 끝난다. -- 파일이 `maxFileBytes`보다 크면 읽기 전에 `FILE_TOO_LARGE`(`NOT_STARTED`)다. +- 파일이 `maxFileBytes`보다 크면 읽기 전에 `FILE_TOO_LARGE`(`NOT_STARTED`)다. 비어 있으면 `FILE_EMPTY`(`NOT_STARTED`)다. +- 202 응답을 모두 "검사 중"으로 보이면 `QUARANTINED` 파일의 화면이 끝나지 않는다. state마다 따로 보인다. - 백엔드가 Fileserver 응답 모양이나 code를 바꾸면 검사가 잡지 못한다. 실패 판정 표(`fileserver-upload.ts`의 `NOT_APPLIED_5XX_CODES`, `MAYBE_APPLIED_CODES`)는 백엔드 `bbe944bd` 기준이다. 백엔드 SHA가 바뀌면 같이 다시 본다. -- 테스트 예: `tests/integration/fileserver-upload.test.ts`(백엔드 계약대로 답하는 MSW). +- 테스트 예: `tests/integration/fileserver-upload.test.ts`(백엔드 코드가 답하는 대로 답하는 MSW. 백엔드 문서는 202 `VERIFYING`만 적는다). diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts index f3832d7e..4e833b0a 100644 --- a/src/adapters/http/fileserver-upload.ts +++ b/src/adapters/http/fileserver-upload.ts @@ -48,7 +48,8 @@ import type { AuthOperationContext } from "./http-execution-v3.ts"; * gives (`FileserverByteSource` is its shape), 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. + * declares a larger size is refused before reading, and an empty file is + * never sent. * * 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 @@ -59,6 +60,19 @@ import type { AuthOperationContext } from "./http-execution-v3.ts"; export type FileserverFileState = "READY" | "UPLOADED" | "VERIFYING" | "QUARANTINED"; +/** + * 1105/01-01. The states the backend answers `POST /v1/files` with. It + * verifies synchronously and answers 202 for every state but `READY` + * (`FileUploadController#created`), so a file its verifiers refused, for a + * reason other than malware, comes back as 202 `REJECTED`. That one is not a + * stored file: the client returns it as a `FILE_REJECTED` failure. + */ +type FileserverAnswerState = FileserverFileState | "REJECTED"; + +type FileserverAnswer = Readonly< + Omit & { state: FileserverAnswerState } +>; + /** * The bytes to send: structurally the browser-file-storage port's * `FileByteSource`, which a product passes as it is. Written here instead of @@ -75,7 +89,12 @@ export type FileserverByteSource = Readonly<{ /** 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. */ + /** + * `READY` with 201: readable now. With 202 the file is not readable: + * `VERIFYING` means a verifier asked to check again later, and `QUARANTINED` + * means it is held until an operator decides, so a screen must not wait for + * it as for a check in progress. + */ state: FileserverFileState; filename: string; mediaType: string; @@ -191,7 +210,7 @@ export function createFileserverUploadClient( const uploadedFileSchema = z .object({ fileId: z.string().regex(UUID), - state: z.enum(["READY", "UPLOADED", "VERIFYING", "QUARANTINED"]), + state: z.enum(["READY", "UPLOADED", "VERIFYING", "QUARANTINED", "REJECTED"]), 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), @@ -426,6 +445,11 @@ async function readMultipartBody( // The server's code for the same refusal, so a feature handles one code. return failure("VALIDATION_REJECTED", "FILE_TOO_LARGE", notSent); } + // 1105/01-01. The backend's default verifier chain rejects empty content + // first (`LengthVerifier`), and that answer is a 202 `REJECTED` with no + // reason. Refused here instead, under a code that says why. + const empty = () => failure("VALIDATION_REJECTED", "FILE_EMPTY", notSent); + if (declared === 0) return empty(); const random = new Uint8Array(16); crypto.getRandomValues(random); const boundary = `----FileserverUpload${[...random] @@ -485,6 +509,7 @@ async function readMultipartBody( return failure("REQUEST_ABORTED", "REQUEST_ABORTED", notSent); } if (declared !== null && fileBytes !== declared) return changed(); + if (fileBytes === 0) return empty(); let bytes: Uint8Array; if (sized) { bytes = sized; @@ -564,7 +589,7 @@ async function readAnswer( response: Response, attempt: AbortableOperation, settings: Settings, - uploadedFileSchema: z.ZodType, + uploadedFileSchema: z.ZodType, sentBytes: number, ): Promise> { const status = response.status; @@ -629,9 +654,19 @@ async function readAnswer( ) { return unreadable("SCHEMA_MISMATCH", "UPLOADED_FILE_INVALID"); } + const { state, ...file } = parsed.data; + if (state === "REJECTED") { + // 1105/01-01. The file is the user's to replace, as with a 413, 415 or + // 422 refusal. The backend keeps the record unpublished and schedules + // its bytes for removal, so nothing usable was stored. + return failure("VALIDATION_REJECTED", "FILE_REJECTED", { + httpStatus: status, + effect: "NOT_APPLIED", + }); + } return Object.freeze({ ok: true as const, - value: Object.freeze({ ...parsed.data }), + value: Object.freeze({ ...file, state }), }); } if (status < 400) return unreadable("ENVELOPE_MISMATCH", "STATUS_UNEXPECTED"); diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index ec5bd27b..79b6bd4c 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -12,11 +12,22 @@ 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`. + * as clean-architecture-backend-template `45d2a478` (the pin) answers it in + * code, not only as its docs/fileserver/http-contract.md lists it. + * + * 1105/01-01. The document lists 202 VERIFYING alone. The code verifies the + * upload synchronously and answers 201 for `READY` and 202 for every other + * state (`FileUploadController#created`): `VERIFYING` (a verifier asked to + * retry), `QUARANTINED` and `REJECTED` (a refusal other than malware, + * `FinalizeUploadApplicationUseCase#applyNonAcceptVerdict`). The default + * verifier chain rejects an empty file that way (`LengthVerifier`). A record + * not yet published reports `application/octet-stream` (`FileRecord#toDescriptor`). + * + * Failure bodies, `details.ambiguous` and `Retry-After` follow the Fileserver + * handler; Envelope keys and the idempotency answers follow + * docs/web/http-contract.md §1–§2 (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"; @@ -188,6 +199,40 @@ describe("Fileserver multipart upload — success", () => { expect(result).toEqual({ ok: true, value: uploaded("VERIFYING") }); }); + it("reads 202 QUARANTINED as a stored file held until an operator decides", async () => { + const held = uploaded("QUARANTINED", { mediaType: "application/octet-stream" }); + answer({ status: 202, body: successEnvelope(held) }); + + const result = await client().client.upload(upload()); + + expect(result).toEqual({ ok: true, value: held }); + }); + + it("reads 202 REJECTED as a refused file, not as a broken answer", async () => { + // 1105/01-01. A verifier refused the file for a reason other than malware. + answer({ + status: 202, + body: successEnvelope( + uploaded("REJECTED", { mediaType: "application/octet-stream" }), + ), + }); + + const result = await client().client.upload(upload()); + + expect(result).toEqual({ + ok: false, + error: expect.objectContaining({ + kind: "VALIDATION_REJECTED", + code: "FILE_REJECTED", + httpStatus: 202, + effect: "NOT_APPLIED", + retryable: false, + action: "none", + operationId: "FILESERVER_UPLOAD", + }), + }); + }); + it("sends a source whose size is not declared up front", async () => { const captured = answer({ status: 201, body: successEnvelope(uploaded("READY")) }); @@ -261,6 +306,7 @@ 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"], + ["201 with REJECTED", 201, successEnvelope(uploaded("REJECTED")), "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) => { @@ -497,6 +543,9 @@ describe("Fileserver multipart upload — refused before sending", () => { it.each([ ["a declared size above maxFileBytes", { source: byteSource(new Uint8Array(2_000)) }, "VALIDATION_REJECTED", "FILE_TOO_LARGE"], + // 1105/01-01. The backend's default verifier chain rejects these. + ["an empty file", { source: byteSource(new Uint8Array(0)) }, "VALIDATION_REJECTED", "FILE_EMPTY"], + ["an undeclared size that turns out empty", { source: byteSource(new Uint8Array(0), { byteLength: null }) }, "VALIDATION_REJECTED", "FILE_EMPTY"], ["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"], From 471b001c409793ef79466dd0a1a87683b8179f7a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:11:17 +0900 Subject: [PATCH 2/4] =?UTF-8?q?fix(http):=20Fileserver=20504=20TRANSFER=5F?= =?UTF-8?q?TIMEOUT=EB=A5=BC=20=EA=B2=B0=EA=B3=BC=20=EB=B6=88=EB=AA=85?= =?UTF-8?q?=EC=9C=BC=EB=A1=9C=20=EC=9D=BD=EA=B3=A0=20=EB=A9=B1=EB=93=B1=20?= =?UTF-8?q?=EC=9D=91=EB=8B=B5=EC=9D=80=20V3=20=ED=91=9C=EB=A5=BC=20?= =?UTF-8?q?=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true, retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시 올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다. 백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가 await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤 TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일 복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에 파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면 같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503 IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와 매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를 MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을 말하지 않는다. pin 대조도 이 표를 보지 않는다. 고른 방법: - TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로 MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로 만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에 내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE, STORAGE_FULL)이다. - 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE, MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로 판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다. 503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400 IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로 NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔 MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다. - pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의 행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는 tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을 옮기면 두 reader가 함께 다시 대조된다. - Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약 문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다. - client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로 맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절). 버린 대안: - client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과 불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일 업로드에서는 use case가 취소하므로 근거도 없다. - TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과 pin 밖 상태가 남는다. 위험·한계: - 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503 IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다. - 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이 보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이 시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true, retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에 interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지 docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을 되돌린다(재검토 조건). - 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다 (UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성 executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다. - 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md 추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은 같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면 충돌한다. 07-01과 함께 넣는 편이 낫다. - Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은 것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503 IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false", "504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false", "504 TRANSFER_TIMEOUT is an unknown result the client does not offer to retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as the V3 Envelope table does"가 실패한다. Refs: 1105/01-02 --- .../backend-api-and-server-state-contract.md | 16 +++++ docs/manual/02-decision-tables.md | 11 +-- src/adapters/http/fileserver-upload.ts | 68 ++++++++++++------ tests/integration/fileserver-upload.test.ts | 70 ++++++++++++++++++- 4 files changed, 140 insertions(+), 25 deletions(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 2e2fe977..e3a317fc 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -330,6 +330,22 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 `RepoStatsAclMapper.java`, `DomainExceptionHandler.java`: `clean-architecture-backend-template/src/sample-portfolio/` - `FileserverErrorCode.java`, `FinalizeUploadApplicationUseCase.java`: `clean-architecture-backend-template/src/application-fileserver/` +- Fileserver 한 번 업로드(`POST /v1/files`)는 V3 실행기가 아니라 + `src/adapters/http/fileserver-upload.ts`의 client가 부른다(1105/01-02). 이 client는 + 위 표의 fileserver 행과 달리 4xx를 `NOT_APPLIED`로 본다. 업로드 use case + (`UploadFileApplicationUseCase.java`)가 모호하지 않은 실패에서 업로드를 취소하므로 + `READY` 파일이 남지 않는다. `MALWARE_DETECTED`처럼 레코드를 `REJECTED`로 쓴 뒤 + 던지는 code도 그 레코드는 공개되지 않는다. 위 행은 fileserver 응답을 V3 실행기로 + 읽을 때의 판정이다. + - 멱등성 code와 V3 표(`REFUSED_BEFORE_WRITE`, `MAYBE_APPLIED_ANSWERS`)에 있는 답은 + client도 V3 표로 판정한다. 그래서 503 `IDEMPOTENCY_UNAVAILABLE`은 `MAYBE_APPLIED`다. + `tests/integration/fileserver-upload.test.ts`가 복사한 답 표의 행마다 둘이 같은지 본다. + - 5xx는 작업 스레드가 게시 전에 내는 code 넷(`PARTIAL_WRITE`, + `ATOMIC_PUBLISH_UNSUPPORTED`, `STORAGE_UNAVAILABLE`, `STORAGE_FULL`)만 + `NOT_APPLIED`다. 504 `TRANSFER_TIMEOUT`은 `MAYBE_APPLIED`다. 대기 스레드가 + 작업 단계와 상관없이 내고, 게시 rename과 `READY` 커밋은 interrupt로 멈추지 않는다 + (`BlockingTransferExecutor.java`, `FinalizeUploadApplicationUseCase.java`). 백엔드는 + 이 code를 `retryable: true`, `ambiguous` 없이 보낸다. 이 차이는 백엔드 결정으로 남는다. **operation이 선언하는 쓰기 전 거절**(1103/03-01): 업무 code는 엔드포인트마다 단계가 달라 위 표에 "쓰기 뒤 가능"으로 둔다. 쓰기 전에만 그 code를 내는 엔드포인트를 diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 95869c07..77f5d1ad 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -316,13 +316,15 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 빈 파일은 보내지 않는다. 짝 백엔드 기본 검증기가 빈 파일을 거절하기 때문이다. `VALIDATION_REJECTED`, code `FILE_EMPTY`, `NOT_STARTED`다. - 실패 `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`를 쓴다. + - `NOT_APPLIED`: 서버가 거절했고 파일은 없다. Fileserver는 모호하지 않은 실패에서 업로드를 취소한다. 아래 `MAYBE_APPLIED` 경우를 뺀 4xx와, 5xx 중 작업 스레드가 게시 전에 내는 code 넷(`PARTIAL_WRITE`, `ATOMIC_PUBLISH_UNSUPPORTED`, `STORAGE_UNAVAILABLE`, `STORAGE_FULL`)이다. + - `MAYBE_APPLIED`: 올라갔을 수도 있다. 응답을 잃음, 시간 초과, `details.ambiguous: true`, 그 밖의 5xx다. 504 `TRANSFER_TIMEOUT`도 여기 든다. 백엔드는 대기 시간이 지나면 작업이 어느 단계에 있든 이 code를 내고, 작업은 그 뒤에 끝나 `READY`가 될 수 있다. 다시 보낼 때는 같은 `idempotencyKey`를 쓴다. + - 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다. - `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다. - `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다. - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. +- `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. -**주의 — 멱등 키**: 짝 백엔드(`bbe944bd`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). +**주의 — 멱등 키**: 짝 백엔드(`45d2a478`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). - 그래서 `MAYBE_APPLIED` 뒤 다시 보내면 같은 파일이 두 개 생길 수 있다. - 같은 키 재전송이 중복을 막는 것은 배포가 업로드를 백엔드 멱등성 executor 뒤에 둘 때뿐이다. @@ -397,5 +399,6 @@ export const createAttachmentFeatureInput = defineFeatureAdapterContribution({ - 프로필의 필수 헤더가 없으면 `fetch`를 부르지 않고 `MISSING_REQUIRED_CREDENTIAL_HEADER`로 끝난다. - 파일이 `maxFileBytes`보다 크면 읽기 전에 `FILE_TOO_LARGE`(`NOT_STARTED`)다. 비어 있으면 `FILE_EMPTY`(`NOT_STARTED`)다. - 202 응답을 모두 "검사 중"으로 보이면 `QUARANTINED` 파일의 화면이 끝나지 않는다. state마다 따로 보인다. -- 백엔드가 Fileserver 응답 모양이나 code를 바꾸면 검사가 잡지 못한다. 실패 판정 표(`fileserver-upload.ts`의 `NOT_APPLIED_5XX_CODES`, `MAYBE_APPLIED_CODES`)는 백엔드 `bbe944bd` 기준이다. 백엔드 SHA가 바뀌면 같이 다시 본다. +- 멱등성·web 공통 응답의 판정은 V3 표를 그대로 쓴다. `tests/integration/fileserver-upload.test.ts`가 pin 옆에 복사한 백엔드 답 표(`config/contracts/backend-idempotency-answers.json`)의 행마다 client와 V3 표가 같은지 본다. pin을 옮기면 같이 다시 돈다. +- 백엔드가 Fileserver 응답 모양이나 Fileserver 자신의 code를 바꾸면 검사가 잡지 못한다. 그 표(`fileserver-upload.ts`의 `NOT_APPLIED_5XX_CODES`)는 백엔드 `45d2a478`(pin) 코드를 읽은 것이다. 백엔드 SHA가 바뀌면 `FileserverErrorCode`, `BlockingTransferExecutor`, 게시 경로를 같이 다시 본다. 4xx를 `NOT_APPLIED`로 보는 이유는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절에 있다. - 테스트 예: `tests/integration/fileserver-upload.test.ts`(백엔드 코드가 답하는 대로 답하는 MSW. 백엔드 문서는 202 `VERIFYING`만 적는다). diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts index 4e833b0a..2ef5465c 100644 --- a/src/adapters/http/fileserver-upload.ts +++ b/src/adapters/http/fileserver-upload.ts @@ -15,10 +15,13 @@ import { } from "../platform/abortable-operation.ts"; import { parseRetryAfterDelay } from "../platform/retry-after.ts"; import { + envelopeFailureEffect, envelopeFailureReading, gatewayFailureOr, + maybeAppliedAnswerRows, readFailureEnvelope, readSuccessEnvelope, + refusedBeforeWriteRows, type EnvelopeError, } from "./backend-envelope.ts"; import { @@ -35,7 +38,8 @@ 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 + * `45d2a478`, the commit config/contracts/backend-contract-pin.json pins; + * docs/fileserver/http-contract.md and its code; Envelope and idempotency in * docs/web/http-contract.md §1–§2). * * The paired backend removed presigned and direct multipart transfer on @@ -111,7 +115,7 @@ export type FileserverUploadRequest = Readonly<{ 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 + * the same key and never a new one. At `45d2a478` the backend runs * `POST /v1/files` without its idempotency executor, so the key protects * only a deployment that routes the upload through it. */ @@ -172,30 +176,49 @@ 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. + * its worker raises 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 worker + * raises before the file is published (`FileserverErrorCode`, + * `AtomicMoveContentPublisher`). Recheck the list when the pinned backend + * commit moves; contract §6.1 says why the 4xx reading differs from its + * fileserver row. + * + * 1105/01-02. 504 TRANSFER_TIMEOUT is not here. The waiting servlet thread + * raises it when `await-seconds` runs out, whatever stage the worker is in + * (`BlockingTransferExecutor`), and the interrupt that follows does not stop a + * publish rename or the READY commit. The file may still become READY, so a + * resend can store it twice. */ 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", -]); +/** + * 1105/01-02. The web contract's own answers (idempotency §2, and the other + * codes the V3 table lists) read as the V3 executor reads them, so the same + * backend code has one verdict in this repository. The idempotency codes are + * taken by prefix: one the table does not list yet stays MAYBE_APPLIED. + */ +function sharedAnswerEffect( + status: number, + error: EnvelopeError, +): "NOT_APPLIED" | "MAYBE_APPLIED" | undefined { + const listed = (rows: readonly Readonly<{ code: string; status: number }>[]) => + rows.some((row) => row.code === error.code && row.status === status); + if ( + !/^IDEMPOTEN(?:T|CY)_/u.test(error.code) && + !listed(refusedBeforeWriteRows()) && + !listed(maybeAppliedAnswerRows()) + ) { + return undefined; + } + return envelopeFailureEffect(status, error) ?? "MAYBE_APPLIED"; +} export function createFileserverUploadClient( dependencies: FileserverUploadClientDependencies, @@ -722,7 +745,10 @@ function envelopeFailure( }); } -/** See `NOT_APPLIED_5XX_CODES`. */ +/** + * In this order: an ambiguous answer, then the web contract's own answers + * (`sharedAnswerEffect`), then the Fileserver reading (`NOT_APPLIED_5XX_CODES`). + */ export function fileserverFailureEffect( status: number, error: EnvelopeError, @@ -733,7 +759,9 @@ export function fileserverFailureEffect( typeof details === "object" && !Array.isArray(details) && (details as Readonly>)["ambiguous"] === true; - if (ambiguous || MAYBE_APPLIED_CODES.has(error.code)) return "MAYBE_APPLIED"; + if (ambiguous || error.code === "AMBIGUOUS_COMPLETION") return "MAYBE_APPLIED"; + const shared = sharedAnswerEffect(status, error); + if (shared !== undefined) return shared; if (status >= 400 && status < 500) return "NOT_APPLIED"; return NOT_APPLIED_5XX_CODES.has(error.code) ? "NOT_APPLIED" : "MAYBE_APPLIED"; } diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index 79b6bd4c..c8f9aa86 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -1,8 +1,12 @@ +import { readFileSync } from "node:fs"; + import { delay, HttpResponse, http, type JsonBodyType } from "msw"; import { setupServer } from "msw/node"; import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest"; +import { z } from "zod"; import type { FileByteSource } from "../../src/application/ports/browser-file-storage/file.ts"; +import { envelopeFailureEffect } from "../../src/adapters/http/backend-envelope.ts"; import { createFileserverUploadClient, type CredentialPatchOutcome, @@ -369,9 +373,14 @@ describe("Fileserver multipart upload — Envelope failures", () => { { 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 }, + // 1105/01-02. As the V3 table reads it: only an unknown result keeps the key. + { status: 503, code: "IDEMPOTENCY_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, { 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 }, + // 1105/01-02. Raised by the waiting thread at any stage of the work, which + // may still publish the file: the backend's own retryable:true does not + // make a resend safe. + { status: 504, code: "TRANSFER_TIMEOUT", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, ])( "$status $code → $kind, $effect, retryable $clientRetryable", async ({ status, code, category, retryable, details, kind, effect, clientRetryable }) => { @@ -427,6 +436,28 @@ describe("Fileserver multipart upload — Envelope failures", () => { ]); }); + it("504 TRANSFER_TIMEOUT is an unknown result the client does not offer to retry", async () => { + // 1105/01-02. The backend sends Retry-After: 5 with it. + answer({ + status: 504, + body: failureEnvelope("TRANSFER_TIMEOUT", "TRANSIENT_DEPENDENCY", true), + headers: { "Retry-After": "5" }, + }); + + const result = await client().client.upload(upload()); + + expect(result).toMatchObject({ + ok: false, + error: { + kind: "SERVER_FAILURE", + code: "TRANSFER_TIMEOUT", + effect: "MAYBE_APPLIED", + retryable: false, + action: "contact-support", + }, + }); + }); + it.each([ { retryAfter: "3", retryable: true, retryAfterMs: 3_000 }, // 2026-11-03 01-02: past the ceiling, neither the wait nor an immediate retry. @@ -451,6 +482,43 @@ describe("Fileserver multipart upload — Envelope failures", () => { ); }); +/** + * 1105/01-02. The backend answer table copied next to the pin + * (config/contracts/backend-contract-pin.json) holds the V3 Envelope table in + * tests/unit/backend-contract-pin.test.ts. The same rows hold this client, so + * one backend code has one verdict and a pin move rechecks both readers. + */ +const PINNED_ANSWERS = (() => { + const pin = z + .object({ tables: z.object({ idempotencyAnswers: z.string().min(1) }) }) + .parse(JSON.parse(readFileSync("config/contracts/backend-contract-pin.json", "utf8"))); + return z + .object({ + answers: z + .array(z.object({ code: z.string().min(1), status: z.number().int() })) + .min(1), + }) + .parse(JSON.parse(readFileSync(pin.tables.idempotencyAnswers, "utf8"))).answers; +})(); + +describe("Fileserver multipart upload — the pinned backend answer table", () => { + it.each(PINNED_ANSWERS.map((row) => [`${row.status} ${row.code}`, row] as const))( + "reads %s as the V3 Envelope table does", + async (_label, row) => { + answer({ + status: row.status, + body: failureEnvelope(row.code, "TRANSIENT_DEPENDENCY", false), + }); + + const result = await client().client.upload(upload()); + + expect(result.ok ? undefined : result.error.effect).toBe( + envelopeFailureEffect(row.status, { code: row.code }), + ); + }, + ); +}); + 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", { From 8b92f45f5eefe85c92a58a3cd65fc7b2bd6b30b1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:12:19 +0900 Subject: [PATCH 3/4] =?UTF-8?q?fix(http):=20Fileserver=20=EC=97=85?= =?UTF-8?q?=EB=A1=9C=EB=93=9C=20=EC=8B=A4=ED=8C=A8=EC=97=90=20Envelope?= =?UTF-8?q?=EC=9D=98=20traceId=EB=A5=BC=20=EC=8B=A3=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고, V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를 서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다. 고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면 createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지 않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다. 위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패 (SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를 돌려주지 않아 traceId가 없다. V3도 같다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId "trace-1"이 없어 모두 실패한다. Refs: 1105/01-03 --- docs/manual/02-decision-tables.md | 1 + src/adapters/http/fileserver-upload.ts | 8 ++++++-- tests/integration/fileserver-upload.test.ts | 15 +++++++++++++++ 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 77f5d1ad..3571f427 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -321,6 +321,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다. - `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다. - `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다. +- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. - `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts index 2ef5465c..736392ed 100644 --- a/src/adapters/http/fileserver-upload.ts +++ b/src/adapters/http/fileserver-upload.ts @@ -695,15 +695,16 @@ async function readAnswer( 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); + return envelopeFailure(status, envelope, response, settings); } function envelopeFailure( status: number, - error: EnvelopeError, + envelope: Readonly<{ value: EnvelopeError; traceId?: string }>, response: Response, settings: Settings, ): Result { + const error = envelope.value; const effect = fileserverFailureEffect(status, error); const retryAfterMs = parseRetryAfterDelay( response.headers.get("retry-after"), @@ -731,6 +732,9 @@ function envelopeFailure( ...(reading.validationIssues === undefined ? {} : { validationIssues: reading.validationIssues }), + // 1105/01-03. The backend's `meta.traceId`, as the V3 executor carries it + // (1103/03-06), so support can find this upload in the server logs. + ...(envelope.traceId === undefined ? {} : { traceId: envelope.traceId }), }); // `retryable` in the Envelope is the server's decision for this answer and // can only narrow the client's. diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index c8f9aa86..41595697 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -397,11 +397,26 @@ describe("Fileserver multipart upload — Envelope failures", () => { effect, retryable: clientRetryable, operationId: "FILESERVER_UPLOAD", + // 1105/01-03. The Envelope's meta.traceId, as V3 carries it. + traceId: META.traceId, }, }); }, ); + it("carries no traceId when the failure Envelope has none", async () => { + const envelope = failureEnvelope("STORAGE_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true); + answer({ + status: 503, + body: { success: envelope.success, error: envelope.error, meta: { requestId: "req-1" } }, + }); + + const result = await client().client.upload(upload()); + + expect(result.ok).toBe(false); + expect(result.ok ? undefined : Object.hasOwn(result.error, "traceId")).toBe(false); + }); + it("409 IDEMPOTENT_IN_FLIGHT keeps the server's wait and asks for the same key", async () => { const captured = answer( { From f2f7dc4cdb4690dfbf3b16363ac68b83f313771f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:13:54 +0900 Subject: [PATCH 4/4] =?UTF-8?q?test(http):=20Fileserver=20client=EC=9D=98?= =?UTF-8?q?=205xx=C2=B7deadline=C2=B7=EC=9D=BD=EA=B8=B0=20=EC=A0=84=20?= =?UTF-8?q?=ED=81=AC=EA=B8=B0=20=EA=B1=B0=EC=A0=88=20=EA=B7=9C=EC=B9=99?= =?UTF-8?q?=EC=9D=84=20=EA=B3=A0=EC=A0=95=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: Fileserver client 규칙 셋을 바꿔도 통합 테스트 48건이 모두 통과했다(리뷰 변이 FS4·FS5·FS8 생존). - FS4: 5xx ATOMIC_PUBLISH_UNSUPPORTED를 NOT_APPLIED에서 빼도 표에 그 행이 없다. - FS5: deadline에서 바이트 비례 몫을 없애도 시간 초과 테스트는 작은 고정값만 본다. 큰 파일이 느린 망에서 기본 30초에 끊기는 회귀를 못 잡는다. - FS8: 선언 크기가 maxFileBytes보다 큰 파일을 읽기 전에 거절하지 않아도, 읽는 중 상한 검사가 같은 code를 내서 통과한다. 그 사이 선언 크기만큼 버퍼를 먼저 잡는다. 고른 방법(리뷰 01-04 최소 개선 방향): - Envelope 실패 표에 503 ATOMIC_PUBLISH_UNSUPPORTED → NOT_APPLIED 행을 더한다. 504 TRANSFER_TIMEOUT 행은 01-02 커밋이 MAYBE_APPLIED로 더했다. 두 방향(빼기·되넣기)이 모두 실패를 만든다. - 가짜 setTimeout과 주입한 fetcher·monotonicNow로, 기본 1초에 바이트당 1초를 더한 deadline 안에서 1.5초 뒤 온 답이 성공하는지, 자격 증명 owner가 받은 deadline이 1,000 + 바이트 수 × 1,000 ms인지 본다. 실제 시간에 기대지 않아 부하에 흔들리지 않는다. - 선언 크기 초과에서 stream()이 한 번도 불리지 않음을 본다. 버린 대안: MSW에 지연을 넣고 실제 시간으로 deadline을 재는 방법. 부하가 큰 desktop에서 흔들릴 수 있고, 시간 여유를 키우면 테스트가 느려진다. 위험·한계: 테스트만 더했다. 지금 코드는 의도대로라서 부모 src에서도 통과한다. 검출력은 변이로만 확인할 수 있다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED 없음(테스트 추가). 변이 셋이 각각 실패를 만들어야 한다: FS4' NOT_APPLIED_5XX_CODES에서 "ATOMIC_PUBLISH_UNSUPPORTED" 줄 삭제, FS5 timeoutMs 식의 Math.ceil(...) 몫을 0으로, FS8 readMultipartBody의 declared > maxFileBytes 거절 블록 삭제. Refs: 1105/01-04 --- tests/integration/fileserver-upload.test.ts | 63 +++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index 41595697..c4981fa0 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -372,6 +372,8 @@ describe("Fileserver multipart upload — Envelope failures", () => { { 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 }, + // 1105/01-04. The atomic move itself was refused: nothing was published. + { status: 503, code: "ATOMIC_PUBLISH_UNSUPPORTED", category: "PERMANENT_DEPENDENCY", retryable: false, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: false }, { status: 503, code: "STORAGE_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, details: { ambiguous: true }, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, // 1105/01-02. As the V3 table reads it: only an unknown result keeps the key. { status: 503, code: "IDEMPOTENCY_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, @@ -575,6 +577,53 @@ describe("Fileserver multipart upload — unknown results", () => { }); }); + it("adds the file's transfer allowance to the base deadline", async () => { + // 1105/01-04. At one byte per second the file earns one second per byte + // on top of the one-second base, so an answer after 1.5 s still counts. + // Without the allowance a large file on a slow uplink ends at the base. + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); + try { + let respond: (response: Response) => void = () => {}; + let sent: () => void = () => {}; + const requestSent = new Promise((resolve) => { + sent = resolve; + }); + const fetcher = vi.fn( + () => + new Promise((resolve) => { + respond = resolve; + sent(); + }), + ); + const { client: uploader, attachCredentials } = client({ + fetcher: fetcher as unknown as typeof fetch, + timeoutMs: 1_000, + minTransferBytesPerSecond: 1, + monotonicNow: () => 0, + }); + + const pending = uploader.upload(upload()); + await requestSent; + await vi.advanceTimersByTimeAsync(1_500); + respond( + new Response(JSON.stringify(successEnvelope(uploaded("READY"))), { + status: 201, + headers: { "content-type": "application/json" }, + }), + ); + + expect(await pending).toEqual({ ok: true, value: uploaded("READY") }); + expect(attachCredentials).toHaveBeenCalledWith( + expect.anything(), + expect.objectContaining({ + deadlineAtMonotonicMs: 1_000 + FILE_BYTES.byteLength * 1_000, + }), + ); + } finally { + vi.useRealTimers(); + } + }); + it("a caller abort after sending may have applied; before sending it did not", async () => { const controller = new AbortController(); let arrived: () => void = () => {}; @@ -641,6 +690,20 @@ describe("Fileserver multipart upload — refused before sending", () => { }); }); + it("refuses a declared size above maxFileBytes without reading a byte", async () => { + // 1105/01-04. Before the body buffer is sized from the declared length. + const stream = vi.fn(async function* () { + yield { ok: true as const, value: new Uint8Array(3) }; + }); + const source: FileByteSource = { byteLength: 2_000, stream }; + + expect(await unsent({}, { source })).toMatchObject({ + ok: false, + error: { kind: "VALIDATION_REJECTED", code: "FILE_TOO_LARGE", effect: "NOT_STARTED" }, + }); + expect(stream).not.toHaveBeenCalled(); + }); + it("a source that fails mid-stream is not readable", async () => { const source: FileByteSource = { byteLength: 6,