Files
clean-architecture-backend-…/docs/web/advanced-capabilities.md
T
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
  바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
  httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태

Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 17:01:54 +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 and sample-portfolio do not depend on it. 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.