Files
clean-architecture-backend-…/docs/web/advanced-capabilities.md
T
DongHyeonka 18188f78c9 fix(web-advanced)!: patch·stream·virtual thread가 약속한 계약대로 답한다
문제: web-advanced의 계약 문서와 코드가 다섯 곳에서 갈렸다.
- patch 거부가 세 코드로 갈렸다. 형식 오류는 PATCH_REJECTED(400), 빈
  문서·연산 모양 오류·merge 깊이 초과는 IllegalArgumentException이라
  BAD_PARAMETER(400), 너무 깊은 pointer는 권한 거절 PATCH_PATH_FORBIDDEN(403)
  이었다. JSON이 아닌 본문과 결과가 대상 타입으로 읽히지 않는 patch는
  Jackson 예외로 catch-all에 닿아 500 INTERNAL_ERROR였다.
- patch-contract.md는 결과를 문서 전체로 검증한다고 했지만 두 applier는
  검증기를 받지 않았다.
- streaming-contract.md는 서버가 위치 증가를 강제하고 heartbeat·idle·max
  age·버퍼 상한·drain 재연결을 한다고 했다. MvcStreamWriter는 그 어느 것도
  하지 않았다.
- commit 뒤 Failure 기록이 어디에도 등록되지 않은 DEPENDENCY_FAILURE로
  고정이라, STREAM_ITEM_TOO_LARGE 같은 carrier 코드가 사라졌다.
- virtual thread profile은 503 + Retry-After를 약속했지만 admission guard는
  bean만 있었고 요청 경로에서 아무도 부르지 않았다.
- web AGENTS B2는 merge patch를 쓰지 않는다고 했고 patch-contract는 필드
  변경에 merge patch를 쓰라고 했다(정본 충돌).

고른 방법:
- 형식이 틀린 patch 문서는 모두 JsonPatchRejectedException(PATCH_REJECTED)
  이다. 본문 파싱과 결과 변환은 PatchBodies가 감싼다. 너무 깊은 pointer는
  권한 검사 앞에서 400으로 거절한다. 대상 타입이 객체가 아닌 것은 서버
  결함이라 IllegalStateException이다.
- 두 applier가 Bean Validation Validator를 받아 결과 객체 전체를 검증한다.
  위반은 @Valid 본문과 같은 ConstraintViolationException → VALIDATION_FAILED.
- writer는 위치가 앞 항목보다 크지 않으면 그 항목을 쓰지 않고 INTERNAL_ERROR
  Failure 기록으로 끝낸다. Failure 기록은 cause 사슬의 carrier 코드, 없으면
  INTERNAL_ERROR, 문구는 category 고정 문구다.
- writer가 할 수 없는 것(heartbeat, idle·max age, 버퍼, drain)은 계약
  문서를 고쳐 누가 하는지(WebStreamPolicy·Registry·DrainCoordinator를 쓰는
  서비스) 적었다. 요청 thread의 동기 writer라 heartbeat를 넣으려면 thread
  모델을 바꿔야 해서 버렸다.
- VirtualThreadAdmissionFilter가 모든 요청을 guard 아래 둔다(request-id
  filter 바로 뒤). async 요청은 async가 끝날 때 permit을 돌려준다. guard에
  Permit API를 더했다.
- 정본 충돌은 리뷰 README 6절 ③대로 patch-contract를 정본으로 두고 web
  AGENTS B2가 그쪽을 가리킨다.

위험·한계: patch를 쓰는 서비스는 applier 생성자에 Validator를 넘겨야
컴파일된다. client가 보는 patch·stream 오류 코드가 바뀐다. virtual thread
profile을 켠 배포는 처음으로 상한에 걸릴 수 있다(upgrade 안내 1~5).

BREAKING CHANGE: JsonMergePatchApplier·JsonPatchApplier 생성자가 Validator를
받는다. patch 거부는 모두 PATCH_REJECTED(400), 결과 제약 위반은
VALIDATION_FAILED, stream Failure 코드는 실패의 코드나 INTERNAL_ERROR다. 할
일은 docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-26, RR9-03-27, RR9-03-28
2026-11-13 04:08:16 +09:00

6.4 KiB

Web Advanced: 지원 매트릭스

Advanced capability는 따로 된 leaf adapter:inbound:web-advanced(src/adapter/inbound/web-advanced, package dev.caskeleton.adapter.inbound.web.advanced)에 있다. 이 leaf를 가진 기본 조립은 없다. app-bootstrap은 이 leaf에 의존하지 않는다. 이 capability 중 하나가 필요한 서비스는 자기 어댑터 leaf에 이 leaf를 implementation으로 더하고 타입을 직접 부른다.

실행 중 스위치가 있는 capability는 셋이고, leaf 자신의 META-INF/spring/...AutoConfiguration.imports로 등록한다. 나머지는 모두 라이브러리다. 속성도 bean도 없고, 서비스 코드가 부르기 전에는 아무 일도 일어나지 않는다.

