merge: PR #25을 합친 검사 브랜치에 넣는다

This commit is contained in:
DongHyeonka
2026-11-13 07:21:13 +09:00
80 changed files with 1555 additions and 284 deletions
+3 -3
View File
@@ -1,8 +1,8 @@
# GraphQL leaf public API surface — every public top-level type in src/main/java.
# A public type in a single-jar leaf is reachable from every adopter's code, so
# additions are reviewed rather than discovered. `api` and `spi` are the intended
# external surface; the rest are candidates to become internal when this leaf is
# split into capability artifacts.
# additions are reviewed rather than discovered. `api` is the intended external
# surface; the rest are candidates to become internal when this leaf is split into
# capability artifacts.
# Update only after review with:
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
# types: 161
+42 -4
View File
@@ -9,7 +9,7 @@
|---|---|---|---|
| POST | `/v1/files` | `201` READY, `202` VERIFYING | multipart 단일 업로드 |
| POST | `/v1/files:raw` | `201`, `202` | 요청 본문 전체가 파일이다 |
| POST | `/v1/files:batch` | `200` | part별 결과를 순서대로 준다. 명시적으로 원자적이지 않다 |
| POST | `/v1/files:batch` | `200` | 공용 bulk envelope(`docs/web/http-contract.md` 1절). 명시적으로 원자적이지 않다 |
| GET | `/v1/files/{fileId}` | `200` | 공개 metadata. content key나 경로는 절대 주지 않는다 |
| GET | `/v1/files/{fileId}/content` | `200`, `206`, `304` | 다운로드 |
| HEAD | `/v1/files/{fileId}/content` | `200`, `304` | 같은 헤더, 본문 없음 |
@@ -76,7 +76,6 @@ servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고,
```json
{
"success": false,
"data": null,
"error": {
"code": "UPLOAD_OFFSET_MISMATCH",
"category": "CONFLICT",
@@ -97,8 +96,10 @@ servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고,
`ambiguous`는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
`retryable`은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객체(`code`, `category`, `message`,
`retryable`)를 담는다.
batch 업로드는 공용 bulk envelope다. 모든 part가 성공하면 `success: true`와 `results[]`(part마다 `clientPartId`,
`status`, `fileId`)다. 한 part라도 거부되면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`, `error.details[]`다.
`details[]` 항목은 part 순서의 `index`, `status`(`ok`·`error`), 성공한 part의 `id`(fileId), 거부된 part의 `code`와
category 고정 문구 `message`다. 부분 실패에서 part는 요청에 보낸 순서의 `index`로 짚는다(`clientPartId`는 전부 성공한 `results[]`에만 있다). 성공한 part는 되돌리지 않는다.
### Envelope 규칙의 프로토콜 예외
@@ -111,6 +112,43 @@ batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객
`409 application/problem+json`, `type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset`,
`expectedOffset`과 `providedOffset`. Envelope가 아닌 실패 본문은 이것 하나뿐이다.
## 오류 코드
`error.code`는 `FileserverErrorCode`(application-fileserver)가 정한다. 아래 표가 그 전부이고, client는 이 값으로
분기한다. `retryable`은 그 code가 허락하는 최대치다. 실제 응답의 `retryable`은 그 발생에 대한 판단이라 `true`인
code도 `false`로 올 수 있다(위 「실패 본문」). `Retry-After`는 retryable인 발생에만 붙는다.
| code | status | category | retryable | `Retry-After` | 언제 |
| --- | --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `VALIDATION` | false | — | 헤더나 헤더 조합이 잘못됐다 |
| `UNAUTHENTICATED` | 401 | `AUTH` | false | — | 인증하지 않았다 |
| `ACCESS_DENIED` | 403 | `AUTHZ` | false | — | 권한이 없다. 존재를 숨기는 profile에서는 `FILE_NOT_FOUND`로 온다 |
| `FILE_NOT_FOUND` | 404 | `NOT_FOUND` | false | — | 파일이 없거나 숨겼다 |
| `FILE_ALREADY_EXISTS` | 409 | `CONFLICT` | false | — | 대상 이름이 이미 있다(copy·move는 새로 만들기만 한다) |
| `FILE_NOT_READY` | 409 | `CONFLICT` | true | 2 | 검증이 끝나지 않아 아직 읽을 수 없다 |
| `UPLOAD_OFFSET_MISMATCH` | 409 | `CONFLICT` | true | — | 이어 쓰기 offset이 서버 offset과 다르다. `details.currentOffset`부터 다시 보낸다 |
| `CONCURRENT_MODIFICATION` | 409 | `CONFLICT` | true | 1 | 같은 자원을 다른 요청이 바꾸는 중이다 |
| `UPLOAD_EXPIRED` | 410 | `CONFLICT` | false | — | 만료되거나 끝난(취소, 거부, 격리) 업로드다 |
| `CONTENT_LENGTH_REQUIRED` | 411 | `VALIDATION` | false | — | `require-content-length` profile인데 길이가 없다 |
| `PRECONDITION_FAILED` | 412 | `CONFLICT` | false | — | `If-Match`·`If-Unmodified-Since`가 맞지 않는다 |
| `FILE_TOO_LARGE` | 413 | `VALIDATION` | false | — | 파일 크기 정책을 넘었다 |
| `QUOTA_EXCEEDED` | 413 | `CONFLICT` | false | — | 저장 할당량을 넘었다 |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | `VALIDATION` | false | — | 받지 않는 media type이다 |
| `RANGE_NOT_SATISFIABLE` | 416 | `VALIDATION` | false | — | Range를 만족할 수 없다. `Content-Range: bytes */<길이>`를 싣는다 |
| `INTEGRITY_MISMATCH` | 422 | `DATA_INTEGRITY` | false | — | 선언한 digest와 받은 바이트가 다르다 |
| `MALWARE_DETECTED` | 422 | `DATA_INTEGRITY` | false | — | 검사기가 거부했다 |
| `INVALID_PATH` | 422 | `VALIDATION` | false | — | 경로 형식이 틀렸다 |
| `PATH_OUTSIDE_NAMESPACE` | 422 | `VALIDATION` | false | — | 경로가 namespace 밖을 가리킨다 |
| `TRANSFER_ADMISSION_REJECTED` | 429 | `RATE_LIMIT` | true | 1 | 호출자 자신의 동시 전송 permit이 찼다. 자기 전송이 끝나면 풀린다 |
| `CHECKSUM_MISMATCH` | 460 | `DATA_INTEGRITY` | false | — | tus `Upload-Checksum`이 그 요청의 바이트와 다르다. 그 chunk만 버린다 |
| `PARTIAL_WRITE` | 500 | `TRANSIENT_DEPENDENCY` | false | — | 쓰기가 중간에 끊겼다 |
| `AMBIGUOUS_COMPLETION` | 500 | `DATA_INTEGRITY` | false | — | 결과를 모른다. 이미 효과가 났을 수 있어 그대로 재시도하지 않는다 |
| `ATOMIC_PUBLISH_UNSUPPORTED` | 503 | `PERMANENT_DEPENDENCY` | false | — | 저장소가 원자적 게시를 지원하지 않는다(배포 설정 결함) |
| `STORAGE_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | true | 30 | 저장소나 검사기를 쓸 수 없다 |
| `SERVER_BUSY` | 503 | `TRANSIENT_DEPENDENCY` | true | 1 | instance 전체의 전송 permit이나 전송 worker pool이 찼다. 공용 서버 포화 코드와 같다 |
| `TRANSFER_TIMEOUT` | 504 | `TRANSIENT_DEPENDENCY` | true | 5 | 전송이 시간 안에 끝나지 않았다 |
| `STORAGE_FULL` | 507 | `TRANSIENT_DEPENDENCY` | false | — | 저장 용량이 없다 |
## 헤더 계약
| 헤더 | 계약 |
+4 -1
View File
@@ -63,7 +63,10 @@ V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileser
- **content가 아직 있으면 삭제는 `204`가 아니라 `202`로 답한다.** 파일은 이미 읽을 수 없고, 물리 회수는
미뤘다. `202`를 실패로 다루면 쓸데없이 재시도한다.
- **batch 업로드는 part가 실패해도 `200`으로 답한다.** batch는 명시적으로 원자적이지 않고, 상태 코드 하나로는
부분 결과를 정직하게 알릴 수 없다. `results[].error`를 읽는다.
부분 결과를 정직하게 알릴 수 없다. 판별은 `success`다. 모두 성공하면 `success: true`와 `results[]`, 하나라도
실패하면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`와 part별 `error.details[]`(`index`, `status`,
성공한 part의 `id`, 실패한 part의 `code`·`message`)다. 2026-11-12 전에는 실패가 있어도 `success: true`였다
(`docs/upgrade/2026-11-round9-contracts.md`).
- **결과를 모르는 실패는 재시도하면 안 된다.** 실패 Envelope의 `error.details`에서 `"ambiguous": true`를 본다.
- **`If-Match`는 version 숫자가 아니라 strong ETag를 받는다.** client는 실제로 받은 표현에 대해서만 주장할 수
있다.
+1 -1
View File
@@ -34,7 +34,7 @@
## inbound
- [ ] 컨트롤러는 변환만 한다. repository·엔티티를 모른다.
- [ ] 경로는 lowerCamel 복수형(AIP-122). 생성은 201 + `Location`.
- [ ] 경로는 lowerCamel 복수형(AIP-122). 생성은 201 + `Location`. 만든 것을 읽는 endpoint가 없으면 `Location`을 싣지 않고 controller 주석에 그 이유를 적는다.
- [ ] 도메인 규칙을 DTO bean validation에 다시 쓰지 않았다.
- [ ] 엔드포인트를 더했으면 **요청률 제한**을 어디서 거는지(ingress/app) 배포 설계에 있다. 앱 기본 off·켜는 법은 [docs/security/rate-limiting.md](../security/rate-limiting.md).
+15
View File
@@ -380,6 +380,21 @@ errors:
compatibility_impact: none
required_test: contract-verification:rate-limit
# source: 2026-11-12 리뷰 결정 ② — 서버 포화(허가 상한, 꽉 찬 work pool)는 전송마다 다른 코드였다(web-advanced
# ADMISSION_REFUSED 503, fileserver TRANSFER_ADMISSION_REJECTED 429, gRPC RATE_LIMIT_EXCEEDED). 이 코드 하나로 모은다.
# 호출자 자신의 빈도·동시성 초과만 429(RATE_LIMIT_EXCEEDED, fileserver TRANSFER_ADMISSION_REJECTED)다.
- code: SERVER_BUSY
category: TRANSIENT_DEPENDENCY
http_status: 503
retryable: true
retry_after_seconds: 1
owner_branch: 2026-11-12-round9-review
owner_layer: presentation
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
runbook_link: "runbook://server/busy"
compatibility_impact: behavior-change
required_test: contract-verification:server-saturation
# source: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지.
# 2초 = 기본 processing lease(30s)보다 짧은 고정값. 이전 "client는 polling"(retryable=false)은 조회 엔드포인트가 없어 폐기.
# 값 하나: IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER. processing-lease가 이 값 이하면 기동 실패(재리뷰 RR-02-05).
+46
View File
@@ -0,0 +1,46 @@
---
title: Runbook — 서버 포화(SERVER_BUSY)
category: TRANSIENT_DEPENDENCY
error_codes: [SERVER_BUSY]
severity: P2
owner: oncall
last_updated: 2026-11-13
status: 운영
---
# Runbook: 서버 포화 (`runbook://server/busy`)
이 instance가 요청을 더 받을 자리가 없어 바로 거절했다. 호출자의 빈도 초과(`RATE_LIMIT_EXCEEDED` 429)와 다르다. 이
코드는 서버 쪽 상한이 찼다는 뜻이다.
## 증상
- HTTP `503`과 `error.code = SERVER_BUSY`, `Retry-After: 1`. gRPC는 `UNAVAILABLE`와 trailer `error-code: SERVER_BUSY`.
- `http_server_requests_seconds_count{status="503"}`이 오르고, 같은 때 p95 지연은 오르지 않는다. 거절은 일을 하기 전에
나기 때문이다.
- 이 코드를 내는 곳은 셋이다.
| 내는 곳 | 찬 상한 | 설정 |
| --- | --- | --- |
| web-advanced `VirtualThreadAdmissionFilter` | 동시에 처리하는 요청 수 | `app.web.advanced.mvc-virtual-threads.admission-limit` |
| fileserver 전송 허가 | instance 전체 업로드·직접 다운로드 permit, 전송 worker pool | `app.fileserver-platform.quota.instance-upload-permits`, `…direct-download-permits` |
| gRPC `GrpcCallAdmission` | feature 호출 worker와 대기열 | `app.grpc.server.executor-max-pool-size`, `executor-queue-capacity` |
## 진단
1. 거절이 한 instance에만 몰리는지 본다. 한 instance만이면 부하 분산이 고르지 않거나 그 instance의 하류가 느리다.
2. 같은 때 하류 지연(DB pool 대기, 외부 HTTP 지연)을 본다. 하류가 느리면 허가를 쥔 요청이 오래 머물러 상한이 찬다.
이때 상한을 올리면 하류 pool 앞의 줄만 길어진다.
3. 정상 부하에서 상한 자체가 작은지 본다. 거절률이 트래픽에 비례하고 하류가 건강하면 상한이 작다.
## 조치
- 하류가 느린 경우: 하류 runbook(`db-unavailable`, `dependency-timeout`)을 먼저 따른다. 상한은 그대로 둔다.
- 상한이 작은 경우: instance를 늘리거나 위 표의 설정을 올린다. virtual thread `admission-limit`은 DB pool과 외부
bulkhead를 넘지 않게 둔다(`docs/web/virtual-thread-profile.md`).
- client는 `Retry-After` 뒤에 같은 요청을 다시 보낸다. 고칠 것이 없으면 거절은 1초 안에 풀린다.
## 에스컬레이션
- 5분 넘게 거절률이 전체 요청의 5%를 넘으면 P1으로 올리고 인프라 당번을 부른다.
- 모든 instance가 같이 거절하고 하류가 건강하면 용량 문제다. 배포 소유자에게 scale-out을 요청한다.
+32
View File
@@ -0,0 +1,32 @@
# 업그레이드 안내 — 2026-11 HTTP 계약·오류 코드 정리
- 범위: web-advanced(patch·stream·virtual thread), fileserver·notification HTTP, 전송 오류 코드를 약속한 계약에 맞춘
변경. 응답 코드·모양이 바뀐 곳이 있다. 아래 표가 그 목록이다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 계약·오류 코드 발견
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스와, 그 서비스의 HTTP 응답을 읽는 client 팀이 읽는다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | `JsonMergePatchApplier`·`JsonPatchApplier`를 만드는 코드에 셋째 인자로 Boot의 `jakarta.validation.Validator` bean을 넘긴다 | 컴파일이 실패한다 | web-advanced patch를 쓰는 서비스 |
| 2 | patch 거부를 읽는 client는 `PATCH_REJECTED`(400) 하나로 본다. 전에는 JSON이 아닌 본문이 `500 INTERNAL_ERROR`, 빈 문서·연산 모양 오류·merge 깊이 초과가 `400 BAD_PARAMETER`, 너무 깊은 pointer가 `403 PATCH_PATH_FORBIDDEN`이었다 | client가 옛 코드로 분기하던 곳이 다른 코드를 받는다 | patch route를 둔 서비스와 그 client |
| 3 | patch 결과가 Bean Validation 제약을 어기면 `400 VALIDATION_FAILED`와 필드별 `details`가 나간다. patch 대상 타입의 제약을 확인한다 | 전에는 제약을 어긴 객체가 그대로 저장 경로로 갔다 | web-advanced patch를 쓰는 서비스 |
| 4 | 스트림 `Failure` 기록의 `code`가 실패의 코드(예: `STREAM_ITEM_TOO_LARGE`) 또는 `INTERNAL_ERROR`다. `DEPENDENCY_FAILURE`로 분기하던 client를 고친다 | 그 분기가 다시는 맞지 않는다 | NDJSON·JSON-seq stream을 읽는 client |
| 5 | virtual thread profile을 켠 배포는 이제 실제로 허가 상한을 건다. `admission-limit`이 부하에 맞는지 본다 | 전에는 상한이 없어 모든 요청이 들어왔다. 이제 넘치면 `503 SERVER_BUSY`와 `Retry-After: 1`이다 | `app.web.advanced.mvc-virtual-threads.enabled=true`인 배포 |
| 6 | fileserver batch(`POST /v1/files:batch`)를 읽는 client는 `success`로 가른다. 모두 성공하면 `success: true`와 최상위 `results[]`, 하나라도 실패하면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`, part별 `error.details[]`(`index`, `status`, `id`, `code`, `message`)다. 부분 실패에서는 part를 요청 순서 `index`로 짚는다(`clientPartId`는 전부 성공한 `results[]`에만 있다) | 전에는 실패가 있어도 `success: true`이고 결과가 `data.results[]`에 있었다. 옛 경로로 읽던 client는 결과를 못 찾는다 | fileserver를 쓰는 서비스와 그 client |
| 7 | `BulkItemResult.error(index, code, message)`를 부르던 코드를 `BulkItemResult.error(index, ApiErrorCode)`로 바꾼다. 문구는 code의 category 고정 문구가 된다 | 컴파일이 실패한다 | bulk endpoint를 둔 서비스 |
| 8 | 서버 포화 거절을 읽는 client는 `SERVER_BUSY`(503, retryable, `Retry-After: 1`)로 본다. web-advanced `ADMISSION_REFUSED`, fileserver instance·전송 pool 포화의 `TRANSFER_ADMISSION_REJECTED`(429), gRPC 포화의 `RESOURCE_EXHAUSTED`/`RATE_LIMIT_EXCEEDED`가 이 코드로 바뀌었다(gRPC status는 `UNAVAILABLE`). 호출자 자신의 동시 전송 초과만 `TRANSFER_ADMISSION_REJECTED` 429로 남는다 | 옛 코드로 분기하던 재시도 로직이 맞지 않는다. 자바에서 `WebAdvancedError.ADMISSION_REFUSED`를 참조하던 코드는 컴파일이 실패한다 | 세 전송의 client, web-advanced 코드를 참조하던 서비스 |
| 9 | 컨테이너가 넘긴 503(필터의 `sendError(503)` 등)은 `SERVER_BUSY`다. 비동기 요청 시간 초과만 `REQUEST_TIMEOUT`이다 | 전에는 모든 503이 `REQUEST_TIMEOUT`이었다 | web을 쓰는 모든 서비스의 client |
| 10 | 알림 template 게시 경로를 `/notification-templates`에서 `/notificationTemplates`로 바꾼다(prefix 뒤) | 옛 경로는 404다 | 알림 template을 게시하는 client와 배포 스크립트 |
| 11 | 알림 제출·template 게시의 모르는 `channel`·`slot`·`locale`·`fallbackLocale`은 `400 VALIDATION_FAILED`와 그 필드를 짚는 `details`다(전에는 details 없는 `BAD_PARAMETER`) | `BAD_PARAMETER`로 분기하던 client가 다른 코드를 받는다 | 알림 HTTP client |
| 12 | 이름 없이 올린 파일의 표시 이름이 `upload.bin`에서 `file`이 된다(모든 전송에서 같다) | 표시 이름이 바뀐다. 동작은 같다 | fileserver를 쓰는 서비스 |
| 13 | fileserver `ATOMIC_PUBLISH_UNSUPPORTED`(재시도 불가 code)는 더 이상 `Retry-After`를 싣지 않는다. 본문 `retryable=false`와 맞춘 것이다 | 그 헤더로 재시도하던 client가 재시도하지 않는다(원래 재시도해도 소용없는 실패다) | fileserver client |
| 14 | 브라우저 client는 `Content-Range`를 읽을 수 있다(CORS 노출 목록에 더함) | — 더하기만 한 변경 | fileserver 다운로드를 이어 받는 브라우저 client |
| 15 | bulk 부분 실패의 `error.message`가 영어 문구에서 category 고정 문구(`ClientErrorMessages`)로 바뀌었다. 항목(`details[]`)은 자기 상태에 맞는 키만 싣는다(성공 항목에 `code`·`message` 키 없음, 실패 항목에 `id` 키 없음) | 문구로 분기하던 client(원래 하면 안 된다)나 null 키를 기대하던 strict client가 다르게 본다 | bulk endpoint를 둔 서비스의 client |
| 16 | 스트림에서 위치가 앞 항목보다 크지 않은 항목은 이제 나가지 않고, 스트림이 `INTERNAL_ERROR` `Failure` 기록으로 끝난다(전에는 그 항목을 쓴 뒤 끝났다) | 서버 결함이 있는 source의 client가 마지막 항목을 받지 않는다 | NDJSON·JSON-seq stream을 읽는 client |
| 17 | 상태만 아는 503·429(Spring이 던진 `ResponseStatusException` 등)도 registry의 `Retry-After`를 싣는다 | — 헤더를 더하기만 한 변경 | web을 쓰는 서비스의 client |
| 18 | virtual thread admission filter가 Spring Security chain 뒤에서 돈다. 인증·권한에서 거절된 요청은 허가를 쓰지 않고, 거절 503에 CORS 헤더가 붙는다 | — | virtual thread profile을 켠 배포 |
+1 -1
View File
@@ -10,7 +10,7 @@ Advanced capability는 따로 된 leaf `adapter:inbound:web-advanced`(`src/adapt
| Capability | 켜는 법 | 더하는 것 | 테스트 |
| --- | --- | --- | --- |
| MVC virtual thread | `app.web.advanced.mvc-virtual-threads.enabled=true`(+ 허가 상한과 예산) | **모든** 요청에 대한 다른 스케줄링 모델 | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest` |
| MVC virtual thread | `app.web.advanced.mvc-virtual-threads.enabled=true`(+ 허가 상한과 예산) | **모든** 요청에 대한 다른 스케줄링 모델과 요청마다 거는 허가 상한(`VirtualThreadAdmissionFilter`) | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest`, `VirtualThreadAdmissionFilterTest` |
| NDJSON 스트리밍 | `app.web.advanced.ndjson.enabled=true` | 오래 사는 connection | `MvcStreamingWiringTest`, `WebStreamCoreTest`, `WebStreamDrainTest`, `WebStreamingSoakIT` |
| JSON text sequence(RFC 7464) | `app.web.advanced.json-sequence.enabled=true` | 오래 사는 connection | NDJSON과 같다 |
| JSON Merge Patch(RFC 7396) | 라이브러리 — `JsonMergePatchApplier` | 부분 문서 | `JsonMergePatchApplierTest` |
+6 -3
View File
@@ -177,7 +177,7 @@ CORS가 켜져 있으면(`app.cors.enabled=true`) cross-origin 실제 응답의
`traceparent`, `Location`, `ETag`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- fileserver를 실은 배포: `Tus-Resumable`, `Tus-Version`, `Tus-Extension`, `Tus-Max-Size`,
`Upload-Offset`, `Upload-Length`, `Upload-Defer-Length`, `Upload-Expires`, `Upload-Complete`,
`Upload-Limit`, `Content-Disposition`, `Accept-Ranges`
`Upload-Limit`, `Content-Disposition`, `Accept-Ranges`, `Content-Range`
새 응답 헤더를 쓰는 모듈은 `CorsExposedHeaders` bean으로 자기 헤더를 기여한다.
@@ -187,15 +187,18 @@ CORS가 켜져 있으면(`app.cors.enabled=true`) cross-origin 실제 응답의
| 코드 | status | category | `retryable` | `Retry-After` | 언제 |
| --- | --- | --- | --- | --- | --- |
| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |
| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. 그 밖의 503(필터의 `sendError(503)` 등)은 공용 `SERVER_BUSY`다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |
| `IDEMPOTENCY_KEY_INVALID` | 400 | `VALIDATION` | `false` | 없음 | 2절 |
| `RATE_LIMIT_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 있음 | rate-limit 저장소 응답 없음(`docs/web/runbook.md`) |
| `RATE_LIMIT_INCOMPATIBLE` | 503 | `INTERNAL` | `false` | 없음 | rate-limit 제공자가 계약과 맞지 않음 |
| `OPERATION_NOT_FOUND` | 404 | `NOT_FOUND` | `false` | 없음 | durable operation 조회(`DurableOperationController`)에서 그 operation이 없거나 다른 호출자의 것이다. 둘을 가르지 않는다 |
- 컨트롤러 파라미터 제약 위반(`@RequestParam @Max(10)`)은 요청 본문 위반과 같은
`400 VALIDATION_FAILED`이고 `details`는 `[{field, code, message}]`다. 거절된 값은 싣지 않는다.
- web-advanced를 실은 서비스의 예외 코드(`ADMISSION_REFUSED` 503 등 10종)는
- web-advanced를 실은 서비스의 예외 코드(`PATCH_REJECTED` 400 등)는
`src/adapter/inbound/web-advanced/README.md` 「오류 응답」이 정본이다.
- 서버 포화(허가 상한, 꽉 찬 work pool)는 모든 전송이 공용 `SERVER_BUSY`(503, retryable, `Retry-After: 1`)
하나로 답한다. 호출자 자신의 빈도 초과만 `RATE_LIMIT_EXCEEDED` 429다(`docs/registries/error-codes.yaml`).
- 직접 쓰는 거부 응답(401·403·429·503)도 컨트롤러 응답과 같이 `application/json;charset=UTF-8`이다.
## 5. 바꿀 때
+11 -2
View File
@@ -38,6 +38,10 @@ route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작
**한도.** 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다
서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
**거부 코드.** 형식이 틀린 문서(JSON이 아닌 본문, 빈 문서, 한도 초과, 연산 모양 오류)는 모두 `400 PATCH_REJECTED`다.
허용 목록 밖의 경로만 `403 PATCH_PATH_FORBIDDEN`이고, 실패한 `test`는 `409 PATCH_TEST_FAILED`다. 너무 깊은 pointer는
권한 문제가 아니라 형식 문제라 400이다.
## 원자성
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고
@@ -60,8 +64,13 @@ JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다.
## 검증
patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검증한다. 필드 하나하나는 모두 유효한 patch가 유효하지 않은
객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도
보지 못한다.
객체를 만들 수 있다. 서로 맞아야 하는 두 필드가 그런 예다. 바뀐 것만 검증하면 그것을 보지 못한다.
- 두 applier는 서비스의 Bean Validation `Validator`를 생성자로 받고, 결과 객체 전체를 검증한 뒤에 돌려준다. 위반은
`@Valid` 본문과 같은 `400 VALIDATION_FAILED`와 필드별 `details`다.
- 결과가 자원 타입으로 읽히지 않으면(숫자 자리에 문자열) `400 PATCH_REJECTED`다.
- 검증하는 대상은 web 표현 DTO이고, 제약은 요청 문법이다(web AGENTS B4·C1). 상태 전이처럼 업무 규칙인 검증은 여기서
하지 않는다. 결과를 command로 바꿔 받은 유스케이스가 한다.
## 선행 조건
+16 -11
View File
@@ -12,8 +12,9 @@ writer는 `adapter:inbound:web-advanced`(골라 쓰는 leaf, `app.web.advanced.n
connection은 결과를 알 수 없다. 끝은 셋이다.
1. **`Complete` envelope.** stream이 끝났다. `lastSequence`가 마지막 위치다.
2. **`Failure` 기록.** commit 뒤에 무언가 실패했다. 오류 code와 client에게 보여도 되는 메시지를 담는다. 상태는 여전히
200이다.
2. **`Failure` 기록.** commit 뒤에 무언가 실패했다. 상태는 여전히 200이다. `code`는 실패한 예외의 코드다(예:
`STREAM_ITEM_TOO_LARGE`). 코드가 없는 실패는 등록된 `INTERNAL_ERROR`다. `message`는 그 category의 고정 문구다. commit 전에
던져졌다면 받았을 코드·문구와 같다.
3. **둘 다 아님.** stream 중간에 connection이 닫혔다. 서버는 이것을 `ABRUPT_CLOSE`로 기록한다. client 쪽에서는 *끝
envelope를 찾지 않는 한* 끝난 stream과 구분할 수 없다.
@@ -23,7 +24,7 @@ connection은 결과를 알 수 없다. 끝은 셋이다.
## 위치
모든 `Item`은 1부터 세는 `sequence`를 가진다. 위치는 엄격히 증가하고, 서버가 그것을 강제한다. 반복이나 후퇴는 client가
견뎌야 할 것이 아니라 서버 쪽 오류다.
견뎌야 할 것이 아니라 서버 쪽 오류다. writer는 그런 항목을 쓰지 않고 stream을 `INTERNAL_ERROR` `Failure` 기록으로 끝낸다.
0은 절대 유효한 위치가 아니다. 첫 항목이 0을 주장한 stream과 sequence를 아예 정하지 않은 stream이 똑같아 보이기
때문이다.
@@ -55,21 +56,25 @@ resnapshot은 자원을 보통 endpoint에서 다시 읽고 새 stream을 시작
## Heartbeat와 시간 초과
서버는 `heartbeatInterval`마다 keepalive를 쓴다. 그보다 오래 아무것도 보지 못한 client는 connection이 죽었다고 봐야
한다. socket에서는 조용한 connection과 끊긴 connection이 같고, heartbeat가 둘을 가른다.
writer(`MvcStreamWriter`)는 요청 thread에서 source를 차례로 쓴다. 그래서 heartbeat를 보내지 않고, `idleTimeout`·
`maxStreamAge`로 stream을 닫지도 않는다. 그 값은 `WebStreamPolicy`에 있고, 자기 stream을 `WebStreamRegistry`에 올려
돌리는 서비스가 쓴다.
stream은 `idleTimeout`(만든 것이 없음)과 `maxStreamAge`(활동과 상관없음)에 닫힌다. 둘 다 보통의 끝이고, connection이
허락하면 둘 다 끝 envelope를 보낸다.
- client는 heartbeat를 기대하지 않는다. 자기 읽기 시간 초과를 두고, 그 시간에 아무것도 오지 않으면 끝 envelope 없이
닫힌 것으로 보고 이어 받기 cursor로 다시 연결한다.
- socket에서는 조용한 connection과 끊긴 connection이 같다. heartbeat가 필요한 route는 서비스가 그것을 더하고 이 문서의
route 설명에 적는다.
## 느린 소비자
서버는 뒤처진 소비자를 위해 최대 `maxBufferedItems`까지만 버퍼링한다. 그것을 넘으면 버퍼를 키우지 않고 connection을
닫는다. 따라가지 못하는 client는 서버가 밀린 것을 쥐고 있기를 기대하지 말고, 이어 받기 cursor로 다시 연결한다.
writer는 버퍼를 두지 않는다. 느린 소비자는 서버의 쓰기를 막고, 그동안 source도 멈춘다. 서버 heap에 밀린 항목이 쌓이지
않는다. `maxBufferedItems`는 버퍼를 두는 서비스 구현의 한도다. 따라가지 못하는 client는 이어 받기 cursor로 다시 연결한다.
## 종료
rolling 배포 중에는 노드가 받기를 멈추기 전에 열린 stream이 다시 연결하라는 요청을 받는다. 바로 다시 연결한다. 노드는
drain 기한에 아직 열린 것을 강제로 닫고, 그것은 갑작스러운 닫힘으로 도착한다.
drain 순서(받기를 멈추고, 다시 연결을 요청하고, 기한에 강제로 닫기)는 `WebStreamDrainCoordinator`에 있다. 서비스가
자기 stream을 `WebStreamRegistry`에 등록하고 그 조정기를 종료 순서에 넣었을 때만 돈다. 기본 writer만 쓰는 배포에서는
종료 때 열린 stream이 갑작스러운 닫힘으로 끝난다.
갑작스러운 닫힘에 backoff와 jitter 없이 바로 다시 연결하지 않는다. 노드의 stream이 한꺼번에 끊겼을 때 모든 client가
한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.
+6 -1
View File
@@ -36,7 +36,12 @@ app:
`VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를 제한하면 기다림을 되돌려 놓고 virtual
thread로 얻은 것을 버리게 된다. virtual thread 만 개가 있어도 백 개만 허가를 쥐고 나머지는 문 앞에서 거부된다.
거부는 **`Retry-After`가 붙은 503**이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤
상한은 `VirtualThreadAdmissionFilter`가 모든 요청에 건다. Spring Security chain 바로 뒤라, 거절 응답에도 CORS 헤더가
붙어 브라우저가 503과 `Retry-After`를 읽고, 보안 chain이 거절한 요청(인증 없음, 권한 없음)은 허가를 쓰지 않는다. 거절된
요청은 handler에 닿지 않는다. async 요청은 async 일이 끝날 때까지 허가를 쥔다. 넘겨준 순간 돌려주면 넘기는 일만 제한하고 정작
하류 pool을 쓰는 일은 제한하지 못한다.
거부는 **`Retry-After`가 붙은 503**(공용 코드 `SERVER_BUSY`)이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤
가득 찬 pool 뒤에서 30초 뒤에 시간 초과가 난 같은 요청보다 client에게 확실히 낫다.
semaphore는 일부러 공정하다. 불공정한 것이 빠르지만, 새로 온 요청이 기다리던 요청을 앞지르게 두고, 앞지름당한
+3
View File
@@ -116,6 +116,9 @@
| GraphQL 인자 변환 실패 | Spring GraphQL 인자 binder의 `BindException`(`@Argument` 값이 파라미터 타입으로 바뀌지 않음)은 `BAD_PARAMETER`(`REQUEST`)로 답하고, WARN 한 줄(예외 타입만, 입력값 없음)을 남긴다. web이 바뀌지 않는 경로 변수에 답하는 것과 같다 | 소유자 | 2026-11-07 같은 전달, r8-f1 보고 「범위 밖」 2 |
| 약속한 응답으로 맞추기 | 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이다. 고치기 전에 묻지 않고, 응답이 바뀌니 업그레이드 안내 행은 적는다. 약속한 곳끼리 다르면 묻는다 | 소유자(2026-11-07, 기본값 확인) | `docs/work/improve.md` 7절, `docs/work/evidence.md` 11절 |
| STOMP 필수 header 누락 | 필수 header·destination 변수가 없을 때 Spring이 던지는 `MessageHandlingException`은 ERROR 그대로 둔다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패(handler의 `Error` 등)도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다 | 기본값(2026-11-07) | 2026-11-07 총괄 지시, r8-f1 보고 「범위 밖」 3 |
| 서버 포화 코드 | 서버 쪽 상한(요청 허가, 꽉 찬 work pool)이 찬 거절은 모든 전송이 공용 `SERVER_BUSY`(503, `TRANSIENT_DEPENDENCY`, retryable, `Retry-After: 1`) 하나다. 호출자 자신의 빈도·동시성 초과만 429(`RATE_LIMIT_EXCEEDED`, fileserver `TRANSFER_ADMISSION_REJECTED`)다. 상태만 아는 503도 `SERVER_BUSY`이고, 비동기 요청 시간 초과만 `REQUEST_TIMEOUT`이다 | 기본값(2026-11-12, 소유자가 뒤집을 수 있다) | 2026-11-12 전체 리뷰 기록 README 6절 ② |
| batch 부분 실패 | fileserver batch도 공용 bulk envelope(web AGENTS B8)다. 하나라도 실패하면 `success:false` + `BATCH_PARTIAL_FAILURE` + 항목별 `details` | 기본값(2026-11-12) | 같은 README 6절 ① |
| PATCH 정본 | `docs/web/patch-contract.md`가 merge patch·JSON Patch의 정본이다. web AGENTS B2는 `application/json` PATCH DTO만 다루고 그쪽을 가리킨다 | 기본값(2026-11-12) | 같은 README 6절 ③ |
### 2.4 멱등성
+6 -6
View File
@@ -139,17 +139,17 @@ strictTestLanes {
// be.
//
// A snapshot does not shrink the surface. It makes each addition visible in review, which is the
// prerequisite for shrinking it: the `api` and `spi` packages are the surface an adopter is meant
// to use, and everything else in this file is a candidate for becoming internal when the leaf is
// split into capability artifacts. Until then the number cannot grow by accident.
// prerequisite for shrinking it: the `api` package is the surface an adopter is meant to use, and
// everything else in this file is a candidate for becoming internal when the leaf is split into
// capability artifacts. Until then the number cannot grow by accident.
apiSurface {
label = 'GraphQl'
baseline = rootProject.file('docs/architecture/graphql-api-surface.txt')
description = 'GraphQL leaf public API surface — every public top-level type in src/main/java.'
rationale = [
'A public type in a single-jar leaf is reachable from every adopter\'s code, so',
'additions are reviewed rather than discovered. `api` and `spi` are the intended',
'external surface; the rest are candidates to become internal when this leaf is',
'split into capability artifacts.',
'additions are reviewed rather than discovered. `api` is the intended external',
'surface; the rest are candidates to become internal when this leaf is split into',
'capability artifacts.',
]
}
+2 -1
View File
@@ -95,7 +95,8 @@ executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서
health/reflection 에는 적용하지 않는다(`Health/Watch` 는 원래 오래 사는 스트림이다).
- **포화 시 동작(`GrpcCallAdmission`).** feature 호출은 `executor-max-pool-size +
executor-queue-capacity` 개까지만 받고, 넘친 호출은 handler 를 시작하지 않고 즉시
`RESOURCE_EXHAUSTED`(`RATE_LIMIT_EXCEEDED`, retryable)로 닫는다. 구현: io.grpc
`UNAVAILABLE`(`SERVER_BUSY`, retryable)로 닫는다. 서버 포화는 모든 전송이 이 공용 코드 하나다(2026-11-12 전에는
`RESOURCE_EXHAUSTED`/`RATE_LIMIT_EXCEEDED`였다). 구현: io.grpc
`ServerCallExecutorSupplier`(`@ExperimentalApi`, 1.39부터)가 호출 시작 전에 permit 을 확인해
받은 호출만 고정 크기 work pool 로 옮기고, 못 받은 호출은 가장 바깥 인터셉터가 닫는다. 메서드
조회·context 정리·health·reflection 은 작은 dispatch pool 에서 돈다. 버린 대안:
@@ -28,9 +28,11 @@ import java.util.concurrent.atomic.AtomicBoolean;
* dispatch executor, before the call starts. A feature call that gets a permit is moved to the
* bounded work pool; one that does not stays on the dispatch executor and is marked, and this same
* object, installed as the outermost feature interceptor, closes the marked call with {@code
* RATE_LIMIT_EXCEEDED} without starting the handler. The permit is returned once, when the admitted
* call completes or is cancelled. Health and reflection are not feature calls: they take no permit
* and run on the dispatch executor, so a saturated pool cannot make health lie.
* SERVER_BUSY} ({@code UNAVAILABLE}) without starting the handler: the shared code every transport
* answers server saturation with, not the caller-rate {@code RATE_LIMIT_EXCEEDED} it used to be.
* The permit is returned once, when the admitted call completes or is cancelled. Health and
* reflection are not feature calls: they take no permit and run on the dispatch executor, so a
* saturated pool cannot make health lie.
*
* <p>Each admitted call has at most one task in the work pool at a time (io.grpc serializes a
* call's callbacks), so a work queue as deep as the permit count can never reject.
@@ -79,8 +81,8 @@ final class GrpcCallAdmission implements ServerCallExecutorSupplier, ServerInter
ServerCall<Q, R> call, Metadata headers, ServerCallHandler<Q, R> next) {
if (refused.remove(headers)) {
call.close(
statusMapper.statusFor(OperationalError.RATE_LIMIT_EXCEEDED),
statusMapper.trailersFor(OperationalError.RATE_LIMIT_EXCEEDED));
statusMapper.statusFor(OperationalError.SERVER_BUSY),
statusMapper.trailersFor(OperationalError.SERVER_BUSY));
return new ServerCall.Listener<>() {};
}
AtomicBoolean released = new AtomicBoolean();
@@ -17,9 +17,7 @@ import io.grpc.Status;
*/
public class GrpcStatusMapper {
/**
* Trailer key carrying the stable {@link ApiErrorCode#code()} (e.g. {@code WORKLOG_NOT_FOUND}).
*/
/** Trailer key carrying the stable {@link ApiErrorCode#code()} (e.g. {@code SERVER_BUSY}). */
static final Metadata.Key<String> CODE_KEY =
Metadata.Key.of("error-code", Metadata.ASCII_STRING_MARSHALLER);
@@ -329,8 +329,8 @@ class GrpcP1BoundaryWireTest {
}
@Test
@DisplayName("스레드와 대기열이 모두 찬 서버는 넘친 호출을 기다리게 두지 않고 즉시 RESOURCE_EXHAUSTED로 거절한다")
void aCallBeyondTheExecutorAndQueueIsRefusedAtOnceAsResourceExhausted() {
@DisplayName("스레드와 대기열이 모두 찬 서버는 넘친 호출을 기다리게 두지 않고 즉시 UNAVAILABLE(SERVER_BUSY)로 거절한다")
void aCallBeyondTheExecutorAndQueueIsRefusedAtOnceAsServerBusy() {
withChannel(
contextRunner.withPropertyValues(
"app.grpc.server.executor-max-pool-size=1",
@@ -351,12 +351,11 @@ class GrpcP1BoundaryWireTest {
// then
assertThat(outcomes)
.extracting(Status::getCode)
.containsExactlyInAnyOrder(
Status.Code.OK, Status.Code.OK, Status.Code.RESOURCE_EXHAUSTED);
.containsExactlyInAnyOrder(Status.Code.OK, Status.Code.OK, Status.Code.UNAVAILABLE);
assertThat(outcomes)
.filteredOn(status -> !status.isOk())
.extracting(Status::getDescription)
.containsExactly(ClientErrorMessages.of(Category.RATE_LIMIT));
.containsExactly(ClientErrorMessages.of(Category.TRANSIENT_DEPENDENCY));
});
}
+3 -3
View File
@@ -51,14 +51,14 @@ virtual thread 실행기는 `TaskDecorator` bean 을 요구한다(요청 상관
이 leaf 의 예외는 모두 `ApiErrorCarrier` 다. 코드는 `error.WebAdvancedError` 한 enum 이 정하고, web 의
`GlobalExceptionHandler.handleCarrier` 한 분기가 Envelope 로 답한다(별도 `@RestControllerAdvice` 없음).
예전에는 10종 모두 `500 INTERNAL_ERROR` 였다(리뷰 2026-11-01 02-07). 아래 표와 enum 은 같은 값을 말하고,
예전에는 10종 모두 `500 INTERNAL_ERROR` 였다(리뷰 2026-11-01 02-07). admission 거절은 2026-11-12부터 공용 `SERVER_BUSY`다. 아래 표와 enum 은 같은 값을 말하고,
`WebAdvancedErrorMappingTest` 가 실제 응답으로 확인한다.
| 예외 | `error.code` | status | category | retryable | 응답에 더 실리는 것 | 클라이언트 행동 |
| --- | --- | --- | --- | --- | --- | --- |
| `AdmissionRefusedException` | `ADMISSION_REFUSED` | 503 | `TRANSIENT_DEPENDENCY` | true | `Retry-After: 1` | 잠시 뒤 같은 요청 |
| `AdmissionRefusedException` | `SERVER_BUSY`(공용 `OperationalError`) | 503 | `TRANSIENT_DEPENDENCY` | true | `Retry-After: 1` | 잠시 뒤 같은 요청. 서버 포화는 모든 전송이 이 코드 하나다 |
| `JsonPatchTestFailedException` | `PATCH_TEST_FAILED` | 409 | `CONFLICT` | false | `details.pointer`(서버 값은 없음) | 다시 읽고 새 patch |
| `JsonPatchRejectedException` | `PATCH_REJECTED` | 400 | `VALIDATION` | false | — | patch 문서를 고친다 |
| `JsonPatchRejectedException` | `PATCH_REJECTED` | 400 | `VALIDATION` | false | — | patch 문서를 고친다. JSON이 아닌 본문, 빈 문서, 한도·깊이 초과, 연산 모양 오류, 결과가 자원 타입으로 읽히지 않는 patch가 모두 이 코드다 |
| `PatchAuthorizationException` | `PATCH_PATH_FORBIDDEN` | 403 | `AUTHZ` | false | `details.refusedPaths` | 해당 경로를 빼거나 권한 확보 |
| `UnsupportedApiVersionException` | `API_VERSION_UNSUPPORTED` | 404 | `NOT_FOUND` | false | — | 지원 버전 경로로 |
| `SunsetViolationException` | `API_DEPRECATION_INVALID` | 500 | `INTERNAL` | false | — | 서버 설정 결함(등록 시점 오류) |
@@ -11,16 +11,14 @@ import dev.caskeleton.shared.error.Category;
* leaf README's "오류 응답" section; it states the same values.
*
* <p>Before this existed every one of these reached the client as {@code 500 INTERNAL_ERROR} with
* an ERROR log line, including an admission refusal the profile documents as a 503 (review
* 2026-11-01 02-07).
* an ERROR log line (review 2026-11-01 02-07). The admission refusal it used to name is now the
* shared {@code OperationalError.SERVER_BUSY} (review 2026-11-12).
*
* <p>Like {@code RateLimitTransportError}, these are not in {@code
* docs/registries/error-codes.yaml}, which is the {@code OperationalError} SSOT.
*/
public enum WebAdvancedError implements ApiErrorCode, RetryAfterHint {
/** The virtual-thread admission limit was full. A refusal in a millisecond; come back shortly. */
ADMISSION_REFUSED(Category.TRANSIENT_DEPENDENCY, 503, true, 1),
/** A JSON Patch {@code test} did not hold; nothing was applied. Re-read, then retry. */
PATCH_TEST_FAILED(Category.CONFLICT, 409, false, 0),
/** The patch document is malformed or over a limit; nothing was applied. */
@@ -6,6 +6,10 @@ import dev.caskeleton.adapter.inbound.web.advanced.stream.WebStreamTermination;
import dev.caskeleton.adapter.inbound.web.advanced.stream.encoding.NdjsonRecord;
import dev.caskeleton.adapter.inbound.web.advanced.stream.encoding.StreamFraming;
import dev.caskeleton.adapter.inbound.web.advanced.stream.encoding.StreamRecordEncoder;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.ClientErrorMessages;
import dev.caskeleton.shared.error.OperationalError;
import java.io.IOException;
import java.io.OutputStream;
import java.time.Clock;
@@ -20,6 +24,16 @@ import java.util.Objects;
* terminal record before closing, and classify a write failure rather than letting it become a 500
* on a response that is already 200.
*
* <p>Positions are enforced before each write, by {@code WebStreamEvidence#requireNext}: an item
* whose sequence is not above the previous one is a server fault, and the stream ends with a
* terminal failure record instead of handing the client a repeat or a rewind it would apply.
*
* <p>What this writer does not do: it writes synchronously from an iterator on the request thread,
* so it sends no heartbeat while the source is blocked, enforces no idle timeout or maximum age,
* and keeps no buffer (a slow consumer blocks the source instead). Those bounds are in {@code
* WebStreamPolicy} and the drain in {@code WebStreamDrainCoordinator} for a service that runs its
* streams through {@code WebStreamRegistry}; {@code docs/web/streaming-contract.md} says which.
*
* <p>**Flushing after every record is not optional.** Without it the container buffers, and a
* streaming response that arrives in one chunk at the end is a slow non-streaming response — which
* passes every test that checks the body and fails the only thing the client wanted.
@@ -58,6 +72,10 @@ public final class MvcStreamWriter {
try {
while (records.hasNext()) {
NdjsonRecord<T> record = records.next();
if (record instanceof NdjsonRecord.Item<T> item) {
// WebStreamEvidence owns the rule; asked before the write so the item never leaves.
evidence.requireNext(new StreamSequence(item.sequence()));
}
writeRecord(record, output);
if (record instanceof NdjsonRecord.Item<T> item) {
evidence.recordDelivered(new StreamSequence(item.sequence()));
@@ -91,13 +109,17 @@ public final class MvcStreamWriter {
}
// Otherwise the source failed after commit. The status is already 200, so the failure goes
// into the stream as a terminal record — and if even that cannot be written, it is an abrupt
// close and is recorded as one rather than counted as a completion.
// close and is recorded as one rather than counted as a completion. The record carries the
// failure's own code when it has one (a carrier anywhere in the cause chain, such as
// STREAM_ITEM_TOO_LARGE), else the registered INTERNAL_ERROR, and the category's fixed message:
// the same code and wording a client would have read before commit.
ApiErrorCode code =
ApiErrorCarrier.firstIn(failure)
.map(carrier -> ((ApiErrorCarrier) carrier).errorCode())
.orElse(OperationalError.INTERNAL_ERROR);
try {
writeRecord(
new NdjsonRecord.Failure<T>(
lastSequence,
"DEPENDENCY_FAILURE",
"the stream ended early because a dependency failed"),
new NdjsonRecord.Failure<T>(lastSequence, code.code(), ClientErrorMessages.of(code)),
output);
evidence.recordTermination(WebStreamTermination.TERMINAL_ERROR_RECORD, clock.instant());
return WebStreamTermination.TERMINAL_ERROR_RECORD;
@@ -0,0 +1,119 @@
package dev.caskeleton.adapter.inbound.web.advanced.mvc;
import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.AdmissionRefusedException;
import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.VirtualThreadAdmissionGuard;
import dev.caskeleton.adapter.inbound.web.error.EnvelopeResponseWriter;
import dev.caskeleton.adapter.inbound.web.http.ApiHeaders;
import dev.caskeleton.adapter.inbound.web.observability.RetryAfterAdvisor;
import jakarta.servlet.AsyncEvent;
import jakarta.servlet.AsyncListener;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Objects;
import org.springframework.core.Ordered;
import org.springframework.web.filter.OncePerRequestFilter;
import tools.jackson.databind.ObjectMapper;
/**
* Puts every request under the virtual-thread admission limit.
*
* <p>The guard alone was a bean nothing called: the profile promised a {@code 503} with {@code
* Retry-After} past the limit, and a deployment that switched it on admitted every arrival (review
* 2026-11-12). A filter, not an interceptor, so the limit covers the handler and its async work;
* ordered after the security chain (see {@link #ORDER}).
*
* <p>A request that goes async keeps its permit until the async work ends: releasing when this
* thread returns would bound only the hand-off, and the work the limit protects the downstream
* pools from happens after it.
*/
public final class VirtualThreadAdmissionFilter extends OncePerRequestFilter implements Ordered {
/**
* Right after the Spring Security filter chain (Boot's {@code SecurityProperties
* .DEFAULT_FILTER_ORDER}, -100). Two reasons. The chain applies CORS, so a cross-origin refusal
* carries {@code Access-Control-Allow-Origin} and the browser can read its 503 and {@code
* Retry-After}; in front of the chain it reached the page as a network error. And a request the
* chain refuses (unauthenticated, forbidden) never takes a permit from the admitted ones (review
* 2026-11-12).
*/
public static final int ORDER = -99;
private final VirtualThreadAdmissionGuard guard;
private final ObjectMapper objectMapper;
public VirtualThreadAdmissionFilter(
VirtualThreadAdmissionGuard guard, ObjectMapper objectMapper) {
this.guard = Objects.requireNonNull(guard, "guard");
this.objectMapper = Objects.requireNonNull(objectMapper, "objectMapper");
}
@Override
public int getOrder() {
return ORDER;
}
@Override
protected void doFilterInternal(
HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
VirtualThreadAdmissionGuard.Permit permit;
try {
permit = guard.enter();
} catch (AdmissionRefusedException refused) {
RetryAfterAdvisor.retryAfterSeconds(refused.errorCode())
.ifPresent(
seconds -> response.setHeader(ApiHeaders.RETRY_AFTER, Integer.toString(seconds)));
EnvelopeResponseWriter.write(response, refused.errorCode(), objectMapper);
return;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new ServletException("interrupted while waiting for admission", interrupted);
}
boolean handedToAsync = false;
try {
chain.doFilter(request, response);
if (request.isAsyncStarted()) {
request.getAsyncContext().addListener(new ReleaseWhenDone(permit));
handedToAsync = true;
}
} finally {
if (!handedToAsync) {
permit.close();
}
}
}
/** Releases the permit when the async request ends, however it ends. */
private static final class ReleaseWhenDone implements AsyncListener {
private final VirtualThreadAdmissionGuard.Permit permit;
ReleaseWhenDone(VirtualThreadAdmissionGuard.Permit permit) {
this.permit = permit;
}
@Override
public void onComplete(AsyncEvent event) {
permit.close();
}
@Override
public void onTimeout(AsyncEvent event) {
permit.close();
}
@Override
public void onError(AsyncEvent event) {
permit.close();
}
@Override
public void onStartAsync(AsyncEvent event) {
// A restarted async cycle drops the listeners of the previous one.
event.getAsyncContext().addListener(this);
}
}
}
@@ -13,6 +13,7 @@ import org.springframework.context.annotation.Bean;
import org.springframework.core.task.AsyncTaskExecutor;
import org.springframework.core.task.TaskDecorator;
import org.springframework.core.task.support.TaskExecutorAdapter;
import tools.jackson.databind.ObjectMapper;
/**
* Wires the virtual-thread executor and, in the same configuration, the admission limit.
@@ -57,6 +58,17 @@ public class VirtualThreadMvcConfiguration {
properties.getAdmissionLimit(), properties.getAdmissionWait());
}
/**
* The request path through the guard: without this the guard is a bean nothing calls, and the
* profile admits every arrival while promising a 503 past the limit.
*/
@Bean
@ConditionalOnMissingBean
public VirtualThreadAdmissionFilter virtualThreadAdmissionFilter(
VirtualThreadAdmissionGuard guard, ObjectMapper objectMapper) {
return new VirtualThreadAdmissionFilter(guard, objectMapper);
}
/**
* The executor Spring MVC dispatches async request handling onto.
*
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.advanced.patch;
import jakarta.validation.Validator;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
@@ -23,14 +24,19 @@ import tools.jackson.databind.node.ObjectNode;
public final class JsonMergePatchApplier {
private final ObjectMapper mapper;
private final Validator validator;
private final PatchFieldAuthorization authorization;
/**
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param authorization which fields may be modified
* @param validator the service's Bean Validation validator (Boot's {@code Validator} bean); the
* patched document is validated whole before it is returned
*/
public JsonMergePatchApplier(ObjectMapper mapper, PatchFieldAuthorization authorization) {
public JsonMergePatchApplier(
ObjectMapper mapper, PatchFieldAuthorization authorization, Validator validator) {
this.mapper = Objects.requireNonNull(mapper, "mapper");
this.validator = Objects.requireNonNull(validator, "validator");
this.authorization = Objects.requireNonNull(authorization, "authorization");
}
@@ -52,7 +58,8 @@ public final class JsonMergePatchApplier {
authorization.validate(patch.fieldNames());
JsonNode before = mapper.valueToTree(current);
if (!before.isObject()) {
throw new IllegalArgumentException("a merge patch target must serialize to a JSON object");
// The target type is the server's choice, so this is a server fault, not a bad request.
throw new IllegalStateException("a merge patch target must serialize to a JSON object");
}
ObjectNode after = merge((ObjectNode) before.deepCopy(), patch.root());
List<String> modified = new ArrayList<>();
@@ -63,7 +70,7 @@ public final class JsonMergePatchApplier {
modified.add(field);
}
}
return new PatchResult<>(mapper.treeToValue(after, type), modified);
return new PatchResult<>(PatchBodies.toTarget(mapper, validator, after, type), modified);
}
private static ObjectNode merge(ObjectNode target, ObjectNode patch) {
@@ -25,7 +25,7 @@ public record JsonMergePatchDocument(ObjectNode root) {
Objects.requireNonNull(root, "root");
int depth = depthOf(root, 1);
if (depth > MAX_DEPTH) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
"a merge patch nested "
+ depth
+ " deep exceeds the "
@@ -56,17 +56,17 @@ public record JsonMergePatchDocument(ObjectNode root) {
*
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param body the request body
* @throws IllegalArgumentException if the body is not a JSON object
* @throws JsonPatchRejectedException if the body is not JSON or not a JSON object
*/
public static JsonMergePatchDocument parse(ObjectMapper mapper, byte[] body) {
Objects.requireNonNull(mapper, "mapper");
Objects.requireNonNull(body, "body");
JsonNode parsed = mapper.readTree(body);
JsonNode parsed = PatchBodies.readTree(mapper, body);
if (!parsed.isObject()) {
// RFC 7396 permits a scalar or an array as a whole-document replacement. Refused here: a
// merge patch that replaces the entire resource is a PUT, and routing it through the patch
// path skips the full-document validation a PUT gets.
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
"a merge patch must be a JSON object; a scalar or array patch replaces the whole "
+ "resource, which is a PUT and belongs on the PUT route with its validation");
}
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.advanced.patch;
import jakarta.validation.Validator;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
@@ -27,14 +28,19 @@ import tools.jackson.databind.node.ObjectNode;
public final class JsonPatchApplier {
private final ObjectMapper mapper;
private final Validator validator;
private final JsonPointerAuthorization authorization;
/**
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param authorization which pointers may be modified
* @param validator the service's Bean Validation validator (Boot's {@code Validator} bean); the
* patched document is validated whole before it is returned
*/
public JsonPatchApplier(ObjectMapper mapper, JsonPointerAuthorization authorization) {
public JsonPatchApplier(
ObjectMapper mapper, JsonPointerAuthorization authorization, Validator validator) {
this.mapper = Objects.requireNonNull(mapper, "mapper");
this.validator = Objects.requireNonNull(validator, "validator");
this.authorization = Objects.requireNonNull(authorization, "authorization");
}
@@ -61,9 +67,9 @@ public final class JsonPatchApplier {
}
}
if (working.equals(before)) {
return new PatchResult<>(mapper.treeToValue(working, type), List.of());
return new PatchResult<>(PatchBodies.toTarget(mapper, validator, working, type), List.of());
}
return new PatchResult<>(mapper.treeToValue(working, type), touched);
return new PatchResult<>(PatchBodies.toTarget(mapper, validator, working, type), touched);
}
private JsonNode applyOne(JsonNode root, JsonPatchOperation operation) {
@@ -24,7 +24,7 @@ public record JsonPatchDocument(List<JsonPatchOperation> operations) {
public JsonPatchDocument {
operations = List.copyOf(Objects.requireNonNull(operations, "operations"));
if (operations.isEmpty()) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
"an empty patch document changes nothing; sending one is a client bug and answering 200 "
+ "hides it");
}
@@ -43,11 +43,12 @@ public record JsonPatchDocument(List<JsonPatchOperation> operations) {
*
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param body the request body
* @throws JsonPatchRejectedException if the body is not JSON or not a valid patch document
*/
public static JsonPatchDocument parse(ObjectMapper mapper, byte[] body) {
Objects.requireNonNull(mapper, "mapper");
Objects.requireNonNull(body, "body");
JsonNode root = mapper.readTree(body);
JsonNode root = PatchBodies.readTree(mapper, body);
if (!root.isArray()) {
throw new JsonPatchRejectedException(
"an RFC 6902 patch is an array of operations; an object here is a merge patch sent to "
@@ -26,22 +26,22 @@ public record JsonPatchOperation(
Objects.requireNonNull(value, "value");
Objects.requireNonNull(from, "from");
if (!path.isEmpty() && !path.startsWith("/")) {
throw new IllegalArgumentException("a JSON Pointer is empty or starts with '/': " + path);
throw new JsonPatchRejectedException("a JSON Pointer is empty or starts with '/': " + path);
}
if (kind.requiresValue() != value.isPresent()) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
kind.wireName()
+ (kind.requiresValue()
? " requires a value member"
: " carries no value member, and one here means the client meant a different op"));
}
if (kind.requiresFrom() != from.isPresent()) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
kind.wireName()
+ (kind.requiresFrom() ? " requires a from member" : " carries no from member"));
}
if (from.isPresent() && !from.get().isEmpty() && !from.get().startsWith("/")) {
throw new IllegalArgumentException("a JSON Pointer is empty or starts with '/'");
throw new JsonPatchRejectedException("a JSON Pointer is empty or starts with '/'");
}
if (kind == JsonPatchOperationKind.MOVE
&& from.isPresent()
@@ -49,7 +49,7 @@ public record JsonPatchOperation(
// RFC 6902 section 4.4: the target cannot be inside the source. Moving a subtree into itself
// is not a thing that has a result, and an implementation that tries produces either an
// infinite structure or a silently truncated one.
throw new IllegalArgumentException("a move cannot target a location inside its own source");
throw new JsonPatchRejectedException("a move cannot target a location inside its own source");
}
}
@@ -66,10 +66,21 @@ public final class JsonPointerAuthorization {
/**
* Check every pointer a document names, including {@code from} pointers.
*
* @throws PatchAuthorizationException naming all of them
* @throws JsonPatchRejectedException if a pointer is deeper than {@link #MAX_POINTER_DEPTH}: a
* malformed document, not a permission question
* @throws PatchAuthorizationException naming every pointer the caller may not modify
*/
public void validate(List<JsonPatchOperation> operations) {
Objects.requireNonNull(operations, "operations");
for (JsonPatchOperation operation : operations) {
boolean tooDeep =
depthOf(operation.path()) > MAX_POINTER_DEPTH
|| operation.from().filter(from -> depthOf(from) > MAX_POINTER_DEPTH).isPresent();
if (tooDeep) {
throw new JsonPatchRejectedException(
"a JSON Pointer deeper than " + MAX_POINTER_DEPTH + " segments is over the limit");
}
}
List<String> refused = new ArrayList<>();
for (JsonPatchOperation operation : operations) {
if (operation.kind().mutating() && !writable(operation.path())) {
@@ -0,0 +1,55 @@
package dev.caskeleton.adapter.inbound.web.advanced.patch;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import jakarta.validation.Validator;
import java.util.Set;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
/**
* The two places a patch meets Jackson, answered as the patch's fault rather than the server's.
*
* <p>A body that is not JSON, and a patched tree that no longer reads as the target type (a string
* where a number was), are both the client's document. Left to Jackson they reached the web
* adapter's catch-all as {@code 500 INTERNAL_ERROR}; here they are {@code 400 PATCH_REJECTED} like
* every other patch the server will not apply (review 2026-11-12).
*/
final class PatchBodies {
private PatchBodies() {}
static JsonNode readTree(ObjectMapper mapper, byte[] body) {
try {
return mapper.readTree(body);
} catch (JacksonException notJson) {
throw new JsonPatchRejectedException("the patch body is not a JSON document");
}
}
/**
* The patched tree as the target type, validated as a whole document.
*
* <p>Whole, not field by field: two fields whose values must agree are invisible to a check of
* the changed fields alone. {@code T} is the web representation DTO, whose constraints are
* request syntax (web AGENTS B4·C1); business rules such as allowed state transitions belong to
* the use case the caller hands the result to as a command. A violation is the same {@link
* ConstraintViolationException} a {@code @Valid} body raises, so the client gets {@code 400
* VALIDATION_FAILED} with the per-field details it already knows.
*/
static <T> T toTarget(ObjectMapper mapper, Validator validator, JsonNode patched, Class<T> type) {
T result;
try {
result = mapper.treeToValue(patched, type);
} catch (JacksonException wrongShape) {
throw new JsonPatchRejectedException(
"the patched document no longer reads as the resource: a value has the wrong type");
}
Set<ConstraintViolation<T>> violations = validator.validate(result);
if (!violations.isEmpty()) {
throw new ConstraintViolationException(violations);
}
return result;
}
}
@@ -38,6 +38,22 @@ public final class WebStreamEvidence {
return streamId;
}
/**
* Refuse a position before it is written: the same check {@link #recordDelivered} makes after the
* write, so a writer can keep a repeat or a rewind off the wire instead of only recording it.
*
* @throws IllegalStateException if the position does not advance, or the stream already ended
*/
public void requireNext(StreamSequence sequence) {
Objects.requireNonNull(sequence, "sequence");
lock.lock();
try {
requireAdvances(sequence);
} finally {
lock.unlock();
}
}
/**
* Record that an item reached the transport.
*
@@ -47,20 +63,7 @@ public final class WebStreamEvidence {
Objects.requireNonNull(sequence, "sequence");
lock.lock();
try {
if (termination != null) {
throw new IllegalStateException(
"an item was delivered after the stream ended as "
+ termination
+ "; the terminal envelope has already told the client there is nothing more");
}
if (lastDelivered != null && sequence.compareTo(lastDelivered) <= 0) {
throw new IllegalStateException(
"stream position went from "
+ lastDelivered.value()
+ " to "
+ sequence.value()
+ "; a client deduplicating on position would silently drop this item");
}
requireAdvances(sequence);
lastDelivered = sequence;
deliveredCount++;
} finally {
@@ -68,6 +71,24 @@ public final class WebStreamEvidence {
}
}
/** Callers hold the lock. */
private void requireAdvances(StreamSequence sequence) {
if (termination != null) {
throw new IllegalStateException(
"an item was delivered after the stream ended as "
+ termination
+ "; the terminal envelope has already told the client there is nothing more");
}
if (lastDelivered != null && sequence.compareTo(lastDelivered) <= 0) {
throw new IllegalStateException(
"stream position went from "
+ lastDelivered.value()
+ " to "
+ sequence.value()
+ "; a client deduplicating on position would silently drop this item");
}
}
/** Record how the stream ended. The first call wins; the end happens once. */
public void recordTermination(WebStreamTermination how, Instant at) {
Objects.requireNonNull(how, "how");
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.inbound.web.advanced.virtualthread;
import dev.caskeleton.adapter.inbound.web.advanced.error.WebAdvancedError;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
/**
* An arrival was refused because the concurrency limit was full.
@@ -27,9 +27,12 @@ public final class AdmissionRefusedException extends RuntimeException implements
return limit;
}
/** {@link WebAdvancedError#ADMISSION_REFUSED}; see the leaf README for the client contract. */
/**
* {@link OperationalError#SERVER_BUSY}, the one code every transport answers server saturation
* with; see the leaf README for the client contract.
*/
@Override
public ApiErrorCode errorCode() {
return WebAdvancedError.ADMISSION_REFUSED;
return OperationalError.SERVER_BUSY;
}
}
@@ -4,6 +4,7 @@ import java.time.Duration;
import java.util.Objects;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
@@ -57,17 +58,42 @@ public final class VirtualThreadAdmissionGuard {
*/
public <T> T run(java.util.concurrent.Callable<T> work) throws Exception {
Objects.requireNonNull(work, "work");
try (Permit permit = enter()) {
return work.call();
}
}
/**
* Take a permit for work that does not end on this thread, such as an async request.
*
* @return the permit; closing it releases, and closing it twice releases once
* @throws AdmissionRefusedException if no permit became available in time
* @throws InterruptedException if interrupted while waiting
*/
public Permit enter() throws InterruptedException {
if (!permits.tryAcquire(acquireTimeout.toMillis(), TimeUnit.MILLISECONDS)) {
rejected.incrementAndGet();
throw new AdmissionRefusedException(limit);
}
int current = active.incrementAndGet();
peakActive.accumulateAndGet(current, Math::max);
try {
return work.call();
} finally {
active.decrementAndGet();
permits.release();
return new Permit();
}
/** One admitted unit of work. */
public final class Permit implements AutoCloseable {
private final AtomicBoolean released = new AtomicBoolean();
private Permit() {}
/** Release, once. An async request ends through more than one listener callback. */
@Override
public void close() {
if (released.compareAndSet(false, true)) {
active.decrementAndGet();
permits.release();
}
}
}
@@ -62,7 +62,7 @@ class WebAdvancedErrorMappingTest {
static Stream<Arguments> documentedMappings() {
return Stream.of(
Arguments.of("admission", 503, "ADMISSION_REFUSED", "TRANSIENT_DEPENDENCY", true),
Arguments.of("admission", 503, "SERVER_BUSY", "TRANSIENT_DEPENDENCY", true),
Arguments.of("patch-test", 409, "PATCH_TEST_FAILED", "CONFLICT", false),
Arguments.of("patch-rejected", 400, "PATCH_REJECTED", "VALIDATION", false),
Arguments.of("patch-forbidden", 403, "PATCH_PATH_FORBIDDEN", "AUTHZ", false),
@@ -68,6 +68,7 @@ class MvcAdvancedConfigurationTest {
.hasNotFailed()
.doesNotHaveBean(StreamRecordEncoder.class)
.doesNotHaveBean(VirtualThreadAdmissionGuard.class)
.doesNotHaveBean(VirtualThreadAdmissionFilter.class)
.doesNotHaveBean(AsyncTaskExecutor.class));
}
@@ -125,6 +126,7 @@ class MvcAdvancedConfigurationTest {
.hasNotFailed()
.hasSingleBean(VirtualThreadProfile.class)
.hasSingleBean(VirtualThreadAdmissionGuard.class)
.hasSingleBean(VirtualThreadAdmissionFilter.class)
.hasBean("applicationTaskExecutor");
assertThat(context.getBean(VirtualThreadAdmissionGuard.class).limit()).isEqualTo(100);
assertThat(context.getBean(VirtualThreadProfile.class).databasePoolSize())
@@ -92,7 +92,10 @@ class MvcStreamingWiringTest {
writer.write(failingAfter(NdjsonRecord.item(1, "a")), output, evidence);
assertThat(how).isEqualTo(WebStreamTermination.TERMINAL_ERROR_RECORD);
assertThat(output.text()).contains("DEPENDENCY_FAILURE");
assertThat(output.text())
.as("a failure without a code of its own is the registered INTERNAL_ERROR")
.contains("\"code\":\"INTERNAL_ERROR\"")
.doesNotContain("DEPENDENCY_FAILURE");
assertThat(evidence.termination()).contains(WebStreamTermination.TERMINAL_ERROR_RECORD);
}
@@ -129,6 +132,58 @@ class MvcStreamingWiringTest {
.hasMessageContaining("exceeds the 16 byte ceiling");
}
@Test
@DisplayName("commit 뒤 실패 기록은 실패한 예외의 코드와 고정 문구를 싣는다")
void aTerminalRecordCarriesTheFailuresOwnCode() {
// given
CountingStream output = new CountingStream();
WebStreamPolicy small =
new WebStreamPolicy(
Duration.ofSeconds(15), Duration.ofSeconds(60), Duration.ofMinutes(30), 8, 200);
MvcStreamWriter writer =
new MvcStreamWriter(encoder(small), StreamFraming.NDJSON, Clock.systemUTC());
WebStreamEvidence evidence = new WebStreamEvidence(new StreamId("feed"), NOW);
// when
WebStreamTermination how =
writer.write(
List.<NdjsonRecord<String>>of(
NdjsonRecord.item(1, "a"), NdjsonRecord.item(2, "x".repeat(1_000)))
.iterator(),
output,
evidence);
// then
assertThat(how).isEqualTo(WebStreamTermination.TERMINAL_ERROR_RECORD);
assertThat(output.text())
.contains("\"code\":\"STREAM_ITEM_TOO_LARGE\"")
.contains(dev.caskeleton.shared.error.ClientErrorMessages.OPAQUE);
}
@Test
@DisplayName("위치가 앞 항목보다 크지 않으면 서버 오류로 끝내고 그 항목은 쓰지 않는다")
void aRepeatedPositionEndsTheStreamInsteadOfReachingTheClient() {
// given
CountingStream output = new CountingStream();
MvcStreamWriter writer =
new MvcStreamWriter(
encoder(WebStreamPolicy.conventional()), StreamFraming.NDJSON, Clock.systemUTC());
WebStreamEvidence evidence = new WebStreamEvidence(new StreamId("feed"), NOW);
// when
WebStreamTermination how =
writer.write(
List.<NdjsonRecord<String>>of(
NdjsonRecord.item(1, "a"), NdjsonRecord.item(2, "b"), NdjsonRecord.item(2, "c"))
.iterator(),
output,
evidence);
// then
assertThat(how).isEqualTo(WebStreamTermination.TERMINAL_ERROR_RECORD);
assertThat(output.text()).doesNotContain("\"c\"").contains("\"code\":\"INTERNAL_ERROR\"");
}
/** A stream that counts flushes and can fail on a chosen write. */
private static final class CountingStream extends OutputStream {
@@ -0,0 +1,150 @@
package dev.caskeleton.adapter.inbound.web.advanced.mvc;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.AdmissionRefusedException;
import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.VirtualThreadAdmissionGuard;
import jakarta.servlet.AsyncEvent;
import jakarta.servlet.AsyncListener;
import java.time.Duration;
import java.util.concurrent.atomic.AtomicInteger;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.springframework.mock.web.MockAsyncContext;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import tools.jackson.databind.json.JsonMapper;
/**
* The request path through the admission guard.
*
* <p>required_test: {@code contract-verification:server-saturation} — a full limit answers the
* shared {@code SERVER_BUSY} 503 with {@code Retry-After}, before any handler runs.
*/
@Tag("web-advanced")
class VirtualThreadAdmissionFilterTest {
@Test
@DisplayName("한도가 차면 요청은 controller에 닿지 않고 503 SERVER_BUSY와 Retry-After를 받는다")
void aFullLimitRefusesWith503AndRetryAfter() throws Exception {
// given
VirtualThreadAdmissionGuard guard = new VirtualThreadAdmissionGuard(1, Duration.ZERO);
VirtualThreadAdmissionFilter filter =
new VirtualThreadAdmissionFilter(guard, JsonMapper.shared());
AtomicInteger reached = new AtomicInteger();
MockHttpServletResponse response = new MockHttpServletResponse();
// when
try (VirtualThreadAdmissionGuard.Permit held = guard.enter()) {
filter.doFilter(
new MockHttpServletRequest("GET", "/orders"),
response,
(request, servletResponse) -> reached.incrementAndGet());
}
// then
assertThat(reached).as("the guard was a bean nothing called").hasValue(0);
assertThat(response.getStatus()).isEqualTo(503);
assertThat(response.getHeader("Retry-After")).isEqualTo("1");
assertThat(response.getContentAsString()).contains("SERVER_BUSY");
assertThat(guard.rejectedCount()).isEqualTo(1);
}
@Test
@DisplayName("동기 요청은 끝나면 permit을 돌려준다")
void aSynchronousRequestReleasesItsPermit() throws Exception {
// given
VirtualThreadAdmissionGuard guard = new VirtualThreadAdmissionGuard(1, Duration.ZERO);
VirtualThreadAdmissionFilter filter =
new VirtualThreadAdmissionFilter(guard, JsonMapper.shared());
AtomicInteger activeInside = new AtomicInteger(-1);
// when
filter.doFilter(
new MockHttpServletRequest("GET", "/orders"),
new MockHttpServletResponse(),
(request, response) -> activeInside.set(guard.active()));
// then
assertThat(activeInside).hasValue(1);
assertThat(guard.active()).isZero();
}
@Test
@DisplayName("async 요청은 async 일이 끝날 때까지 permit을 쥔다")
void anAsyncRequestHoldsItsPermitUntilTheAsyncWorkEnds() throws Exception {
// given
VirtualThreadAdmissionGuard guard = new VirtualThreadAdmissionGuard(1, Duration.ZERO);
VirtualThreadAdmissionFilter filter =
new VirtualThreadAdmissionFilter(guard, JsonMapper.shared());
MockHttpServletRequest request = new MockHttpServletRequest("GET", "/orders");
request.setAsyncSupported(true);
MockHttpServletResponse response = new MockHttpServletResponse();
// when
filter.doFilter(request, response, (req, res) -> request.startAsync(req, res));
int activeAfterHandOff = guard.active();
request.getAsyncContext().complete();
// then
assertThat(activeAfterHandOff)
.as("releasing on hand-off would bound only the hand-off, not the work")
.isEqualTo(1);
assertThat(guard.active()).isZero();
}
@Test
@DisplayName("async 시간 초과 뒤 완료가 또 와도 permit은 한 번만 돌아가 상한이 늘지 않는다")
void aTimeoutFollowedByCompletionReleasesThePermitOnce() throws Exception {
// given
VirtualThreadAdmissionGuard guard = new VirtualThreadAdmissionGuard(1, Duration.ZERO);
VirtualThreadAdmissionFilter filter =
new VirtualThreadAdmissionFilter(guard, JsonMapper.shared());
MockHttpServletRequest request = new MockHttpServletRequest("GET", "/orders");
request.setAsyncSupported(true);
filter.doFilter(
request, new MockHttpServletResponse(), (req, res) -> request.startAsync(req, res));
MockAsyncContext async = (MockAsyncContext) request.getAsyncContext();
AsyncEvent event = new AsyncEvent(async);
// when — a container calls onTimeout, then onComplete, for one timed-out request
for (AsyncListener listener : async.getListeners()) {
listener.onTimeout(event);
listener.onComplete(event);
}
// then
assertThat(guard.active()).isZero();
try (VirtualThreadAdmissionGuard.Permit only = guard.enter()) {
assertThat(catchThrowable(guard::enter))
.as("a permit released twice would let a second request past a limit of one")
.isInstanceOf(AdmissionRefusedException.class);
}
}
@Test
@DisplayName("async가 다시 시작되면 새 cycle에도 permit을 돌려주는 listener가 붙는다")
void aRestartedAsyncCycleKeepsTheReleaseListener() throws Exception {
// given
VirtualThreadAdmissionGuard guard = new VirtualThreadAdmissionGuard(1, Duration.ZERO);
VirtualThreadAdmissionFilter filter =
new VirtualThreadAdmissionFilter(guard, JsonMapper.shared());
MockHttpServletRequest request = new MockHttpServletRequest("GET", "/orders");
request.setAsyncSupported(true);
MockHttpServletResponse response = new MockHttpServletResponse();
filter.doFilter(request, response, (req, res) -> request.startAsync(req, res));
MockAsyncContext first = (MockAsyncContext) request.getAsyncContext();
MockAsyncContext restarted = new MockAsyncContext(request, response);
// when
for (AsyncListener listener : first.getListeners()) {
listener.onStartAsync(new AsyncEvent(restarted));
}
restarted.complete();
// then
assertThat(guard.active()).isZero();
}
}
@@ -2,7 +2,12 @@ package dev.caskeleton.adapter.inbound.web.advanced.patch;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import jakarta.validation.ConstraintViolationException;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.constraints.NotNull;
import java.nio.charset.StandardCharsets;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;
@@ -20,12 +25,15 @@ import tools.jackson.databind.json.JsonMapper;
class JsonMergePatchApplierTest {
private static final ObjectMapper MAPPER = JsonMapper.shared();
private static final Validator VALIDATOR =
Validation.buildDefaultValidatorFactory().getValidator();
/** A target with a mandatory field and two optional ones. */
record Profile(String displayName, String description, String nickname) {}
private static JsonMergePatchApplier applier(String... writableFields) {
return new JsonMergePatchApplier(MAPPER, PatchFieldAuthorization.allow(writableFields));
return new JsonMergePatchApplier(
MAPPER, PatchFieldAuthorization.allow(writableFields), VALIDATOR);
}
private static JsonMergePatchDocument patch(String json) {
@@ -118,7 +126,7 @@ class JsonMergePatchApplierTest {
// A whole-document replacement is a PUT, and routing it through the patch path skips the
// full-document validation a PUT gets.
assertThatThrownBy(() -> patch("[1,2,3]"))
.isInstanceOf(IllegalArgumentException.class)
.isInstanceOf(JsonPatchRejectedException.class)
.hasMessageContaining("belongs on the PUT route");
}
@@ -135,7 +143,7 @@ class JsonMergePatchApplierTest {
deep.append("}".repeat(40));
assertThatThrownBy(() -> patch(deep.toString()))
.isInstanceOf(IllegalArgumentException.class)
.isInstanceOf(JsonPatchRejectedException.class)
.hasMessageContaining("can turn into a 400");
}
@@ -153,4 +161,38 @@ class JsonMergePatchApplierTest {
assertThat(PatchMediaType.MERGE_PATCH).isEqualTo("application/merge-patch+json");
assertThat(PatchMediaType.JSON_PATCH).isEqualTo("application/json-patch+json");
}
@Test
@DisplayName("JSON이 아닌 merge patch 본문은 400 PATCH_REJECTED로 거절된다")
void aMergePatchBodyThatIsNotJsonIsRejected() {
// given
String notJson = "displayName=new";
// when
Throwable thrown = catchThrowable(() -> patch(notJson));
// then
assertThat(thrown).isInstanceOf(JsonPatchRejectedException.class);
}
/** A target whose field may be patched but not deleted. */
record Required(@NotNull String displayName, String nickname) {}
@Test
@DisplayName("merge patch 결과는 문서 전체로 검증되고 위반은 VALIDATION_FAILED가 받는 예외로 나간다")
void theMergedDocumentIsValidatedWhole() {
// given
JsonMergePatchApplier applier =
new JsonMergePatchApplier(MAPPER, PatchFieldAuthorization.allow("displayName"), VALIDATOR);
JsonMergePatchDocument deleting = patch("{\"displayName\":null}");
// when
Throwable thrown =
catchThrowable(() -> applier.apply(new Required("old", "n"), deleting, Required.class));
// then
assertThat(thrown)
.as("the patch is allowed field by field; only the whole document breaks the constraint")
.isInstanceOf(ConstraintViolationException.class);
}
}
@@ -2,7 +2,12 @@ package dev.caskeleton.adapter.inbound.web.advanced.patch;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import jakarta.validation.ConstraintViolationException;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.constraints.NotBlank;
import java.nio.charset.StandardCharsets;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
@@ -21,6 +26,8 @@ import tools.jackson.databind.json.JsonMapper;
class JsonPatchApplierTest {
private static final ObjectMapper MAPPER = JsonMapper.shared();
private static final Validator VALIDATOR =
Validation.buildDefaultValidatorFactory().getValidator();
/** A target with a scalar, a nested object and a list. */
record Profile(String displayName, int version, Address address, List<String> tags) {}
@@ -33,7 +40,8 @@ class JsonPatchApplierTest {
}
private static JsonPatchApplier applier(String... writablePrefixes) {
return new JsonPatchApplier(MAPPER, JsonPointerAuthorization.allow(writablePrefixes));
return new JsonPatchApplier(
MAPPER, JsonPointerAuthorization.allow(writablePrefixes), VALIDATOR);
}
private static JsonPatchDocument patch(String json) {
@@ -212,10 +220,10 @@ class JsonPatchApplierTest {
// Discovered halfway through, it would be a document that has already modified the working
// copy.
assertThatThrownBy(() -> patch("[{\"op\":\"replace\",\"path\":\"/displayName\"}]"))
.isInstanceOf(IllegalArgumentException.class)
.isInstanceOf(JsonPatchRejectedException.class)
.hasMessageContaining("requires a value member");
assertThatThrownBy(() -> patch("[{\"op\":\"move\",\"path\":\"/displayName\"}]"))
.isInstanceOf(IllegalArgumentException.class)
.isInstanceOf(JsonPatchRejectedException.class)
.hasMessageContaining("requires a from member");
}
@@ -224,7 +232,7 @@ class JsonPatchApplierTest {
void moveIntoOwnSourceIsRefused() {
assertThatThrownBy(
() -> patch("[{\"op\":\"move\",\"from\":\"/address\",\"path\":\"/address/self\"}]"))
.isInstanceOf(IllegalArgumentException.class)
.isInstanceOf(JsonPatchRejectedException.class)
.hasMessageContaining("inside its own source");
}
@@ -232,7 +240,75 @@ class JsonPatchApplierTest {
@DisplayName("an empty patch document is refused")
void emptyDocumentIsRefused() {
assertThatThrownBy(() -> patch("[]"))
.isInstanceOf(IllegalArgumentException.class)
.isInstanceOf(JsonPatchRejectedException.class)
.hasMessageContaining("client bug");
}
@Test
@DisplayName("JSON이 아닌 본문은 400 PATCH_REJECTED로 거절된다")
void aBodyThatIsNotJsonIsRejectedAsAPatch() {
// given
String notJson = "op=replace&path=/displayName";
// when
Throwable thrown = catchThrowable(() -> patch(notJson));
// then
assertThat(thrown)
.as("left to Jackson the parse error reached the catch-all as 500 INTERNAL_ERROR")
.isInstanceOf(JsonPatchRejectedException.class);
}
@Test
@DisplayName("너무 깊은 pointer는 권한 거절(403)이 아니라 문서 거절(400)이다")
void aTooDeepPointerIsAMalformedDocumentNotAPermissionRefusal() {
// given
String deep = "/displayName" + "/x".repeat(JsonPointerAuthorization.MAX_POINTER_DEPTH);
JsonPatchDocument document =
patch("[{\"op\":\"replace\",\"path\":\"" + deep + "\",\"value\":\"v\"}]");
// when
Throwable thrown =
catchThrowable(() -> applier("/displayName").apply(profile(), document, Profile.class));
// then
assertThat(thrown).isInstanceOf(JsonPatchRejectedException.class);
}
@Test
@DisplayName("patch 결과가 대상 타입으로 읽히지 않으면 400 PATCH_REJECTED다")
void aPatchThatBreaksTheTargetTypeIsRejected() {
// given
JsonPatchDocument document =
patch("[{\"op\":\"replace\",\"path\":\"/version\",\"value\":\"not-a-number\"}]");
// when
Throwable thrown =
catchThrowable(() -> applier("/version").apply(profile(), document, Profile.class));
// then
assertThat(thrown).isInstanceOf(JsonPatchRejectedException.class);
}
/** A target with a constraint across the whole document. */
record Named(@NotBlank String displayName, String nickname) {}
@Test
@DisplayName("patch 결과는 문서 전체로 검증되고 위반은 VALIDATION_FAILED가 받는 예외로 나간다")
void thePatchedDocumentIsValidatedWhole() {
// given
JsonPatchApplier applier =
new JsonPatchApplier(MAPPER, JsonPointerAuthorization.allow("/displayName"), VALIDATOR);
JsonPatchDocument blanking =
patch("[{\"op\":\"replace\",\"path\":\"/displayName\",\"value\":\" \"}]");
// when
Throwable thrown =
catchThrowable(() -> applier.apply(new Named("old", "n"), blanking, Named.class));
// then
assertThat(thrown)
.as("each operation is well formed, and only the whole document breaks the constraint")
.isInstanceOf(ConstraintViolationException.class);
}
}
@@ -58,7 +58,7 @@ public final class BlockingTransferExecutor {
throw new FileserverException(
"transfer pool is saturated",
rejected,
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
FileserverFailureContext.of(FileserverErrorCode.SERVER_BUSY, true));
}
try {
return future.get(awaitSeconds, TimeUnit.SECONDS);
@@ -36,7 +36,9 @@ public class FileserverHttpSurfaceConfiguration {
/**
* The response headers the upload and download routes write that a cross-origin browser must be
* allowed to read: without {@code Upload-Offset} a tus or draft-12 client cannot resume.
* allowed to read: without {@code Upload-Offset} a tus or draft-12 client cannot resume, and
* without {@code Content-Range} a browser that resumes a download with {@code Range} cannot tell
* which bytes a {@code 206} carries or how long the representation is from a {@code 416}.
*/
@Bean
CorsExposedHeaders fileserverCorsExposedHeaders() {
@@ -53,6 +55,7 @@ public class FileserverHttpSurfaceConfiguration {
Draft12Headers.UPLOAD_COMPLETE,
Draft12Headers.UPLOAD_LIMIT,
HttpHeaders.CONTENT_DISPOSITION,
HttpHeaders.ACCEPT_RANGES));
HttpHeaders.ACCEPT_RANGES,
HttpHeaders.CONTENT_RANGE));
}
}
@@ -4,12 +4,12 @@ import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.config.BlockingTransferExecutor;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.BatchUploadItemResult;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.BatchUploadResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.MultipartUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.UploadIntent;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.adapter.inbound.web.observability.ResponseMetaFactory;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
@@ -21,6 +21,9 @@ import dev.caskeleton.application.fileserver.port.in.UploadFileUseCase;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.shared.response.BulkEnvelope;
import dev.caskeleton.shared.response.BulkItemResult;
import dev.caskeleton.shared.response.ResponseMeta;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.io.InputStream;
@@ -117,23 +120,41 @@ public class FileUploadController {
/**
* Bounded multi-file upload.
*
* <p>The batch is explicitly non-atomic: each part is an independent file, a failure never rolls
* back a sibling that already succeeded, and the response is always {@code 200} carrying the
* ordered per-part outcome.
* <p>The batch is explicitly non-atomic: each part is an independent file and a failure never
* rolls back a sibling that already succeeded. The response is {@code 200} and the shared bulk
* envelope (web AGENTS B8): every part succeeded → {@code success = true} and {@code results};
* any part failed → {@code success = false}, {@code BATCH_PARTIAL_FAILURE} and the per-part
* outcome in {@code error.details[]}. It used to answer {@code success = true} with the failures
* inside {@code data}, so a client reading the discriminator saw a batch that worked (review
* 2026-11-12).
*/
@PostMapping(
path = "/v1/files:batch",
consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<BatchUploadResponse> uploadBatch(
public ResponseEntity<BulkEnvelope<BatchUploadItemResult>> uploadBatch(
@RequestParam("files") List<MultipartFile> files) {
requirePartCountWithinPolicy(files.size());
RequestContext context = contextFactory.current();
List<BatchUploadItemResult> results = new ArrayList<>(files.size());
List<PartOutcome> outcomes = new ArrayList<>(files.size());
for (int index = 0; index < files.size(); index++) {
results.add(uploadPart(files.get(index), index, context));
outcomes.add(uploadPart(files.get(index), index, context));
}
ResponseMeta meta = ResponseMetaFactory.fromMdc();
if (outcomes.stream().allMatch(PartOutcome::succeeded)) {
return ResponseEntity.ok(
BulkEnvelope.allOk(outcomes.stream().map(PartOutcome::result).toList(), meta));
}
return ResponseEntity.ok(
BulkEnvelope.partial(outcomes.stream().map(PartOutcome::detail).toList(), meta));
}
/** One part's result in both shapes the bulk envelope may need. */
private record PartOutcome(BatchUploadItemResult result, BulkItemResult detail) {
boolean succeeded() {
return result.error() == null;
}
return ResponseEntity.ok(new BatchUploadResponse(results));
}
/**
@@ -142,7 +163,7 @@ public class FileUploadController {
* <p>A part failure is converted to a per-part problem instead of aborting the request, which is
* what makes the endpoint's non-atomic contract observable rather than merely documented.
*/
private BatchUploadItemResult uploadPart(MultipartFile part, int index, RequestContext context) {
private PartOutcome uploadPart(MultipartFile part, int index, RequestContext context) {
String clientPartId = partId(part, index);
try (InputStream body = part.getInputStream()) {
UploadIntent intent = multipartMapper.map(part);
@@ -150,14 +171,21 @@ public class FileUploadController {
FileView view =
transferExecutor.call(
() -> upload(intent, content, part.getSize(), context, UploadMode.BATCH));
return BatchUploadItemResult.accepted(clientPartId, view);
return new PartOutcome(
BatchUploadItemResult.accepted(clientPartId, view),
BulkItemResult.ok(index, view.fileId().canonicalText()));
} catch (FileserverException failure) {
return BatchUploadItemResult.rejected(clientPartId, failure.code());
return rejected(clientPartId, index, failure.code());
} catch (IOException failure) {
return BatchUploadItemResult.rejected(clientPartId, FileserverErrorCode.STORAGE_UNAVAILABLE);
return rejected(clientPartId, index, FileserverErrorCode.STORAGE_UNAVAILABLE);
}
}
private static PartOutcome rejected(String clientPartId, int index, FileserverErrorCode code) {
return new PartOutcome(
BatchUploadItemResult.rejected(clientPartId, code), BulkItemResult.error(index, code));
}
/**
* Records the application upload mode represented by this HTTP endpoint.
*
@@ -239,8 +239,9 @@ public class Draft12UploadController {
}
}
/** The header's name, or empty: the application's {@code OriginalFilenamePolicy} names it. */
private static String filename(HttpServletRequest request) {
String header = request.getHeader("X-Filename");
return header == null || header.isBlank() ? "upload.bin" : header;
return header == null ? "" : header;
}
}
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.shared.error.ClientErrorMessages;
@@ -12,7 +13,11 @@ import dev.caskeleton.shared.response.ApiError;
* rolls back a sibling that already succeeded. A rejected part carries the same {@link ApiError}
* the single-file endpoints put in their Envelope: stable code, category, the shared client message
* and {@code retryable}. The server-side message never crosses this boundary.
*
* <p>Absent members are omitted on the wire, like every envelope field (http-contract §1): an
* accepted part has no {@code error} key rather than {@code "error": null}.
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public record BatchUploadItemResult(
String clientPartId, String status, String fileId, ApiError error) {
@@ -1,21 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import java.util.List;
/**
* Ordered per-part outcome of one batch upload.
*
* <p>The endpoint answers {@code 200} even when some parts failed: the batch has no request-wide
* atomicity, and pretending otherwise with a single status would hide the parts that succeeded.
*/
public record BatchUploadResponse(List<BatchUploadItemResult> results) {
public BatchUploadResponse {
results = List.copyOf(results);
}
/** True when every part succeeded, which the envelope layer reports as a plain success. */
public boolean fullySucceeded() {
return results.stream().allMatch(result -> result.error() == null);
}
}
@@ -13,16 +13,18 @@ import org.springframework.web.multipart.MultipartFile;
*/
public final class MultipartUploadRequestMapper {
private static final String FALLBACK_FILENAME = "upload.bin";
public UploadIntent map(MultipartFile part) {
return new UploadIntent(
filename(part), claimedMediaType(part), OptionalLong.of(part.getSize()), Optional.empty());
}
/**
* The submitted name, or empty when there is none. Naming an unnamed upload is the application's
* {@code OriginalFilenamePolicy}, one place for every transport (review 2026-11-12).
*/
private static String filename(MultipartFile part) {
String submitted = part.getOriginalFilename();
return submitted == null || submitted.isBlank() ? FALLBACK_FILENAME : submitted;
return submitted == null ? "" : submitted;
}
private static Optional<String> claimedMediaType(MultipartFile part) {
@@ -20,8 +20,6 @@ public final class RawUploadRequestMapper {
public static final String FILENAME_HEADER = "X-Filename";
public static final String DIGEST_HEADER = "X-Content-Sha256";
private static final String FALLBACK_FILENAME = "upload.bin";
private final boolean contentLengthRequired;
public RawUploadRequestMapper(boolean contentLengthRequired) {
@@ -39,9 +37,10 @@ public final class RawUploadRequestMapper {
filename(request), claimedMediaType(request), declaredLength, digest(request));
}
/** The header's name, or empty: the application's {@code OriginalFilenamePolicy} names it. */
private static String filename(HttpServletRequest request) {
String header = request.getHeader(FILENAME_HEADER);
return header == null || header.isBlank() ? FALLBACK_FILENAME : header;
return header == null ? "" : header;
}
private static Optional<String> claimedMediaType(HttpServletRequest request) {
@@ -1,10 +1,13 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import dev.caskeleton.adapter.inbound.web.error.ErrorResponseFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpRangeNotSatisfiableException;
import dev.caskeleton.adapter.inbound.web.observability.RetryAfterAdvisor;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.OptionalInt;
/**
* The headers a Fileserver failure carries, owned once for every transport.
@@ -31,7 +34,6 @@ public final class FileserverProblemHeaders {
Map.of(
FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, 1,
FileserverErrorCode.STORAGE_UNAVAILABLE, 30,
FileserverErrorCode.ATOMIC_PUBLISH_UNSUPPORTED, 30,
FileserverErrorCode.TRANSFER_TIMEOUT, 5,
FileserverErrorCode.FILE_NOT_READY, 2,
FileserverErrorCode.CONCURRENT_MODIFICATION, 1);
@@ -45,11 +47,17 @@ public final class FileserverProblemHeaders {
*/
public static Map<String, String> of(FileserverException failure) {
Map<String, String> headers = new LinkedHashMap<>();
Integer retryAfter = RETRY_AFTER_SECONDS.get(failure.code());
// Only a failure the server itself called retryable advertises a retry: telling a client to
// come back after a permanent rejection is worse than saying nothing.
if (retryAfter != null && failure.context().retryable()) {
headers.put("Retry-After", String.valueOf(retryAfter));
// come back after a permanent rejection is worse than saying nothing. The body's own rule
// (ErrorResponseFactory.effectiveRetryable): the occurrence can only narrow its code, so a code
// that is never retryable never carries the header, whatever the occurrence said. A code that
// shares its name with an operational one (SERVER_BUSY) takes the registry's value from
// RetryAfterAdvisor rather than a second copy here.
if (ErrorResponseFactory.effectiveRetryable(failure.code(), failure.context().retryable())) {
Integer own = RETRY_AFTER_SECONDS.get(failure.code());
OptionalInt seconds =
own != null ? OptionalInt.of(own) : RetryAfterAdvisor.retryAfterSeconds(failure.code());
seconds.ifPresent(value -> headers.put("Retry-After", String.valueOf(value)));
}
if (failure instanceof HttpRangeNotSatisfiableException unsatisfiable) {
headers.put("Content-Range", "bytes */" + unsatisfiable.representationLength());
@@ -112,7 +112,8 @@ public class TusController {
create.handle(
new CreateUploadCommand(
new CreateUploadRequest(
parser.filename(request).orElse("upload.bin"),
// Empty when absent: OriginalFilenamePolicy names it, for every transport.
parser.filename(request).orElse(""),
Optional.ofNullable(parser.metadata(request).get("filetype")),
parser.declaredLength(request),
Optional.empty(),
@@ -9,7 +9,7 @@ import org.junit.jupiter.api.Test;
class FileserverCorsExposedHeadersTest {
@Test
@DisplayName("fileserver HTTP 표면은 업로드 재개에 필요한 헤더를 CORS 노출 목록에 기여한다")
@DisplayName("fileserver HTTP 표면은 업로드·다운로드 재개에 필요한 헤더를 CORS 노출 목록에 기여한다")
void theSurfaceContributesTheHeadersAResumingClientMustRead() {
// when
CorsExposedHeaders contributed =
@@ -23,6 +23,7 @@ class FileserverCorsExposedHeadersTest {
"Upload-Length",
"Upload-Expires",
"Upload-Complete",
"Content-Disposition");
"Content-Disposition",
"Content-Range");
}
}
@@ -23,6 +23,7 @@ class MvcUploadExecutorSaturationTest {
BlockingTransferExecutor executor = new BlockingTransferExecutor(pool, bounds.awaitSeconds());
CountDownLatch release = new CountDownLatch(1);
AtomicInteger rejections = new AtomicInteger();
CountDownLatch firstRejection = new CountDownLatch(1);
List<Thread> callers = new ArrayList<>();
for (int index = 0; index < 8; index++) {
@@ -34,21 +35,25 @@ class MvcUploadExecutorSaturationTest {
} catch (FileserverException failure) {
// A caller that outlived the budget (TRANSFER_TIMEOUT) is not a saturation
// signal; only an admission rejection is.
if (failure.code() == FileserverErrorCode.TRANSFER_ADMISSION_REJECTED) {
if (failure.code() == FileserverErrorCode.SERVER_BUSY) {
rejections.incrementAndGet();
firstRejection.countDown();
}
}
});
callers.add(caller);
caller.start();
}
Thread.sleep(200);
// Held until the pool has refused someone, rather than for a guessed 200 ms: under load the
// callers may not have arrived yet, and then the release lets every one of them through.
boolean refused = firstRejection.await(10, TimeUnit.SECONDS);
release.countDown();
for (Thread caller : callers) {
caller.join(TimeUnit.SECONDS.toMillis(10));
}
pool.shutdown();
assertThat(refused).as("a pool of 1 with a queue of 1 refused within the wait").isTrue();
assertThat(rejections.get())
.as("a pool of 1 with a queue of 1 cannot absorb 8 concurrent transfers")
.isPositive();
@@ -102,8 +107,7 @@ class MvcUploadExecutorSaturationTest {
.satisfies(
failure -> {
FileserverException rejected = (FileserverException) failure;
assertThat(rejected.code())
.isEqualTo(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED);
assertThat(rejected.code()).isEqualTo(FileserverErrorCode.SERVER_BUSY);
assertThat(rejected.context().retryable()).isTrue();
});
}
@@ -115,7 +119,10 @@ class MvcUploadExecutorSaturationTest {
BlockingTransferExecutor executor = new BlockingTransferExecutor(pool, bounds.awaitSeconds());
assertThatThrownBy(() -> executor.call(() -> await(new CountDownLatch(1))))
.isInstanceOf(FileserverException.class);
.isInstanceOf(FileserverException.class)
.extracting(failure -> ((FileserverException) failure).code())
.as("the overrun is answered as the timeout it is, not as some other transfer failure")
.isEqualTo(FileserverErrorCode.TRANSFER_TIMEOUT);
pool.shutdown();
}
@@ -7,6 +7,7 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.envelope.EnvelopeWireFormatConfig;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.MultipartUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
@@ -17,12 +18,19 @@ import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import java.nio.charset.StandardCharsets;
import java.util.Set;
import java.util.TreeSet;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.http.converter.json.JacksonJsonHttpMessageConverter;
import org.springframework.mock.web.MockMultipartFile;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;
class FileUploadControllerTest {
@@ -41,6 +49,11 @@ class FileUploadControllerTest {
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.properties()))
// The envelope wire rules a deployment's mapper carries, so a key the wire omits is
// asserted absent rather than merely null.
.setMessageConverters(
new JacksonJsonHttpMessageConverter(
JsonMapper.builder().addModule(EnvelopeWireFormatConfig.module()).build()))
.build();
}
@@ -89,15 +102,19 @@ class FileUploadControllerTest {
}
@Test
void aRawUploadWithoutAFilenameHeaderStillGetsASafeDisplayName() throws Exception {
@DisplayName("이름 헤더 없는 raw 업로드는 전송이 이름을 지어 넣지 않고 앱 정책에 빈 이름을 넘긴다")
void aRawUploadWithoutAFilenameHeaderLeavesTheNameToTheApplicationPolicy() throws Exception {
// when
mvc.perform(
post("/v1/files:raw").contentType(MediaType.APPLICATION_OCTET_STREAM).content("abc"))
.andExpect(status().isCreated());
// then
assertThat(uploadService.requests())
.singleElement()
.extracting(CreateUploadRequest::originalFilename)
.isEqualTo("upload.bin");
.as("OriginalFilenamePolicy names an unnamed upload, once for every transport")
.isEqualTo("");
}
@Test
@@ -127,7 +144,9 @@ class FileUploadControllerTest {
}
@Test
@DisplayName("모든 part가 성공한 batch는 success=true와 part별 results를 순서대로 준다")
void batchReturnsPerPartResultsAndIsExplicitlyNonAtomic() throws Exception {
// when / then
mvc.perform(
multipart("/v1/files:batch")
.file(
@@ -137,13 +156,22 @@ class FileUploadControllerTest {
new MockMultipartFile(
"files", "b.txt", "text/plain", "b".getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isOk())
.andExpect(jsonPath("$.success").value(true))
.andExpect(jsonPath("$.results.length()").value(2))
.andExpect(jsonPath("$.results[0].clientPartId").value("a.txt"))
.andExpect(jsonPath("$.results[1].clientPartId").value("b.txt"));
.andExpect(jsonPath("$.results[1].clientPartId").value("b.txt"))
.andExpect(
result ->
assertThat(keys(json(result).get("results").get(0)))
.as("an accepted part carries no error key, not \"error\": null")
.containsExactlyInAnyOrder("clientPartId", "status", "fileId"));
}
@Test
@DisplayName(
"한 part가 실패한 batch는 success=false, BATCH_PARTIAL_FAILURE, part별 details이고 성공한 part는 되돌리지 않는다")
void aFailedBatchPartNeverRollsBackTheSiblingThatSucceeded() throws Exception {
// given
uploadService.failWith(
body ->
"b".equals(body)
@@ -152,6 +180,7 @@ class FileUploadControllerTest {
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false))
: null);
// when / then
mvc.perform(
multipart("/v1/files:batch")
.file(
@@ -161,10 +190,18 @@ class FileUploadControllerTest {
new MockMultipartFile(
"files", "b.txt", "text/plain", "b".getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isOk())
.andExpect(jsonPath("$.results[0].status").value("READY"))
.andExpect(jsonPath("$.results[1].status").value("REJECTED"))
.andExpect(jsonPath("$.results[1].error.code").value("FILE_TOO_LARGE"))
.andExpect(jsonPath("$.results[1].error.category").value("VALIDATION"));
.andExpect(jsonPath("$.success").value(false))
.andExpect(
result ->
assertThat(keys(json(result)))
.as("a partial failure has no results key at all")
.containsExactlyInAnyOrder("success", "error", "meta"))
.andExpect(jsonPath("$.error.code").value("BATCH_PARTIAL_FAILURE"))
.andExpect(jsonPath("$.error.details[0].status").value("ok"))
.andExpect(jsonPath("$.error.details[0].id").isNotEmpty())
.andExpect(jsonPath("$.error.details[1].index").value(1))
.andExpect(jsonPath("$.error.details[1].status").value("error"))
.andExpect(jsonPath("$.error.details[1].code").value("FILE_TOO_LARGE"));
}
@Test
@@ -181,4 +218,14 @@ class FileUploadControllerTest {
assertThat(body).doesNotContain("/tmp").doesNotContain("multipart").doesNotContain("staging");
}
private static JsonNode json(MvcResult result) throws Exception {
return JsonMapper.shared().readTree(result.getResponse().getContentAsString());
}
private static Set<String> keys(JsonNode node) {
Set<String> keys = new TreeSet<>();
node.properties().forEach(entry -> keys.add(entry.getKey()));
return keys;
}
}
@@ -48,6 +48,59 @@ class FileserverProblemHeaderParityTest {
assertThat(headers).doesNotContainKey("Retry-After");
}
@Test
@org.junit.jupiter.api.DisplayName(
"본문이 retryable=false로 좁히는 code는 발생이 retryable이어도 Retry-After를 싣지 않는다")
void aCodeThatIsNeverRetryableAdvertisesNoRetryWhateverTheOccurrenceSaid() {
// given
FileserverException failure =
new FileserverException(
"no atomic publish",
FileserverFailureContext.of(FileserverErrorCode.ATOMIC_PUBLISH_UNSUPPORTED, true));
// when
Map<String, String> headers = FileserverProblemHeaders.of(failure);
// then
assertThat(headers)
.as("the body says retryable=false for this code; the header must not say otherwise")
.doesNotContainKey("Retry-After");
}
@Test
@org.junit.jupiter.api.DisplayName(
"공용 이름의 SERVER_BUSY는 registry 값(RetryAfterAdvisor)으로 Retry-After를 싣는다")
void aSharedSaturationCodeTakesTheRegistrysRetryAfter() {
// given
FileserverException failure =
new FileserverException(
"pool full", FileserverFailureContext.of(FileserverErrorCode.SERVER_BUSY, true));
// when
Map<String, String> headers = FileserverProblemHeaders.of(failure);
// then
assertThat(headers).containsEntry("Retry-After", "1");
}
@org.junit.jupiter.params.ParameterizedTest(name = "{0}")
@org.junit.jupiter.params.provider.EnumSource(FileserverErrorCode.class)
@org.junit.jupiter.api.DisplayName("재시도 불가 code는 발생이 재시도 가능이라고 해도 Retry-After를 싣지 않는다")
void aNonRetryableCodeNeverAdvertisesARetry(FileserverErrorCode code) {
// given
org.junit.jupiter.api.Assumptions.assumeFalse(code.retryable(), "a retryable code may");
FileserverException failure =
new FileserverException("refused", FileserverFailureContext.of(code, true));
// when
Map<String, String> headers = FileserverProblemHeaders.of(failure);
// then
assertThat(headers)
.as("the body narrows retryable to false for %s; the header must agree", code)
.doesNotContainKey("Retry-After");
}
@Test
void anUnsatisfiableRangeDisclosesTheRepresentationLength() {
Map<String, String> headers =
@@ -0,0 +1,42 @@
package dev.caskeleton.adapter.inbound.web.notification.platform.submission;
import dev.caskeleton.adapter.inbound.web.error.ClientSafeErrorDetails;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
* A request field whose value is outside the vocabulary this transport parses (a channel, a slot, a
* language tag).
*
* <p>The same answer a body constraint gets — {@code 400 VALIDATION_FAILED} with one {@code {field,
* code, message}} detail — rather than the {@code BAD_PARAMETER} a bare {@code
* IllegalArgumentException} reaches, which named nothing the client could correct (review
* 2026-11-12). The detail uses web's validation vocabulary for a value no rule names ({@code
* INVALID}, its fixed wording). The rejected value is not echoed.
*/
final class NotificationFieldRejectedException extends RuntimeException
implements ApiErrorCarrier, ClientSafeErrorDetails {
private static final long serialVersionUID = 1L;
private final String field;
NotificationFieldRejectedException(String field, String reason, Throwable cause) {
super(reason, cause);
this.field = Objects.requireNonNull(field, "field");
}
@Override
public ApiErrorCode errorCode() {
return OperationalError.VALIDATION_FAILED;
}
@Override
public Object clientDetails() {
return List.of(Map.of("field", field, "code", "INVALID", "message", "값이 올바르지 않습니다."));
}
}
@@ -1,7 +1,6 @@
package dev.caskeleton.adapter.inbound.web.notification.platform.submission;
import dev.caskeleton.adapter.inbound.web.observability.ResponseMetaFactory;
import dev.caskeleton.application.notification.platform.api.routing.Channel;
import dev.caskeleton.application.notification.platform.port.in.AcceptNotificationCommand;
import dev.caskeleton.application.notification.platform.port.in.AcceptNotificationUseCase;
import dev.caskeleton.shared.response.Envelope;
@@ -70,7 +69,7 @@ public final class NotificationSubmissionController {
new AcceptNotificationCommand(
Optional.empty(),
request.recipientRef(),
channel(request.channel()),
NotificationVocabulary.channel(request.channel()),
request.address(),
request.template(),
// An omitted version or locale stays omitted: the use case owns both defaults.
@@ -89,36 +88,10 @@ public final class NotificationSubmissionController {
ResponseMetaFactory.fromMdc()));
}
/**
* The channel a caller named.
*
* <p>Parsed here rather than bound by Jackson so an unknown name fails as a validation error
* naming the vocabulary, instead of as a deserialization error naming a Java enum.
*/
private static Channel channel(String name) {
try {
return Channel.valueOf(name.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException unknown) {
throw new IllegalArgumentException(
"channel must be one of " + java.util.Arrays.toString(Channel.values()), unknown);
}
}
/**
* The locale a caller named, or none.
*
* <p>{@link Locale#forLanguageTag} answers {@code Locale.ROOT} for anything it cannot parse
* rather than failing, so an unparseable tag is refused explicitly — silently rendering a Korean
* notification in the root locale is the kind of wrong that reaches a recipient.
*/
private static Optional<Locale> locale(String tag) {
if (tag == null || tag.isBlank()) {
return Optional.empty();
}
Locale parsed = Locale.forLanguageTag(tag.trim());
if (parsed.equals(Locale.ROOT)) {
throw new IllegalArgumentException("locale must be a BCP 47 language tag");
}
return Optional.of(parsed);
return Optional.of(NotificationVocabulary.locale("locale", tag));
}
}
@@ -1,16 +1,11 @@
package dev.caskeleton.adapter.inbound.web.notification.platform.submission;
import dev.caskeleton.adapter.inbound.web.observability.ResponseMetaFactory;
import dev.caskeleton.application.notification.platform.api.routing.Channel;
import dev.caskeleton.application.notification.platform.port.in.PublishNotificationTemplateCommand;
import dev.caskeleton.application.notification.platform.port.in.PublishNotificationTemplateUseCase;
import dev.caskeleton.application.notification.platform.template.TemplateSlot;
import dev.caskeleton.shared.response.Envelope;
import jakarta.validation.Valid;
import java.util.EnumMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
@@ -32,7 +27,12 @@ import org.springframework.web.bind.annotation.RestController;
* publish} and no application or transport ever called it.
*
* <p>{@code 201}, unlike a submission's {@code 202}: a published version is an immutable resource
* that exists when the call returns, with nothing deferred to a worker.
* that exists when the call returns, with nothing deferred to a worker. The response carries no
* {@code Location}: there is no endpoint that reads a template version, and a {@code Location} that
* answers 404 is worse than none. The body names the version and its digest.
*
* <p>The path is lowerCamel plural like every other collection (manual 11, AIP-122); it was {@code
* /notification-templates} until 2026-11-12.
*
* <p>Authorized by {@code notification-template:publish}, which is deliberately not {@code
* notification:submit}. Publishing a template changes what every future submission renders, and a
@@ -45,7 +45,7 @@ import org.springframework.web.bind.annotation.RestController;
name = "enabled",
havingValue = "true",
matchIfMissing = true)
@RequestMapping("/notification-templates")
@RequestMapping("/notificationTemplates")
public final class NotificationTemplateController {
private final PublishNotificationTemplateUseCase publish;
@@ -73,12 +73,12 @@ public final class NotificationTemplateController {
new PublishNotificationTemplateCommand(
request.templateId(),
Optional.ofNullable(request.version()),
channel(request.channel()),
locale(request.locale()),
NotificationVocabulary.channel(request.channel()),
NotificationVocabulary.locale("locale", request.locale()),
Optional.ofNullable(request.fallbackLocale())
.filter(tag -> !tag.isBlank())
.map(NotificationTemplateController::locale),
slots(request.slots()),
.map(tag -> NotificationVocabulary.locale("fallbackLocale", tag)),
NotificationVocabulary.slots(request.slots()),
names(request.requiredVariables()),
names(request.sensitiveVariables()));
@@ -89,47 +89,7 @@ public final class NotificationTemplateController {
ResponseMetaFactory.fromMdc()));
}
/**
* The slots a caller named.
*
* <p>An unknown slot name is refused rather than dropped. Silently ignoring it publishes a
* template missing the content the caller wrote, and the failure then arrives at render time as a
* missing required slot for a template that looks published and complete.
*/
private static Map<TemplateSlot, String> slots(Map<String, String> source) {
Map<TemplateSlot, String> slots = new EnumMap<>(TemplateSlot.class);
source.forEach(
(name, content) -> {
TemplateSlot slot;
try {
slot = TemplateSlot.valueOf(name.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException unknown) {
throw new IllegalArgumentException(
"slot must be one of " + java.util.Arrays.toString(TemplateSlot.values()), unknown);
}
slots.put(slot, content);
});
return slots;
}
private static Set<String> names(List<String> source) {
return source == null ? Set.of() : Set.copyOf(source);
}
private static Channel channel(String name) {
try {
return Channel.valueOf(name.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException unknown) {
throw new IllegalArgumentException(
"channel must be one of " + java.util.Arrays.toString(Channel.values()), unknown);
}
}
private static Locale locale(String tag) {
Locale parsed = Locale.forLanguageTag(tag.trim());
if (parsed.equals(Locale.ROOT)) {
throw new IllegalArgumentException("locale must be a BCP 47 language tag");
}
return parsed;
}
}
@@ -0,0 +1,65 @@
package dev.caskeleton.adapter.inbound.web.notification.platform.submission;
import dev.caskeleton.application.notification.platform.api.routing.Channel;
import dev.caskeleton.application.notification.platform.template.TemplateSlot;
import java.util.Arrays;
import java.util.EnumMap;
import java.util.Locale;
import java.util.Map;
/**
* The names a notification request may use for a channel, a template slot and a locale, parsed once
* for both controllers.
*
* <p>Parsed here rather than bound by Jackson so an unknown name fails as a validation error on its
* field ({@link NotificationFieldRejectedException}, {@code VALIDATION_FAILED}) instead of as a
* deserialization error naming a Java enum.
*/
final class NotificationVocabulary {
private NotificationVocabulary() {}
static Channel channel(String name) {
try {
return Channel.valueOf(name.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException unknown) {
throw new NotificationFieldRejectedException(
"channel", "channel must be one of " + Arrays.toString(Channel.values()), unknown);
}
}
/**
* A BCP 47 tag. {@link Locale#forLanguageTag} answers {@code Locale.ROOT} for anything it cannot
* parse rather than failing, so an unparseable tag is refused explicitly: silently rendering in
* the root locale is the kind of wrong that reaches a recipient.
*/
static Locale locale(String field, String tag) {
Locale parsed = Locale.forLanguageTag(tag.trim());
if (parsed.equals(Locale.ROOT)) {
throw new NotificationFieldRejectedException(
field, field + " must be a BCP 47 language tag", null);
}
return parsed;
}
/**
* The slots a caller named. An unknown slot is refused rather than dropped: ignoring it publishes
* a template missing the content the caller wrote, which then fails at render time as a missing
* required slot of a template that looks published and complete.
*/
static Map<TemplateSlot, String> slots(Map<String, String> source) {
Map<TemplateSlot, String> slots = new EnumMap<>(TemplateSlot.class);
source.forEach(
(name, content) -> {
TemplateSlot slot;
try {
slot = TemplateSlot.valueOf(name.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException unknown) {
throw new NotificationFieldRejectedException(
"slots", "slot must be one of " + Arrays.toString(TemplateSlot.values()), unknown);
}
slots.put(slot, content);
});
return slots;
}
}
@@ -31,6 +31,19 @@ class NotificationRoutePrefixTest {
assertThat(prefixed.test(NotificationTemplateController.class)).isTrue();
}
@org.junit.jupiter.api.Test
@org.junit.jupiter.api.DisplayName("template 게시 경로는 다른 collection처럼 lowerCamel 복수형이다")
void theTemplateCollectionPathIsLowerCamelPlural() {
// when
String[] paths =
NotificationTemplateController.class
.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class)
.value();
// then
assertThat(paths).containsExactly("/notificationTemplates");
}
private static final class InspectablePathMatchConfigurer extends PathMatchConfigurer {
Predicate<Class<?>> prefix(String path) {
@@ -2,13 +2,17 @@ package dev.caskeleton.adapter.inbound.web.notification.platform.submission;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler;
import dev.caskeleton.application.notification.platform.port.in.AcceptNotificationCommand;
import dev.caskeleton.shared.tracing.SpanErrorRecorder;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
@@ -47,4 +51,35 @@ class NotificationSubmissionControllerTest {
// then
assertThat(List.of(status, accepted.size())).containsExactly(400, 0);
}
@ParameterizedTest(name = "{0}")
@CsvSource({
"channel, '\"channel\":\"PIGEON\",\"locale\":\"ko-KR\"'",
"locale, '\"channel\":\"EMAIL\",\"locale\":\"%%%\"'"
})
@DisplayName("모르는 channel·locale은 그 필드를 짚는 400 VALIDATION_FAILED이고 use case에 닿지 않는다")
void anUnknownVocabularyValueIsAValidationFailureNamingTheField(String field, String fields)
throws Exception {
// given
String body =
"{\"recipientRef\":\"r-1\","
+ fields
+ ",\"address\":\"a@example.com\",\"template\":\"welcome\",\"category\":\"TRANSACTIONAL\"}";
// when
String response =
mvc.perform(post("/notifications").contentType(MediaType.APPLICATION_JSON).content(body))
.andExpect(status().isBadRequest())
.andReturn()
.getResponse()
.getContentAsString();
// then
assertThat(response)
.contains("\"code\":\"VALIDATION_FAILED\"")
.contains("\"field\":\"" + field + "\"")
.doesNotContain("PIGEON")
.doesNotContain("%%%");
assertThat(accepted).isEmpty();
}
}
@@ -0,0 +1,67 @@
package dev.caskeleton.adapter.inbound.web.notification.platform.submission;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler;
import dev.caskeleton.application.notification.platform.port.in.PublishNotificationTemplateCommand;
import dev.caskeleton.shared.tracing.SpanErrorRecorder;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class NotificationTemplateControllerTest {
private final List<PublishNotificationTemplateCommand> published = new ArrayList<>();
private final MockMvc mvc =
MockMvcBuilders.standaloneSetup(
new NotificationTemplateController(
command -> {
published.add(command);
throw new IllegalStateException("the probe stops after recording");
}))
.setControllerAdvice(new GlobalExceptionHandler(SpanErrorRecorder.NOOP))
.build();
@ParameterizedTest(name = "{0}")
@CsvSource(
delimiter = '|',
value = {
"channel|\"channel\":\"PIGEON\",\"locale\":\"ko-KR\",\"slots\":{\"SUBJECT\":\"s\"}",
"locale|\"channel\":\"EMAIL\",\"locale\":\"%%%\",\"slots\":{\"SUBJECT\":\"s\"}",
"fallbackLocale|\"channel\":\"EMAIL\",\"locale\":\"ko-KR\",\"fallbackLocale\":\"%%%\",\"slots\":{\"SUBJECT\":\"s\"}",
"slots|\"channel\":\"EMAIL\",\"locale\":\"ko-KR\",\"slots\":{\"FOOTNOTE\":\"s\"}"
})
@DisplayName("template 게시의 모르는 값은 그 필드를 짚는 400 VALIDATION_FAILED이고 use case에 닿지 않는다")
void anUnknownVocabularyValueIsAValidationFailureNamingTheField(String field, String fields)
throws Exception {
// given
String body = "{\"templateId\":\"welcome\"," + fields + "}";
// when
String response =
mvc.perform(
post("/notificationTemplates")
.contentType(MediaType.APPLICATION_JSON)
.content(body))
.andExpect(status().isBadRequest())
.andReturn()
.getResponse()
.getContentAsString();
// then
assertThat(response)
.contains("\"code\":\"VALIDATION_FAILED\"")
.contains("\"field\":\"" + field + "\"")
.doesNotContain("PIGEON")
.doesNotContain("FOOTNOTE");
assertThat(published).isEmpty();
}
}
+5 -3
View File
@@ -62,9 +62,11 @@ bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adap
**않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는
wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional<T>`)을 써서 JSON `null`이 primitive `0`이 되지 못하게
한다.
- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는
*없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에
`org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나 `Optional<T>` wrapper를 쓴다.
- **B2 — PATCH 뜻.** 이 leaf의 `application/json` PATCH DTO는 *없음*(바꾸지 않음), *명시한 null*(필드 비움),
*값*(바꿈)을 구별해야 한다. 요청 record에 `org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나
`Optional<T>` wrapper를 쓴다. RFC 7396 merge patch(`application/merge-patch+json`, `null = 삭제`)와 RFC 6902 JSON
Patch는 `adapter:inbound:web-advanced`의 applier로 받는다. 어느 것을 언제 쓰는지와 거부 규칙의 정본은
`docs/web/patch-contract.md`다.
- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL
정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로
보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한
+1 -1
View File
@@ -532,7 +532,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
이 advisor 가 유일한 Retry-After 노출 지점이라 여기 중앙화한다.
`DEPENDENCY_4XX_CLIENT` 는 비재시도(retryable=false)라 `shouldAdvise` 가드로 empty 반환.
- 다른 leaf 가 소유한 코드는 이 표에 이름으로 넣지 않고 `RetryAfterHint` 를 구현해 값을 스스로 말한다
(web-advanced `ADMISSION_REFUSED` = 1초).
(web-advanced `WebAdvancedError`). 서버 포화는 공용 `SERVER_BUSY`(1초)이고 이 표에 있다.
- `IDEMPOTENT_IN_FLIGHT` 는 2초: 기본 processing lease(30s)보다 짧아 첫 시도가 끝날 수 있는 동안
같은 키로 다시 묻게 한다. 근거와 클라이언트 행동은 `docs/web/http-contract.md` §2.
- 표는 레지스트리의 `retry_after_seconds` 가 있는 행마다 한 줄이다(`LOCK_ACQUISITION_TIMEOUT` 1초, DB·outbox·job
@@ -3,6 +3,7 @@ package dev.caskeleton.adapter.inbound.web.envelope;
import com.fasterxml.jackson.annotation.JsonInclude;
import dev.caskeleton.shared.response.ApiError;
import dev.caskeleton.shared.response.BulkEnvelope;
import dev.caskeleton.shared.response.BulkItemResult;
import dev.caskeleton.shared.response.Envelope;
import dev.caskeleton.shared.response.ResponseMeta;
import org.springframework.context.annotation.Bean;
@@ -33,6 +34,7 @@ public class EnvelopeWireFormatConfig {
SimpleModule module = new SimpleModule("EnvelopeWireFormatModule");
module.setMixInAnnotation(Envelope.class, OmitNullFields.class);
module.setMixInAnnotation(BulkEnvelope.class, OmitNullFields.class);
module.setMixInAnnotation(BulkItemResult.class, OmitNullFields.class);
module.setMixInAnnotation(ApiError.class, OmitNullFields.class);
module.setMixInAnnotation(ResponseMeta.class, OmitNullFields.class);
return module;
@@ -31,6 +31,14 @@ public final class ErrorResponseFactory {
return body(code, code.retryable(), details);
}
/**
* Whether this occurrence may be retried: the occurrence can only narrow its code. The one rule
* for the body's {@code retryable} and for any {@code Retry-After} a transport adds beside it.
*/
public static boolean effectiveRetryable(ApiErrorCode code, boolean occurrenceRetryable) {
return code.retryable() && occurrenceRetryable;
}
/**
* Body whose {@code retryable} is decided for this occurrence.
*
@@ -39,7 +47,7 @@ public final class ErrorResponseFactory {
*/
public static Envelope<Void> body(ApiErrorCode code, boolean retryable, Object details) {
String message = ClientErrorMessages.of(code);
boolean effectiveRetryable = code.retryable() && retryable;
boolean effectiveRetryable = effectiveRetryable(code, retryable);
ApiError err =
details == null
? ApiError.of(code.code(), code.category().name(), message, effectiveRetryable)
@@ -412,12 +412,25 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
return null;
}
}
ApiErrorCode code = HttpStatusErrorCodes.forStatus(statusCode);
ApiErrorCode code = HttpStatusErrorCodes.forException(ex, statusCode);
if (code.httpStatus() >= 500) {
log.error("spring mvc failure classified as {}", code.code(), ex);
spanErrorRecorder.recordException(ex, code.code());
}
// The code's registry Retry-After, as the error dispatch (EnvelopeErrorController) adds it: a
// 503 classified SERVER_BUSY or a 429 RATE_LIMIT_EXCEEDED left without it here (review
// 2026-11-12). A header Spring already prepared wins.
// Copied: the headers Spring hands over may be read-only.
HttpHeaders responseHeaders = new HttpHeaders();
responseHeaders.putAll(headers);
if (!responseHeaders.containsHeader(ApiHeaders.RETRY_AFTER)) {
RetryAfterAdvisor.retryAfterSeconds(code)
.ifPresent(
seconds -> responseHeaders.set(ApiHeaders.RETRY_AFTER, String.valueOf(seconds)));
}
return new ResponseEntity<>(
ErrorResponseFactory.body(code, null), headers, HttpStatusCode.valueOf(code.httpStatus()));
ErrorResponseFactory.body(code, null),
responseHeaders,
HttpStatusCode.valueOf(code.httpStatus()));
}
}
@@ -3,6 +3,7 @@ package dev.caskeleton.adapter.inbound.web.error;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
import org.springframework.http.HttpStatusCode;
import org.springframework.web.context.request.async.AsyncRequestTimeoutException;
/**
* The operational code a bare HTTP status stands for, when a status is all that is known.
@@ -15,6 +16,17 @@ final class HttpStatusErrorCodes {
private HttpStatusErrorCodes() {}
/**
* The code for a Spring MVC exception that carries only a status. An async request timeout is
* {@code REQUEST_TIMEOUT}; anything else is classified by its status.
*/
static ApiErrorCode forException(Exception failure, HttpStatusCode status) {
if (failure instanceof AsyncRequestTimeoutException) {
return WebTransportError.REQUEST_TIMEOUT;
}
return forStatus(status);
}
static ApiErrorCode forStatus(HttpStatusCode status) {
return switch (status.value()) {
case 401 -> OperationalError.UNAUTHENTICATED;
@@ -27,8 +39,10 @@ final class HttpStatusErrorCodes {
case 414 -> OperationalError.URI_TOO_LONG;
case 415 -> OperationalError.UNSUPPORTED_MEDIA_TYPE;
case 429 -> OperationalError.RATE_LIMIT_EXCEEDED;
// Spring answers its async request timeout with 503: transient, not an internal fault.
case 503 -> WebTransportError.REQUEST_TIMEOUT;
// A bare 503 is the server saying it cannot serve now (RFC 9110 15.6.4). An async request
// timeout is also a 503, and forException tells it apart; every other one used to be
// labelled REQUEST_TIMEOUT whatever it was (review 2026-11-12).
case 503 -> OperationalError.SERVER_BUSY;
default ->
status.is4xxClientError()
? OperationalError.BAD_PARAMETER
@@ -19,6 +19,7 @@ public final class RetryAfterAdvisor {
private static final Map<String, Integer> RETRY_AFTER_SECONDS =
Map.ofEntries(
Map.entry("RATE_LIMIT_EXCEEDED", 1),
Map.entry("SERVER_BUSY", 1),
// The application's value, which the processing-lease check also reads: the resend
// arrives while the first attempt can still finish. docs/web/http-contract.md §2.
Map.entry(
@@ -5,6 +5,8 @@ import static org.springframework.test.web.servlet.request.MockMvcRequestBuilder
import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler;
import dev.caskeleton.application.idempotency.IdempotencyInFlightException;
import dev.caskeleton.shared.error.ClientErrorMessages;
import dev.caskeleton.shared.error.OperationalError;
import dev.caskeleton.shared.observability.MdcKeys;
import dev.caskeleton.shared.response.BulkEnvelope;
import dev.caskeleton.shared.response.BulkItemResult;
@@ -26,6 +28,7 @@ import org.springframework.boot.security.autoconfigure.SecurityAutoConfiguration
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@@ -77,6 +80,33 @@ class EnvelopeWireShapeTest {
new ResponseMeta("req-1", "trace-1", "corr-1").withPage(new PageMeta(0, 20, 1, "id")));
}
@GetMapping("/probe/null-data")
public Envelope<String> nullData() {
return Envelope.ok(null, new ResponseMeta("req-1", "trace-1", "corr-1"));
}
@GetMapping("/probe/text")
public String text() {
ids(true);
return "hello";
}
@GetMapping("/probe/page-unsorted")
public Envelope<List<String>> pageUnsorted() {
return Envelope.ok(
List.of("a"),
new ResponseMeta("req-1", "trace-1", "corr-1").withPage(new PageMeta(0, 20, 1, null)));
}
@GetMapping("/probe/bulk-partial-items")
public BulkEnvelope<String> bulkPartialItems() {
return BulkEnvelope.partial(
List.of(
BulkItemResult.ok(0, "item-1"),
BulkItemResult.error(1, OperationalError.MAPPING_FAILED)),
new ResponseMeta("req-1", "trace-1", "corr-1"));
}
@GetMapping("/probe/in-flight")
public Map<String, String> inFlight() {
ids(false);
@@ -178,6 +208,60 @@ class EnvelopeWireShapeTest {
assertThat(details.isArray() && details.isEmpty()).isTrue();
}
@Test
@DisplayName("성공인데 data가 null이면 data 키도 없다")
void aNullDataOmitsTheDataKey() throws Exception {
// when
JsonNode body = rawBody("/probe/null-data");
// then
assertThat(keys(body)).containsExactlyInAnyOrder("success", "meta");
}
@Test
@DisplayName("JSON을 요청하면 String 반환도 같은 Envelope의 data로 나간다")
void aStringBodyIsAnEnvelopeWhenJsonIsAsked() throws Exception {
// when
JsonNode body =
READER.readTree(
mvc.perform(get("/probe/text").accept(MediaType.APPLICATION_JSON))
.andReturn()
.getResponse()
.getContentAsString());
// then
assertThat(keys(body)).containsExactlyInAnyOrder("success", "data", "meta");
assertThat(body.get("data").asString()).isEqualTo("hello");
}
@Test
@DisplayName("정렬 없는 목록의 page는 sort 키를 null로 싣는다")
void anUnsortedPageCarriesSortNull() throws Exception {
// when
JsonNode page = rawBody("/probe/page-unsorted").get("meta").get("page");
// then
assertThat(keys(page)).containsExactlyInAnyOrder("number", "size", "total", "sort");
assertThat(page.get("sort").isNull()).isTrue();
}
@Test
@DisplayName("bulk 부분 실패의 message는 고정 문구이고 항목은 자기 상태에 맞는 키만 싣는다")
void aPartialFailureCarriesFixedWordingAndItemsWithoutNullKeys() throws Exception {
// when
JsonNode error = rawBody("/probe/bulk-partial-items").get("error");
// then
assertThat(error.get("message").asString())
.isEqualTo(ClientErrorMessages.of(OperationalError.BATCH_PARTIAL_FAILURE));
assertThat(keys(error.get("details").get(0)))
.containsExactlyInAnyOrder("index", "status", "id");
assertThat(keys(error.get("details").get(1)))
.containsExactlyInAnyOrder("index", "status", "code", "message");
assertThat(error.get("details").get(1).get("message").asString())
.isEqualTo(ClientErrorMessages.of(OperationalError.MAPPING_FAILED));
}
private JsonNode rawBody(String path) throws Exception {
String text = mvc.perform(get(path)).andReturn().getResponse().getContentAsString();
return READER.readTree(text);
@@ -28,6 +28,7 @@ class EnvelopeErrorControllerTest {
"401, 401, UNAUTHENTICATED",
"404, 404, ROUTE_NOT_FOUND",
"429, 429, RATE_LIMIT_EXCEEDED",
"503, 503, SERVER_BUSY",
"409, 400, BAD_PARAMETER",
"422, 400, BAD_PARAMETER",
"500, 500, INTERNAL_ERROR",
@@ -124,6 +124,32 @@ class TransportErrorHandlingTest {
.andExpect(jsonPath("$.error.code").value("BAD_PARAMETER"));
}
@Test
@DisplayName("상태만 아는 503은 SERVER_BUSY이고 registry의 Retry-After를 싣는다")
void aBare503IsServerBusyWithItsRetryAfter() throws Exception {
// when
var result = mvc.perform(get("/t/status-503"));
// then
result
.andExpect(status().isServiceUnavailable())
.andExpect(jsonPath("$.error.code").value("SERVER_BUSY"))
.andExpect(header().string("Retry-After", "1"));
}
@Test
@DisplayName("상태만 아는 429도 RATE_LIMIT_EXCEEDED의 Retry-After를 싣는다")
void aBare429CarriesItsRetryAfter() throws Exception {
// when
var result = mvc.perform(get("/t/status-429"));
// then
result
.andExpect(status().isTooManyRequests())
.andExpect(jsonPath("$.error.code").value("RATE_LIMIT_EXCEEDED"))
.andExpect(header().string("Retry-After", "1"));
}
@Test
@DisplayName("비동기 요청 시간 초과는 500이 아니라 재시도 가능한 503 REQUEST_TIMEOUT이다")
void anAsyncTimeoutIsARetryable503NotAnInternalError() throws Exception {
@@ -199,6 +225,18 @@ class TransportErrorHandlingTest {
throw new AsyncRequestTimeoutException();
}
@GetMapping("/t/status-503")
Map<String, String> status503() {
throw new org.springframework.web.server.ResponseStatusException(
org.springframework.http.HttpStatus.SERVICE_UNAVAILABLE);
}
@GetMapping("/t/status-429")
Map<String, String> status429() {
throw new org.springframework.web.server.ResponseStatusException(
org.springframework.http.HttpStatus.TOO_MANY_REQUESTS);
}
@GetMapping("/t/bounded")
Map<String, Integer> bounded(@RequestParam("limit") @Max(10) int limit) {
return Map.of("limit", limit);
@@ -17,10 +17,10 @@ import dev.caskeleton.shared.error.Category;
* servlet transport, the reactive transport and the Nginx delegation path cannot answer the same
* failure three different ways.
*
* <p>{@code UNAUTHENTICATED}, {@code PRECONDITION_FAILED} and {@code UNSUPPORTED_MEDIA_TYPE} share
* their name with an {@code OperationalError}; they are kept here so the failure context stays one
* enum, and {@code FileserverExceptionTest} pins that each means exactly what the operational code
* means on the wire (category, status, retryability).
* <p>{@code UNAUTHENTICATED}, {@code PRECONDITION_FAILED}, {@code UNSUPPORTED_MEDIA_TYPE} and
* {@code SERVER_BUSY} share their name with an {@code OperationalError}; they are kept here so the
* failure context stays one enum, and {@code FileserverExceptionTest} pins that each means exactly
* what the operational code means on the wire (category, status, retryability).
*/
public enum FileserverErrorCode implements ApiErrorCode {
BAD_REQUEST(400, Category.VALIDATION, false),
@@ -42,6 +42,7 @@ public enum FileserverErrorCode implements ApiErrorCode {
MALWARE_DETECTED(422, Category.DATA_INTEGRITY, false),
INVALID_PATH(422, Category.VALIDATION, false),
PATH_OUTSIDE_NAMESPACE(422, Category.VALIDATION, false),
// The caller's own transfers fill its scope's permits: the caller's rate, so 429.
TRANSFER_ADMISSION_REJECTED(429, Category.RATE_LIMIT, true),
// tus checksum extension status: one request's bytes did not match the checksum the client sent
// for them. The chunk is rolled back before its offset commits, so the upload stays resumable.
@@ -52,6 +53,9 @@ public enum FileserverErrorCode implements ApiErrorCode {
AMBIGUOUS_COMPLETION(500, Category.DATA_INTEGRITY, false),
ATOMIC_PUBLISH_UNSUPPORTED(503, Category.PERMANENT_DEPENDENCY, false),
STORAGE_UNAVAILABLE(503, Category.TRANSIENT_DEPENDENCY, true),
// The instance's permits or its transfer pool are full: server saturation, the shared code every
// transport answers it with (decisions 2.3, 2026-11-12).
SERVER_BUSY(503, Category.TRANSIENT_DEPENDENCY, true),
TRANSFER_TIMEOUT(504, Category.TRANSIENT_DEPENDENCY, true),
STORAGE_FULL(507, Category.TRANSIENT_DEPENDENCY, false);
@@ -15,9 +15,11 @@ import java.util.concurrent.atomic.AtomicBoolean;
* In-process admission control backed by bounded semaphores.
*
* <p>The failure vocabulary is deliberately distinct so a client can tell a permanent policy denial
* from a transient one: an exhausted pool is {@code STORAGE_FULL}, and running out of concurrency
* permits — for the caller's scope or for the whole instance — is a retryable admission rejection.
* Stored bytes over a quota ({@code QUOTA_EXCEEDED}) are decided by the quota service, not here.
* from a transient one: an exhausted pool is {@code STORAGE_FULL}; running out of the caller's own
* scope permits is a retryable {@code TRANSFER_ADMISSION_REJECTED} (429, the caller's rate);
* running out of the whole instance's permits is the shared server-saturation {@code SERVER_BUSY}
* (503). Stored bytes over a quota ({@code QUOTA_EXCEEDED}) are decided by the quota service, not
* here.
*/
public final class TransferAdmissionController {
@@ -74,7 +76,7 @@ public final class TransferAdmissionController {
scopePermits.release();
throw new FileserverException(
"instance upload permits are exhausted",
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
FileserverFailureContext.of(FileserverErrorCode.SERVER_BUSY, true));
}
return new SemaphorePermit(scopePermits, instanceUploads);
}
@@ -83,7 +85,7 @@ public final class TransferAdmissionController {
if (!directDownloads.tryAcquire()) {
throw new FileserverException(
"instance direct download permits are exhausted",
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
FileserverFailureContext.of(FileserverErrorCode.SERVER_BUSY, true));
}
return new SemaphorePermit(directDownloads);
}
@@ -9,7 +9,9 @@ import java.util.OptionalLong;
* Client intent when starting an upload.
*
* <p>{@code originalFilename} and {@code claimedMediaType} are untrusted: they are sanitized and
* stored as display metadata, never used to build a physical key or to decide safety.
* stored as display metadata, never used to build a physical key or to decide safety. A transport
* that received no name passes an empty string; the display name of an unnamed upload is {@code
* OriginalFilenamePolicy}'s to choose, not each transport's.
*
* <p>The request carries only what the client decides. The namespace and the session lifetime are
* {@link UploadPolicy}'s, so no transport can pick its own.
@@ -119,7 +119,12 @@ class TransferAdmissionControllerTest {
assertThatThrownBy(() -> narrow.acquireUpload(scope("tenant-b"), 10))
.isInstanceOf(FileserverException.class)
.satisfies(
failure -> assertThat(((FileserverException) failure).context().retryable()).isTrue());
failure -> {
assertThat(((FileserverException) failure).context().retryable()).isTrue();
assertThat(((FileserverException) failure).context().code())
.as("the whole instance is full: server saturation, not the caller's rate")
.isEqualTo(FileserverErrorCode.SERVER_BUSY);
});
held.close();
TransferPermit afterRelease = narrow.acquireUpload(scope("tenant-b"), 10);
@@ -197,7 +202,9 @@ class TransferAdmissionControllerTest {
TransferPermit download = narrow.acquireDirectDownload(scope("tenant-a"));
assertThatThrownBy(() -> narrow.acquireDirectDownload(scope("tenant-a")))
.isInstanceOf(FileserverException.class);
.isInstanceOf(FileserverException.class)
.extracting(failure -> ((FileserverException) failure).context().code())
.isEqualTo(FileserverErrorCode.SERVER_BUSY);
assertThat(narrow.acquireUpload(scope("tenant-a"), 10).isHeld()).isTrue();
download.close();
@@ -49,7 +49,7 @@ case "${NOTIFICATION_SMOKE_PHASE}" in
# reruns against a surviving volume is not a different lane; a 409 here means the platform
# holds a version with this id and different content, which is a real failure.
PUBLISH_STATUS="$(curl -s -o /tmp/publish.json -w '%{http_code}' \
-X POST "${APP_BASE_URL}${BASE_PATH}/notification-templates" \
-X POST "${APP_BASE_URL}${BASE_PATH}/notificationTemplates" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H 'Content-Type: application/json' \
-d "{\"templateId\":\"${TEMPLATE_ID}\",\"version\":1,\"channel\":\"EMAIL\",\"locale\":\"en\",
@@ -19,7 +19,7 @@ composition:notification-platform
├─ adapter:outbound:notification provider(SMTP·SES), 저장 외 런타임, NotificationPlatformAutoConfiguration
├─ adapter:outbound:persistence-notification (runtimeOnly) 알림 entity·저장소·Flyway stream
├─ adapter:outbound:persistence-jpa (runtimeOnly) DataSource·Flyway core·TransactionPort
└─ adapter:inbound:web-notification POST /notifications, POST /notification-templates,
└─ adapter:inbound:web-notification POST /notifications, POST /notificationTemplates,
POST /internal/notification/callbacks/{provider}/{profile}
```
@@ -44,6 +44,12 @@ public enum OperationalError implements ApiErrorCode {
ROUTE_NOT_FOUND(Category.NOT_FOUND, 404, false),
// rate-limit / idempotency
RATE_LIMIT_EXCEEDED(Category.RATE_LIMIT, 429, true),
/**
* This instance has no capacity for another request right now: an admission limit, a full work
* pool. Every transport answers server saturation with this one code; {@link
* #RATE_LIMIT_EXCEEDED} is the caller's own rate (decisions 2.3, 2026-11-12).
*/
SERVER_BUSY(Category.TRANSIENT_DEPENDENCY, 503, true),
IDEMPOTENT_IN_FLIGHT(Category.CONFLICT, 409, true),
IDEMPOTENT_REQUEST_MISMATCH(Category.VALIDATION, 422, false),
IDEMPOTENCY_UNAVAILABLE(Category.TRANSIENT_DEPENDENCY, 503, true),
@@ -1,5 +1,6 @@
package dev.caskeleton.shared.response;
import dev.caskeleton.shared.error.ClientErrorMessages;
import dev.caskeleton.shared.error.OperationalError;
import java.util.List;
@@ -25,7 +26,7 @@ public record BulkEnvelope<T>(boolean success, List<T> results, ApiError error,
ApiError.withDetails(
OperationalError.BATCH_PARTIAL_FAILURE.code(),
OperationalError.BATCH_PARTIAL_FAILURE.category().name(),
"One or more items failed; see details[] for the per-item outcome.",
ClientErrorMessages.of(OperationalError.BATCH_PARTIAL_FAILURE),
OperationalError.BATCH_PARTIAL_FAILURE.retryable(),
details);
return new BulkEnvelope<>(false, null, err, meta);
@@ -1,14 +1,20 @@
package dev.caskeleton.shared.response;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.ClientErrorMessages;
/**
* Per-item result inside a bulk endpoint's {@code error.details[]} array.
*
* <ul>
* <li>{@code status = "ok"} + {@code id} when the item succeeded;
* <li>{@code status = "error"} + {@code code} + {@code message} when failed.
* <li>{@code status = "error"} + {@code code} + {@code message} when failed. The message is the
* code's category wording from {@link ClientErrorMessages}, the same text a single-item
* endpoint would send, never the caller's own text (review 2026-11-12).
* </ul>
*
* <p>No debug payload — keeps the envelope safe to log/ship.
* <p>No debug payload — keeps the envelope safe to log/ship. Absent members are omitted on the wire
* like every other envelope field.
*/
public record BulkItemResult(int index, String status, String id, String code, String message) {
@@ -16,7 +22,7 @@ public record BulkItemResult(int index, String status, String id, String code, S
return new BulkItemResult(index, "ok", id, null, null);
}
public static BulkItemResult error(int index, String code, String message) {
return new BulkItemResult(index, "error", null, code, message);
public static BulkItemResult error(int index, ApiErrorCode code) {
return new BulkItemResult(index, "error", null, code.code(), ClientErrorMessages.of(code));
}
}
@@ -2,7 +2,10 @@ package dev.caskeleton.shared.response;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.shared.error.ClientErrorMessages;
import dev.caskeleton.shared.error.OperationalError;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class EnvelopeTest {
@@ -31,16 +34,39 @@ class EnvelopeTest {
}
@Test
void bulkAllOkAndPartialCarryMeta() {
BulkEnvelope<String> ok = BulkEnvelope.allOk(List.of("a"), META);
@DisplayName("bulk 전체 성공은 success=true와 meta를 싣는다")
void aFullySucceededBulkCarriesMeta() {
// given
List<String> results = List.of("a");
// when
BulkEnvelope<String> ok = BulkEnvelope.allOk(results, META);
// then
assertThat(ok.success()).isTrue();
assertThat(ok.meta().requestId()).isEqualTo("req-1");
}
BulkEnvelope<String> partial =
BulkEnvelope.partial(List.of(BulkItemResult.error(0, "MAPPING_FAILED", "x")), META);
@Test
@DisplayName("bulk 부분 실패는 BATCH_PARTIAL_FAILURE와 category 고정 문구, 항목 코드의 고정 문구를 싣는다")
void aPartiallyFailedBulkCarriesTheFixedWording() {
// given
List<BulkItemResult> details =
List.of(
BulkItemResult.ok(0, "f-1"), BulkItemResult.error(1, OperationalError.MAPPING_FAILED));
// when
BulkEnvelope<String> partial = BulkEnvelope.partial(details, META);
// then
assertThat(partial.success()).isFalse();
assertThat(partial.error().code()).isEqualTo("BATCH_PARTIAL_FAILURE");
assertThat(partial.error().category()).isEqualTo("VALIDATION");
assertThat(partial.error().message())
.isEqualTo(ClientErrorMessages.of(OperationalError.BATCH_PARTIAL_FAILURE));
assertThat(details.get(1).message())
.as("an item carries its code's wording, never text the caller chose")
.isEqualTo(ClientErrorMessages.of(OperationalError.MAPPING_FAILED));
assertThat(partial.meta().correlationId()).isEqualTo("corr-1");
}
}