- 결정 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>
79 lines
5.8 KiB
Markdown
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 | `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`.
|