chore(review): 1105 업로드 client 조치 브랜치를 합친다
This commit is contained in:
@@ -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를 내는 엔드포인트를
|
||||
|
||||
@@ -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<FileserverUploadedFile, AppFailure>`를 돌려준다.
|
||||
|
||||
- 성공 `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`만 적는다).
|
||||
|
||||
@@ -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<FileserverUploadedFile, "state"> & { 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<string> = 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<string> = 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<ArrayBuffer>;
|
||||
if (sized) {
|
||||
bytes = sized;
|
||||
@@ -564,7 +612,7 @@ async function readAnswer(
|
||||
response: Response,
|
||||
attempt: AbortableOperation,
|
||||
settings: Settings,
|
||||
uploadedFileSchema: z.ZodType<FileserverUploadedFile>,
|
||||
uploadedFileSchema: z.ZodType<FileserverAnswer>,
|
||||
sentBytes: number,
|
||||
): Promise<Result<FileserverUploadedFile, AppFailure>> {
|
||||
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<never, AppFailure> {
|
||||
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<Record<string, unknown>>)["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";
|
||||
}
|
||||
|
||||
@@ -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<void>((resolve) => {
|
||||
sent = resolve;
|
||||
});
|
||||
const fetcher = vi.fn(
|
||||
() =>
|
||||
new Promise<Response>((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,
|
||||
|
||||
Reference in New Issue
Block a user