Files
clean-architecture-backend-…/docs/web/advanced-capabilities.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

6.3 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(+ 허가 상한과 예산) 모든 요청에 대한 다른 스케줄링 모델 MvcAdvancedConfigurationTest, VirtualThreadAdmissionTest
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를 본다.