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

79 lines
5.8 KiB
Markdown

# 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`.