diff --git a/docs/upgrade/2026-11-round9-contracts.md b/docs/upgrade/2026-11-round9-contracts.md new file mode 100644 index 00000000..8f89e0c3 --- /dev/null +++ b/docs/upgrade/2026-11-round9-contracts.md @@ -0,0 +1,19 @@ +# 업그레이드 안내 — 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 ADMISSION_REFUSED`와 `Retry-After: 1`이다 | `app.web.advanced.mvc-virtual-threads.enabled=true`인 배포 | diff --git a/docs/web/advanced-capabilities.md b/docs/web/advanced-capabilities.md index 731c048f..719adfc9 100644 --- a/docs/web/advanced-capabilities.md +++ b/docs/web/advanced-capabilities.md @@ -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` | diff --git a/docs/web/patch-contract.md b/docs/web/patch-contract.md index 5cb64725..c340fe85 100644 --- a/docs/web/patch-contract.md +++ b/docs/web/patch-contract.md @@ -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 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고 @@ -63,6 +67,11 @@ patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검 객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도 보지 못한다. +- 두 applier는 서비스의 Bean Validation `Validator`를 생성자로 받고, 결과 객체 전체를 검증한 뒤에 돌려준다. 위반은 + `@Valid` 본문과 같은 `400 VALIDATION_FAILED`와 필드별 `details`다. +- 결과가 자원 타입으로 읽히지 않으면(숫자 자리에 문자열) `400 PATCH_REJECTED`다. +- 상태 전이처럼 업무 규칙인 검증은 여기서 하지 않는다. 유스케이스가 한다. + ## 선행 조건 patch route는 `If-Match`를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다. diff --git a/docs/web/streaming-contract.md b/docs/web/streaming-contract.md index b2ccb6a8..01283585 100644 --- a/docs/web/streaming-contract.md +++ b/docs/web/streaming-contract.md @@ -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가 한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다. diff --git a/docs/web/virtual-thread-profile.md b/docs/web/virtual-thread-profile.md index 599927db..610ea717 100644 --- a/docs/web/virtual-thread-profile.md +++ b/docs/web/virtual-thread-profile.md @@ -36,7 +36,11 @@ app: `VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를 제한하면 기다림을 되돌려 놓고 virtual thread로 얻은 것을 버리게 된다. virtual thread 만 개가 있어도 백 개만 허가를 쥐고 나머지는 문 앞에서 거부된다. -거부는 **`Retry-After`가 붙은 503**이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤 +상한은 `VirtualThreadAdmissionFilter`가 모든 요청에 건다. request-id filter 바로 뒤, 보안 chain보다 앞이라 거부된 요청은 +아무 일도 하지 않는다. async 요청은 async 일이 끝날 때까지 허가를 쥔다. 넘겨준 순간 돌려주면 넘기는 일만 제한하고 정작 +하류 pool을 쓰는 일은 제한하지 못한다. + +거부는 **`Retry-After`가 붙은 503**(`ADMISSION_REFUSED`)이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤 가득 찬 pool 뒤에서 30초 뒤에 시간 초과가 난 같은 요청보다 client에게 확실히 낫다. semaphore는 일부러 공정하다. 불공정한 것이 빠르지만, 새로 온 요청이 기다리던 요청을 앞지르게 두고, 앞지름당한 diff --git a/src/adapter/inbound/web-advanced/README.md b/src/adapter/inbound/web-advanced/README.md index 3b854a88..34f7c59c 100644 --- a/src/adapter/inbound/web-advanced/README.md +++ b/src/adapter/inbound/web-advanced/README.md @@ -58,7 +58,7 @@ virtual thread 실행기는 `TaskDecorator` bean 을 요구한다(요청 상관 | --- | --- | --- | --- | --- | --- | --- | | `AdmissionRefusedException` | `ADMISSION_REFUSED` | 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 | — | 서버 설정 결함(등록 시점 오류) | diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamWriter.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamWriter.java index c836c18f..49092b59 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamWriter.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamWriter.java @@ -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. * + *

Positions are enforced here: 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. + * + *

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. + * *

