Files
clean-architecture-backend-…/docs/web/advanced-capabilities.md
T
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00

5.8 KiB

Web Advanced: support matrix

The Advanced capabilities live in their own leaf, adapter:inbound:web-advanced (src/adapter/inbound/web-advanced, package dev.caskeleton.adapter.inbound.web.advanced). No default composition carries it: app-bootstrap은 이 leaf에 의존하지 않는다. A service that wants one of these capabilities adds the leaf as implementation in its own adapter leaf and calls the types directly.

Three capabilities have a runtime switch, published through the leaf's own META-INF/spring/...AutoConfiguration.imports. Everything else is a library: no property, no bean, nothing happens until service code calls it.

Capability How it is turned on What it adds Tests
MVC virtual threads app.web.advanced.mvc-virtual-threads.enabled=true (+ admission limit and budgets) A different scheduling model for every request MvcAdvancedConfigurationTest, VirtualThreadAdmissionTest
NDJSON streaming app.web.advanced.ndjson.enabled=true Long-lived connections MvcStreamingWiringTest, WebStreamCoreTest, WebStreamDrainTest, WebStreamingSoakIT
JSON text sequences (RFC 7464) app.web.advanced.json-sequence.enabled=true Long-lived connections as NDJSON
JSON Merge Patch (RFC 7396) library — JsonMergePatchApplier Partial documents JsonMergePatchApplierTest
JSON Patch (RFC 6902) library — JsonPatchApplier Arbitrary pointers JsonPatchApplierTest
CBOR / XML codecs library — WebCborMapperFactory, WebXmlMapperFactory; the backend jar is the service's choice A second decoder WebCodecMapperTest, WebCodecSecurityTest
OpenAPI 3.2 library — WebOpenApi32Generator A parallel description artifact WebOpenApi32GeneratorTest
Stream replay from messaging library — MessagingReplayBridge Resume after reconnect MessagingReplayBridgeTest

The same leaf also holds the web library packages the servlet production path never reaches: http (URI and method policy), versioning, operation, budget, contract, security (security-context bridge), idempotency (JsonIdempotentResponseCodec) and admin/route.

./gradlew :adapter:inbound:web-advanced:test runs all of it. webAdvancedTest is the tagged subset and fails when the tag selects nothing.

Removed on 2026-09-25

  • The promotion/release gate (WebAdvancedPromotionGate, WebAdvancedReleaseManifest, WebAdvancedFeature) and the OpenAPI 3.2 promotion report (OpenApi32CompatibilityReport, OpenApiToolchainMatrix). They were checks on this repository's release process kept in production code, and only their own tests called them. The feature catalog also named flags that no code reads (…json-merge-patch.enabled, …sse.enabled, …cbor.enabled and others).
  • advanced.blockingbridge: the accounting half of the WebFlux blocking bridge, whose adapter went with the WebFlux twin.
  • functional (FunctionalRouteRegistry, WebFunctionalHandlerAdapter): it built a WebFlux RouterFunction, which nothing serves in a servlet-only template (D4). spring-webflux left the leaf with it.
  • Packages that re-implemented what the production web path already does another way, and the webNginxProxyTest lane that certified only one of them:
    • proxy + http.External* — production uses server.forward-headers-strategy (app-bootstrap/src/main/resources/config/server.yml).
    • security CORS/CSRF profiles — production uses CorsSettings and SecurityConfig.
    • cache — production uses CacheControlFilter.
    • json (WebObjectMapperFactory) — production uses Boot's JsonMapper; the streaming encoder now writes with that bean.
    • openapi.WebOpenApiCustomizer (+ WebOpenApiProfile, CursorSchemaContributor) — production customizes springdoc through OpenApiContractConfig.

Recovery paths are in docs/capability-status.md (the removed-code table).

What is refused, and why the row is here

Refused Reason
Virtual threads without an admission limit The pool size was the admission policy. Removing it accepts every arrival and queues them on downstream budgets that did not grow.
A merge patch outside its field allowlist A merge patch is partial, so no DTO's absent fields say "not permitted". Without an allowlist the writable set grows every time somebody adds a field.
A JSON Patch pointer above its allowed prefix Replacing a parent deletes every sibling, so permission on a child cannot grant it.
A move whose source is unauthorized Checking only the destination lets a caller relocate data out of a field they may not touch.
XML with a DTD or an external entity Billion-laughs and XXE. Neither errors when it fires; the parse succeeds and the document contains something it should not.
A non-JSON representation without all three gates The enabled set the service passes to RepresentationNegotiationPolicy, route produces, and client allowlist. An Accept header is not evidence the route was tested against that codec.
Compression-style silent fallback on a 406 A client that asked only for CBOR and gets JSON parses the bytes as CBOR and fails somewhere far away.
Changing HTTP status after commit The body becomes half stream, half JSON, and the 200 is cached.
Unbounded buffering for a slow consumer It moves the client's slowness into the server's heap.

Turning it off

Removing the dependency removes the capability. With the dependency present, the three switches default to off; WebAdvancedRollbackIT asserts that no Advanced bean exists with no flag set and with each flag explicitly false.

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