Capability 켜는 법 더하는 것 테스트
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
JSON Patch(RFC 6902) 라이브러리 — JsonPatchApplier 임의의 pointer JsonPatchApplierTest
CBOR / XML codec 라이브러리 — WebCborMapperFactory, WebXmlMapperFactory. backend jar는 서비스가 고른다 두 번째 decoder WebCodecMapperTest, WebCodecSecurityTest
OpenAPI 3.2 라이브러리 — WebOpenApi32Generator 나란히 만드는 설명 산출물 WebOpenApi32GeneratorTest
messaging에서 stream 다시 보내기 라이브러리 — MessagingReplayBridge 다시 연결한 뒤 이어 받기 MessagingReplayBridgeTest

같은 leaf에 servlet 운영 경로가 닿지 않는 web 라이브러리 package도 있다: http(URI와 method 정책), versioning, operation, budget, contract, security(security context 다리), idempotency(JsonIdempotentResponseCodec), admin/route.

./gradlew :adapter:inbound:web-advanced:test가 전부 돌린다. webAdvancedTest는 tag를 단 부분집합이고, tag가 아무 것도 고르지 않으면 실패한다.

2026-09-25에 지운 것

  • 승격/릴리스 게이트(WebAdvancedPromotionGate, WebAdvancedReleaseManifest, WebAdvancedFeature)와 OpenAPI 3.2 승격 보고서(OpenApi32CompatibilityReport, OpenApiToolchainMatrix). 이 저장소의 릴리스 절차를 검사하는 것이 production 코드에 있었고, 자기 테스트만 그것을 불렀다. 기능 목록은 어떤 코드도 읽지 않는 flag(…json-merge-patch.enabled, …sse.enabled, …cbor.enabled 등)도 적었다.
  • advanced.blockingbridge: WebFlux blocking 다리의 회계 쪽 절반. 어댑터 쪽은 WebFlux 쌍과 함께 사라졌다.
  • functional(FunctionalRouteRegistry, WebFunctionalHandlerAdapter): WebFlux RouterFunction을 만들었는데, servlet만 쓰는 템플릿(D4)에서는 아무것도 그것을 내보내지 않는다. spring-webflux도 함께 leaf를 떠났다.
  • 운영 web 경로가 이미 다른 방식으로 하는 일을 다시 구현한 package들, 그리고 그중 하나만 인증하던 webNginxProxyTest lane:
    • proxy + http.External* — 운영은 server.forward-headers-strategy를 쓴다 (src/bootstrap/app/src/main/resources/config/server.yml).
    • security CORS/CSRF profile — 운영은 CorsSettings와 SecurityConfig를 쓴다.
    • cache — 운영은 CacheControlFilter를 쓴다.
    • json(WebObjectMapperFactory) — 운영은 Boot의 JsonMapper를 쓴다. 스트리밍 encoder도 이제 그 bean으로 쓴다.
    • openapi.WebOpenApiCustomizer(+ WebOpenApiProfile, CursorSchemaContributor) — 운영은 OpenApiContractConfig로 springdoc을 손본다.

되살리는 길은 docs/capability-status.md(제거된 코드 표)에 있다.

거부하는 것과 그 행이 여기 있는 이유

거부 이유
허가 상한 없는 virtual thread pool 크기가 곧 허가 정책이었다. 그것을 없애면 오는 요청을 다 받고, 늘지 않은 하류 예산에 줄 세운다.
필드 허용 목록 밖의 merge patch merge patch는 부분이라, 어떤 DTO의 빠진 필드도 「허락 안 함」을 뜻하지 않는다. 허용 목록이 없으면 누가 필드를 더할 때마다 쓸 수 있는 집합이 커진다.
허락한 접두사보다 위의 JSON Patch pointer 부모를 바꾸면 모든 형제가 지워진다. 그래서 자식에 대한 권한이 부모 권한을 줄 수 없다.
출처가 허락되지 않은 move 목적지만 검사하면 호출자가 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다.
DTD나 외부 entity가 있는 XML Billion-laughs와 XXE. 둘 다 터져도 오류가 나지 않는다. 파싱은 성공하고 문서에 있으면 안 되는 것이 들어 있다.
세 관문을 다 지나지 않은 JSON 아닌 표현 서비스가 RepresentationNegotiationPolicy에 넘기는 켜진 집합, route의 produces, client 허용 목록. Accept 헤더는 그 route가 그 codec으로 시험됐다는 증거가 아니다.
406에서 압축처럼 조용히 물러서기 CBOR만 요청한 client가 JSON을 받으면 그 바이트를 CBOR로 파싱하다 먼 곳에서 실패한다.
commit 뒤 HTTP 상태 바꾸기 본문이 반은 stream, 반은 JSON이 되고, 200이 cache된다.
느린 소비자를 위한 상한 없는 버퍼링 client의 느림을 서버의 heap으로 옮긴다.

끄기

의존성을 빼면 capability가 사라진다. 의존성이 있어도 스위치 셋은 기본으로 꺼져 있다. WebAdvancedRollbackIT가 flag를 하나도 주지 않았을 때와 각 flag를 명시적으로 false로 줬을 때 Advanced bean이 하나도 없음을 단언한다.

docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md, ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md, ADR-WEB-ADV-003-openapi-32-remains-experimental.md를 본다.