문제: 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.
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`은 이 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`.
|