Files
clean-architecture-backend-…/docs/web/advanced-capabilities.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +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 backend.web.advanced.mvc-virtual-threads.enabled=true (+ admission limit and budgets) A different scheduling model for every request MvcAdvancedConfigurationTest, VirtualThreadAdmissionTest
NDJSON streaming backend.web.advanced.ndjson.enabled=true Long-lived connections MvcStreamingWiringTest, WebStreamCoreTest, WebStreamDrainTest, WebStreamingSoakIT
JSON text sequences (RFC 7464) backend.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.