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 e36381f1..3571f427 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,16 +309,23 @@ 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`를 쓴다. + - `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로 고른다. +- `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`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. -**주의 — 멱등 키**: 짝 백엔드(`bbe944bd`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). +**주의 — 멱등 키**: 짝 백엔드(`45d2a478`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). - 그래서 `MAYBE_APPLIED` 뒤 다시 보내면 같은 파일이 두 개 생길 수 있다. - 같은 키 재전송이 중복을 막는 것은 배포가 업로드를 백엔드 멱등성 executor 뒤에 둘 때뿐이다. @@ -390,6 +398,8 @@ export const createAttachmentFeatureInput = defineFeatureAdapterContribution({ **틀리면** - 프로필의 필수 헤더가 없으면 `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). +- 파일이 `maxFileBytes`보다 크면 읽기 전에 `FILE_TOO_LARGE`(`NOT_STARTED`)다. 비어 있으면 `FILE_EMPTY`(`NOT_STARTED`)다. +- 202 응답을 모두 "검사 중"으로 보이면 `QUARANTINED` 파일의 화면이 끝나지 않는다. state마다 따로 보인다. +- 멱등성·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 f3832d7e..736392ed 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 @@ -48,7 +52,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 +64,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 +93,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; @@ -92,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. */ @@ -153,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, @@ -191,7 +233,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 +468,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 +532,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 +612,7 @@ async function readAnswer( response: Response, attempt: AbortableOperation, settings: Settings, - uploadedFileSchema: z.ZodType, + uploadedFileSchema: z.ZodType, sentBytes: number, ): Promise> { const status = response.status; @@ -629,23 +677,34 @@ 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"); 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"), @@ -673,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. @@ -687,7 +749,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, @@ -698,7 +763,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 ec5bd27b..c4981fa0 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, @@ -12,11 +16,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 +203,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 +310,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) => { @@ -322,10 +372,17 @@ 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 }, - { 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 }) => { @@ -342,11 +399,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( { @@ -381,6 +453,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. @@ -405,6 +499,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", { @@ -446,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 = () => {}; @@ -497,6 +675,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"], @@ -509,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,