**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,14 @@ public final class MvcStreamWriter { try { while (records.hasNext()) { NdjsonRecord record = records.next(); + if (record instanceof NdjsonRecord.Item item && item.sequence() <= lastSequence) { + throw new IllegalStateException( + "stream position " + + item.sequence() + + " does not follow " + + lastSequence + + "; positions strictly increase"); + } writeRecord(record, output); if (record instanceof NdjsonRecord.Item item) { evidence.recordDelivered(new StreamSequence(item.sequence())); @@ -91,13 +113,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( - lastSequence, - "DEPENDENCY_FAILURE", - "the stream ended early because a dependency failed"), + new NdjsonRecord.Failure(lastSequence, code.code(), ClientErrorMessages.of(code)), output); evidence.recordTermination(WebStreamTermination.TERMINAL_ERROR_RECORD, clock.instant()); return WebStreamTermination.TERMINAL_ERROR_RECORD; diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadAdmissionFilter.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadAdmissionFilter.java new file mode 100644 index 00000000..ee5c9c17 --- /dev/null +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadAdmissionFilter.java @@ -0,0 +1,111 @@ +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.RetryAfterHint; +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. + * + *

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 whole request including the + * security chain, and refuses before any of it runs. + * + *

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 request-id filter, so a refusal still carries the request id. */ + public static final int ORDER = Ordered.HIGHEST_PRECEDENCE + 11; + + 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) { + if (refused.errorCode() instanceof RetryAfterHint hint) { + response.setHeader(ApiHeaders.RETRY_AFTER, Integer.toString(hint.retryAfterSeconds())); + } + 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); + } + } +} diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadMvcConfiguration.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadMvcConfiguration.java index 2273845c..617513f5 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadMvcConfiguration.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadMvcConfiguration.java @@ -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. * diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplier.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplier.java index ce301568..11ddfe0a 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplier.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplier.java @@ -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 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) { diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchDocument.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchDocument.java index 4aad82e0..87ffb87d 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchDocument.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchDocument.java @@ -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"); } diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplier.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplier.java index 04a2e8ba..5803aac4 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplier.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplier.java @@ -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) { diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchDocument.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchDocument.java index b461b6c0..d560b4fd 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchDocument.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchDocument.java @@ -24,7 +24,7 @@ public record JsonPatchDocument(List 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 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 " diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchOperation.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchOperation.java index 79d2c290..65c7ab4e 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchOperation.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchOperation.java @@ -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"); } } diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPointerAuthorization.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPointerAuthorization.java index bf47c21b..3e6b2273 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPointerAuthorization.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPointerAuthorization.java @@ -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 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 refused = new ArrayList<>(); for (JsonPatchOperation operation : operations) { if (operation.kind().mutating() && !writable(operation.path())) { diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/PatchBodies.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/PatchBodies.java new file mode 100644 index 00000000..cca6b7af --- /dev/null +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/patch/PatchBodies.java @@ -0,0 +1,53 @@ +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. + * + *

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. + * + *

Whole, not field by field: two fields that must agree, or a state only some transitions + * allow, are invisible to a check of the changed fields alone. 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 toTarget(ObjectMapper mapper, Validator validator, JsonNode patched, Class 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> violations = validator.validate(result); + if (!violations.isEmpty()) { + throw new ConstraintViolationException(violations); + } + return result; + } +} diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/virtualthread/VirtualThreadAdmissionGuard.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/virtualthread/VirtualThreadAdmissionGuard.java index b66aed53..707391a5 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/virtualthread/VirtualThreadAdmissionGuard.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/virtualthread/VirtualThreadAdmissionGuard.java @@ -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 run(java.util.concurrent.Callable 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(); + } } } diff --git a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcAdvancedConfigurationTest.java b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcAdvancedConfigurationTest.java index ee30ac31..20c76e91 100644 --- a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcAdvancedConfigurationTest.java +++ b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcAdvancedConfigurationTest.java @@ -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()) diff --git a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamingWiringTest.java b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamingWiringTest.java index c738bbbe..f9e25a24 100644 --- a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamingWiringTest.java +++ b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/MvcStreamingWiringTest.java @@ -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.>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.>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 { diff --git a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadAdmissionFilterTest.java b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadAdmissionFilterTest.java new file mode 100644 index 00000000..47b1434a --- /dev/null +++ b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/mvc/VirtualThreadAdmissionFilterTest.java @@ -0,0 +1,87 @@ +package dev.caskeleton.adapter.inbound.web.advanced.mvc; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.VirtualThreadAdmissionGuard; +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.MockHttpServletRequest; +import org.springframework.mock.web.MockHttpServletResponse; +import tools.jackson.databind.json.JsonMapper; + +/** The request path through the admission guard. */ +@Tag("web-advanced") +class VirtualThreadAdmissionFilterTest { + + @Test + @DisplayName("한도가 차면 요청은 controller에 닿지 않고 503 ADMISSION_REFUSED와 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("ADMISSION_REFUSED"); + 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(); + } +} diff --git a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplierTest.java b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplierTest.java index 2795f20c..4e829b76 100644 --- a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplierTest.java +++ b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonMergePatchApplierTest.java @@ -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); + } } diff --git a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplierTest.java b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplierTest.java index 1b1c538f..c50838c0 100644 --- a/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplierTest.java +++ b/src/adapter/inbound/web-advanced/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/patch/JsonPatchApplierTest.java @@ -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 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,77 @@ 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); + } } diff --git a/src/adapter/inbound/web/AGENTS.md b/src/adapter/inbound/web/AGENTS.md index fbc2fd8a..7922037f 100644 --- a/src/adapter/inbound/web/AGENTS.md +++ b/src/adapter/inbound/web/AGENTS.md @@ -62,9 +62,11 @@ bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adap **않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는 wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 한다. -- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 - *없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에 - `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 `Optional` wrapper를 쓴다. +- **B2 — PATCH 뜻.** 이 leaf의 `application/json` PATCH DTO는 *없음*(바꾸지 않음), *명시한 null*(필드 비움), + *값*(바꿈)을 구별해야 한다. 요청 record에 `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 + `Optional` 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가 아닌 호출자의 평범한