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>
This commit is contained in:
DongHyeonka
2026-09-25 12:49:07 +09:00
co-authored by Claude Opus 5.5
parent 208077fddf
commit 6d27356e2b
2822 changed files with 27992 additions and 166879 deletions
+53 -34
View File
@@ -1,58 +1,77 @@
# Web Advanced: support matrix
Every capability is off unless named. `WebAdvancedPromotionGate.forFeature` is the machine-checked
form of the last two columns; if this table disagrees with it, the code wins.
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.
| Capability | Flag | What it adds | Required suites | Soak |
| --- | --- | --- | --- | --- |
| `MVC_VIRTUAL_THREADS` | `backend.web.advanced.mvc-virtual-threads.enabled` | A different scheduling model for **every** request | `web:test`, `webCrossStackParityTest`, `virtual-thread-admission`, `pinning-jfr` | 24h |
| `WEBFLUX_BLOCKING_BRIDGE` | `…webflux-blocking-bridge.enabled` | A bounded offload; affects the shared event loop | `web:test`, `blocking-bridge-bounded`, `event-loop-guard` | 24h |
| `JSON_MERGE_PATCH` | `…json-merge-patch.enabled` | RFC 7396, partial documents | `web:test`, `patch-security`, `patch-atomicity` | 8h |
| `JSON_PATCH` | `…json-patch.enabled` | RFC 6902, arbitrary pointers | as merge patch | 8h |
| `SSE` | `…sse.enabled` | Long-lived connections | `web:test`, `streaming-soak-10k`, `slow-consumer-bounded`, `cancellation-propagation`, `pod-drain` | 24h |
| `NDJSON` | `…ndjson.enabled` | Long-lived connections | as SSE | 24h |
| `JSON_SEQUENCE` | `…json-sequence.enabled` | Long-lived connections | as SSE | 24h |
| `FUNCTIONAL_WEBFLUX` | `…functional-webflux.enabled` | Routes with no annotation to scan | `web:test`, `functional-route-parity` | 8h |
| `CBOR` | `…cbor.enabled` | A second decoder | `web:test`, `codec-security`, `codec-budget` | 8h |
| `XML` | `…xml.enabled` | A decoder with dangerous defaults | as CBOR | 8h |
| `OPENAPI_32` | `…openapi-32.enabled` | A parallel description artifact | `web:test`, `openapi-32-toolchain-matrix` | 8h |
| `RATELIMIT_DRAFT_HEADERS` | `…ratelimit-draft-headers.enabled` | Additive response headers | `web:test`, `ratelimit-draft-headers` | 8h |
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.
## Two capabilities change requests that do not use them
| 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` |
`WebAdvancedFeature.affectsUnrelatedRequests()` is true for exactly `MVC_VIRTUAL_THREADS` and
`WEBFLUX_BLOCKING_BRIDGE`. A codec affects only requests that negotiate it; a virtual-thread
executor affects every request in the process, and the blocking bridge affects the event loop they
all share. `WebAdvancedFeatureFlags.stableBehaviourPreserved()` reports whether either is on.
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`.
That distinction is why those two soak for 24 hours and why their rollback test is the one that
matters most.
`./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 blocking offload for an unregistered operation | `boundedElastic()` is reachable from anywhere and unbounded in practice; an unenumerable set of offloads is invisible until the pool is the heap. |
| 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 | Flag, route `produces`, and client allowlist. An `Accept` header is not evidence the route was tested against that codec. |
| 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. |
## Promotion
## Turning it off
Each capability is promoted on its own evidence. Two conditions apply to all and are not waivable:
- **Rollback exercised.** A flag nobody has turned off is not known to turn off.
- **Stable behaviour unchanged with the feature off.** If it is not, the feature was never optional
and every deployment has it.
Parsers and patch appliers additionally require a security review —
`WebAdvancedPromotionGate.needsSecurityReview` names them.
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
+10 -35
View File
@@ -9,49 +9,24 @@ The value of an API description is entirely in what consumes it. A document in a
generator does not fully understand does not fail — it produces a client that compiles and is wrong,
which is worse than no document at all.
So 3.1.2 stays the release artifact and 3.2 is generated beside it, with a report.
So 3.1.2 stays the release artifact and 3.2 is generated beside it.
## The invariant
**Generating 3.2 must not change the 3.1 snapshot.** Both come from the same model, so a contributor
that mutates it on the way to 3.2 changes the artifact that is actually shipped — silently, and only
when the experimental lane runs.
when 3.2 is generated.
`OpenApi32CompatibilityReport` hashes the snapshot before and after, and a difference is a promotion
blocker with its own message.
Nothing in this repository checks it any more. `OpenApi32CompatibilityReport` and
`OpenApiToolchainMatrix` — the promotion report that hashed the snapshot and recorded which parser,
linter, generator and client compile had read the 3.2 output — were removed on 2026-09-25: they
lived in production code and only their own tests called them. A service that generates 3.2 with
`WebOpenApi32Generator` (library, `adapter:inbound:web-advanced`) owns that check in its own build.
## The toolchain matrix
Four kinds of tool, checked separately, because passing one says nothing about the others:
| Kind | What it catches | What it misses |
| --- | --- | --- |
| Parser | Structural errors | Anything semantically odd |
| Linter | Style rule violations | Accepts documents a parser rejects |
| Generator | Unsupported constructs — sometimes | Usually emits a wrong-but-valid signature instead of failing |
| Client compile | The wrong signature the generator emitted | Runtime behaviour |
`OpenApiToolchainMatrix.complete()` requires at least one passing tool of each kind.
`gaps()` names the kinds that have none.
"OpenAPI 3.2 works" is not a statement anybody can make. "This document is read correctly by these
four tools at these versions" is.
## Streaming descriptions
The substantive difference between 3.1 and 3.2 for this application is how streaming responses are
described. Those differences are reported separately rather than folded into a pass/fail, because a
green pass hides what changed.
## Promotion
`promotionBlockers(adrAccepted)` always includes the ADR blocker until one is accepted, however
green the matrix is. A machine-checkable matrix cannot decide whether the consumer population is
ready; that is a judgement, and it belongs in
Promotion stays a judgement, recorded in
`docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`.
## Running it
The experimental generation runs in its own workflow and publishes the 3.2 document and the
compatibility report as artifacts. It never runs in the release workflow, so the release artifact
cannot depend on whether it ran.
No workflow in this repository generates 3.2. `OpenApiVersionLane.STABLE_3_1` is the release
artifact; `WebOpenApi32GeneratorTest` covers the generator.
+3 -1
View File
@@ -1,6 +1,8 @@
# Web patch: the client contract
Two patch formats, and they are not interchangeable.
Two patch formats, and they are not interchangeable. Both appliers are library code in
`adapter:inbound:web-advanced` (opt-in): a service adds the leaf and calls `JsonMergePatchApplier`
or `JsonPatchApplier` from its controller.
## Choosing one
+61 -141
View File
@@ -6,6 +6,12 @@ was written against a standalone repository. Four of its assumptions do not hold
document records what each became and why, so a reader comparing the design to the tree is not left
guessing whether a difference is a decision or a mistake.
> **2026-09-25 (D4, Wave 2 W2-3).** The template is servlet (Spring MVC) on virtual threads. The
> WebFlux twin, the second-generation problem-document/budget/throttle/admission platform, the
> durable-operation HTTP projection and the in-leaf module-boundary check were removed. HTTP errors
> are the `Envelope` written by `GlobalExceptionHandler`. What was removed, and the commit it last
> existed in, is listed in `docs/capability-status.md` ("제거된 코드").
## 1. Twenty-three Gradle modules became sub-packages of one leaf
The design lays the platform out as `modules/web/web-core-api`, `web-contract`, `web-mvc` and so on.
@@ -14,20 +20,14 @@ list, and adding twenty-three leaves to it is an architecture decision the desig
repository's behalf. The JPA and GraphQL platforms reached the same fork and resolved it the same
way, so this is the established answer rather than a new one.
The substitution only holds if the boundaries are enforced, because a Gradle dependency gate cannot
see inside a leaf. `WebStableModule` declares each module's identity, package, purity grade and
allowed edges; `WebModuleBoundaryTest` scans the real source tree and fails when the tree and the
declaration disagree **in either direction** — an undeclared edge, an undeclared package, or a
declared module with no source. Four negative fixtures prove each rule can fail.
Each enum constant is already shaped like a leaf specification, so promoting a module to its own
Gradle path later is a registry edit rather than an archaeology exercise.
A Gradle dependency gate cannot see inside a leaf. The in-leaf module map that used to check the
package edges (`WebStableModule`) was removed with the second-generation platform; the ArchUnit
rules in `testkit/arch` (`WebArchitectureRules`) are what remains.
| Design module | Package under `dev.caskeleton.adapter.inbound.web` | Status |
| --- | --- | --- |
| `web-core-api` | `core` | planned (Task 2+) |
| `web-contract` | `contract` | planned |
| `web-validation` | `validation` | planned |
| `web-error` | `error` | present |
| `web-pagination` | `pagination` | present |
| `web-idempotency` | `idempotency` | present |
@@ -38,19 +38,16 @@ Gradle path later is a registry edit rather than an archaeology exercise.
| `web-observability` | `observability` | present |
| `web-openapi` | `openapi` | planned |
| `web-mvc` | `mvc` | planned |
| `web-webflux` | `webflux` | planned |
| `web-webflux` | — | removed (D4: servlet only) |
| `web-admin` | `admin` | planned |
| `web-operation-jpa` | `operation.jpa` | planned |
| `web-operation-messaging` | `operation.messaging` | planned |
| `web-spring-boot-starter-mvc` | `autoconfigure.mvc` | planned |
| `web-spring-boot-starter-webflux` | `autoconfigure.webflux` | planned |
| `web-testkit-*` | `testkit`, `testkit.mvc`, `testkit.webflux`, `testkit.contract` | planned |
| — | `conditional`, `cursor`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design |
| `web-spring-boot-starter-webflux` | — | removed (D4: servlet only) |
| `web-testkit-*` | `testkit`, `testkit.mvc` | present |
| — | `conditional`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design |
| — | `fileserver.*`, `notification.*` | present, feature integrations rather than platform modules |
A module is added to `WebStableModule` at the moment its package gains its first file, never before:
a declared module with no source is a claim about a rename that has not happened.
## 2. Root package
The design uses `io.backend.skeleton.web`. This repository's package root is
@@ -78,10 +75,13 @@ carries the OpenAPI drift gate and the contract lanes the design's sample is spe
## 6. Idempotency: the design's store SPI is already owned by `application-core`
The design gives `web-idempotency` its own `IdempotencyStore`, `IdempotencyRecord`,
`IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has all
five in `application-core/idempotency`, with a JPA adapter
(`PostgreSqlOwnerSafeIdempotencyStore`, `IdempotencyStoreAdapter`) and a Redis cache behind them —
which is what the design's Tasks 39 and 40 ask for, built in the direction the registry permits.
`IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has the
equivalents in `application-core/idempotency` — `IdempotencyStorePort`, `IdempotencyState`,
`IdempotencyScopeDigest` and `RequestFingerprint` — with two provider stores behind the port:
PostgreSQL (`PostgreSqlOwnerSafeIdempotencyStore` in `persistence-jpa`) and Redis
(`RedisIdempotencyStoreAdapter` in `cache-redis`), selected by
`ca-skeleton.capabilities.idempotency.provider`. That is what the design's Tasks 39 and 40 ask for,
built in the direction the registry permits.
Implementing the design's SPI literally would have required
`adapter-outbound-persistence-jpa → adapter-inbound-web`, an edge the registry forbids and one that
@@ -97,7 +97,7 @@ application use-case boundary.
| store / record / scope / claim / replay | `application-core/idempotency` |
| request fingerprint policy | application use case, because only the use case knows which fields define the same work |
| `Idempotency-Key` extraction | concrete inbound endpoint that opts into idempotency |
| replay JSON encoding | `adapter-inbound-web/idempotency/JsonIdempotentResponseCodec` |
| replay JSON encoding | `adapter-inbound-web-advanced/idempotency/JsonIdempotentResponseCodec` |
This avoids two authorities for “same request”. The HTTP adapter does not run its own database
replay policy; it translates the transport input into the application idempotency context and lets
@@ -118,7 +118,7 @@ holding a JPA store for long-running operations, with the port
This is the same shape as §6 and takes the same resolution — the one the repository already used
for idempotency, where `IdempotencyStorePort` lives in `application-core` and
`IdempotencyStoreAdapter` in `persistence-jpa`:
`PostgreSqlOwnerSafeIdempotencyStore` in `persistence-jpa`:
| Design type | Here |
| --- | --- |
@@ -128,15 +128,12 @@ for idempotency, where `IdempotencyStorePort` lives in `application-core` and
| the lease | `application-core/operation/OperationLease` |
| the stored failure | `application-core/operation/OperationFailure` — a code and an already-safe message, never an exception |
| `JpaDurableOperationStore`, `JpaOperationEntity`, `V002__web_operation.sql` | `persistence-jpa/operation/*`, `db/migration/postgresql/V11__durable_operation.sql` |
| `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | web `operationasync` — the HTTP projection |
| — | web `operationasync/OperationResourceFactory`, which is the projection itself |
| `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | removed 2026-09-25 — the web `operationasync` projection and `/api/v1/operations` controller had no production wiring and published failures only as `WebProblem` |
The split is not only a registry workaround; it puts each half where its invariants belong. A
problem document is an HTTP concept and has no business being persisted, so the stored failure is a
code plus a safe message and the factory turns it into a `WebProblem` through the same catalog and
the same sanitiser as every synchronous error. An async failure therefore cannot publish something
a synchronous one would have redacted, and a worker cannot extend the published code vocabulary by
writing a row — an unrecognised code becomes `INTERNAL_ERROR`.
code plus a safe message. An HTTP surface for operations, if one is added again, maps it onto the
`Envelope` error contract.
The state machine is enforced three times on purpose: in `DurableOperation`'s constructor, in the
`CHECK` constraints of `V11__durable_operation.sql`, and in the `WHERE` clause of every statement
@@ -147,6 +144,12 @@ no row and it learns that from the affected count.
## 8. Budget enforcement: what the edge stops and what the application stops
> **Removed 2026-09-25.** The servlet budget filter (`WebMvcBudgetFilter`) and its problem mapping
> were deleted with the second-generation platform. The shipped application no longer enforces the
> application column below; the `budget` catalog (`WebRequestBudget`, `WebBudgetCatalog`) remains as
> library code in `adapter:inbound:web-advanced`, and its unused meter (`WebBudgetMeter` and its
> outcome/violation types) was removed. The edge column still applies.
The design (Task 49) requires that the difference between an edge proxy's limits and the
application's own be written down rather than discovered during an incident. Two limits on the same
dimension always exist, they are never equal, and which one fires decides what the caller sees.
@@ -163,8 +166,9 @@ dimension always exist, they are never equal, and which one fires decides what t
Two consequences worth stating, because both are counterintuitive:
**An edge limit below the application's means clients never see a problem document.** nginx answers
its own HTML error page, so a client that branches on `ProblemCode` gets a body it cannot parse.
**An edge limit below the application's means clients never see the application's error body.**
nginx answers its own HTML error page, so a client that branches on `error.code` gets a body it
cannot parse.
Where a dimension matters to clients, the edge limit must be set *above* the application's so the
application is the one that refuses.
@@ -172,61 +176,19 @@ application is the one that refuses.
the process and a body large enough to matter before the application's own meter has counted it.
Both belong; only their ordering is a decision.
The enforcement itself never materializes a body to measure it. `WebBudgetMeter` counts bytes as
they move — through a wrapped `ServletInputStream` on the servlet side and a `doOnNext` on the
buffer flux on the reactive side — and throws at the byte that crosses. A check that read the body
in order to size it would be the heap exhaustion the check exists to prevent, so the contract asserts
directly that an oversized body never reaches the handler in full.
## 9. The Nginx lane (removed 2026-09-25)
On the way out the split is between committed and not:
The `webNginxProxyTest` lane ran the forwarded-header library (`proxy`, `http.External*`) behind a
Testcontainers `nginx:1.27-alpine`. That library was a second way of doing what the shipped path
does with `server.forward-headers-strategy`, so the library and its lane were removed together
(`docs/capability-status.md`, "제거된 코드").
- **Not committed** — the response is reset, which discards the partial body *and* the meter's
count of it, and the overrun is answered as a problem document. Resetting only the buffer was the
first implementation and it failed: the meter still held the count of the discarded bytes, so the
small problem document was refused too and the client got the container's error page.
- **Committed** — there is no status left to send. The exception propagates, the connection ends
mid-document, and the client sees a truncated response. That is worse for the client than a clean
error and better than a short response it would accept as complete.
Statuses are never restated. `BudgetProblemMapper.statusFor` reads `ProblemCatalog` through the
violation's code; an earlier draft kept its own violation-to-status table and disagreed with the
catalog on two entries, which `requireStatusAgreement` turned into a 500. One table, no drift.
## 9. The Nginx lane: what a real proxy caught that no unit test could
Task 55 asks for the proxy contract to be verified against a real Nginx. It is implemented as a
separate `nginxProxyTest` source set with a Testcontainers-managed `nginx:1.27-alpine`, run by
`./gradlew :adapter:inbound:web:webNginxProxyTest`. Its own lane because it is the only one that
needs Docker; folded into `test`, every developer's `check` would depend on a container runtime,
and the usual end of that is an `@Disabled` nobody notices.
**TLS is terminated in configuration, not in the container.** The design describes an `ssl` listener.
What the application can observe about TLS is exactly one thing — that the edge set
`X-Forwarded-Proto: https` authoritatively — and a proxy that terminates TLS and one that declares
the scheme produce an identical request upstream. Generating a certificate per run would add a
second failure mode to a lane whose subject is header handling. The lane asserts the observable
property; it does not assert that Nginx can do TLS.
**The defect the lane found on its first run.** The first configuration set the forwarded headers
once at the `server` level and added only `X-Forwarded-Prefix` per `location`. Six of the ten cases
failed. Nginx's inheritance rule for array directives is *replacement*: a single `proxy_set_header`
inside a `location` discards every `proxy_set_header` inherited from `server`. So none of the
security headers were sent, the application fell back to the upstream's own `Host`, and a client's
`X-Forwarded-Host` would have been trusted.
That configuration reads as correct, is a shape found throughout the wild, and no test of the
application could detect it — the application's forwarded-header handling is thoroughly unit-tested
and every one of those tests still passed. The bug lived entirely in the seam. The headers now live
in `proxy_headers.conf` and are `include`d by each location.
| Bound | Where it fires | What the client sees |
| --- | --- | --- |
| `client_max_body_size 2m` | Nginx, before the application | Nginx's HTML 413, no problem document |
| application `maxBodyBytes` | the application | RFC 9457 problem, `REQUEST_TOO_LARGE` |
| unknown prefix | Nginx | 404; only `/api/` and `/dev-api/` are routed at all |
The first row is the §8 table's consequence made concrete: an edge limit below the application's
means clients never see a problem document for that dimension.
One finding from that lane still applies to any Nginx in front of this service. Nginx's
inheritance rule for array directives is *replacement*: a single `proxy_set_header` inside a
`location` discards every `proxy_set_header` inherited from `server`. Setting the forwarded headers
once at `server` level and adding only `X-Forwarded-Prefix` per `location` therefore sends none of
the others, and the application falls back to the upstream's own `Host`. Keep the forwarded headers
in one included file and `include` it in every `location`.
## Advanced capabilities
@@ -240,23 +202,15 @@ What the design wanted from the separation is enforced instead by two machine ch
- **`WEB-ARCH-ADV`** in `WebArchitectureRules.stableDoesNotDependOnAdvanced()` fails the build when a
Stable class names an Advanced type. A feature flag decides whether a bean is created; it does
nothing about a compile-time edge, and one such edge makes Stable unbuildable without Advanced.
- **`WebStableModule`** declares eleven Advanced module identities with their own purity and edge
sets, checked by `WebModuleBoundaryTest`. Nine of the eleven are `CORE` — pure policy with no
framework import — which is stricter than the design's Gradle layout would have been.
Two modules are `FRAMEWORK_BOUND` and had to be: `advanced-patch` and `advanced-codec`. Jackson's
tree model is the reason for the first — a merge patch's null-means-delete has no representation in
a Java object, so the applier works on nodes — and `XMLInputFactory` is the reason for the second.
A third, `advanced-stream-encoding`, is separated from the pure `advanced-stream` for the same
reason: framing serializes, and serializing binds to Jackson.
`advanced.patch` and `advanced.codec` bind to a framework and had to: Jackson's tree model is the
reason for the first — a merge patch's null-means-delete has no representation in a Java object, so
the applier works on nodes — and `XMLInputFactory` is the reason for the second.
`advanced.stream.encoding` is separated from `advanced.stream` for the same reason: framing
serializes, and serializing binds to Jackson.
### What was adapted rather than copied
**`WebStreamEnvelope.Error` is named `Failure`.** A nested type called `Error` shadows
`java.lang.Error` inside its own file, so an unrelated `catch (Error e)` there would catch the wrong
thing. Error Prone's `JavaLangClash` refuses it outright, and the rename is the only difference from
the design's sealed hierarchy.
**`WebStreamErrorPolicy`'s factory methods are `startOver` / `resumeFromPosition` / `nothingToDo`.**
The design's names collided with the record's own accessors, which Java rejects.
@@ -288,13 +242,11 @@ coordinate. `RepresentationBackendScopeTest` reads `build.gradle` and fails if e
returns to `implementation`, because nothing else catches it — the codec's own tests pass either
way, and the failure only appears in whatever composes this leaf.
**The framing and the writers are separate, and both exist.** `NdjsonFraming` and
`JsonSequenceFraming` hold the contract; `MvcStreamWriter`, `WebFluxStreamWriter` and
`WebFluxSseAdapter` are what actually put it on a response. There is no MVC SSE writer: this
repository's `NO_SSE_EMITTER` ArchUnit rule forbids `SseEmitter` outright, so the servlet stack
streams NDJSON and JSON-seq and SSE is reactive-only. An earlier pass
stopped after the framing, which left the platform advertising SSE while nothing could serve it —
the same "control reached by nothing" shape this leaf has caught five other times.
**The framing and the writer are separate.** `NdjsonFraming` and `JsonSequenceFraming` hold the
contract; `MvcStreamWriter` is what puts it on a response. There is no MVC SSE writer: this
repository's `NO_SSE_EMITTER` ArchUnit rule forbids `SseEmitter` outright, and the only SSE writer
was the WebFlux one removed on 2026-09-25. So the servlet stack streams NDJSON and JSON-seq, and SSE
is framing-only — nothing serves it until a servlet writer exists.
**`MessagingReplayBridge` is `WebStreamReplaySource`, an interface this module implements nowhere.**
The design's requirement is that the web module store no durable event history; an implementation
@@ -302,50 +254,18 @@ here would be the thing it forbids.
### What the execution layer had to get right
Three of these were only found by building the adapter rather than the policy.
**A merged heartbeat means a finished source never completes.** `Flux.interval` is infinite, so
`source.mergeWith(heartbeat)` holds the connection for the full `maxStreamAge` after the last item —
thirty minutes of keepalives on a stream that ended. `WebFluxSseAdapter` therefore ends at the
terminal envelope (`takeUntil`), and supplies one for a source that finished without emitting its
own.
**`onBackpressureBuffer(n)` does not close anything.** It propagates demand, so a subscriber that
stops requesting simply stops the source and the bound never fires. That is correct for a
well-behaved source and useless as a slow-consumer policy, because the sources this carries push
whether or not anybody asked. The working composition is `onBackpressureBuffer(n)` followed by
`onBackpressureError()`, verified by mutation: removing the second half makes both slow-consumer
tests fail. The merge prefetch is set to the same `n`, because its default of 256 would otherwise
be a larger backlog sitting behind the configured one.
**The blocking bridge's permit cannot be released in `doFinally`.** That fires on the subscriber's
cancel signal, which arrives while the callable is still blocked on a thread — releasing there hands
the permit to another caller while the first still holds the database connection it was accounting
for. Acquire and release are in the same `try`/`finally` inside the callable, and the consequence,
stated rather than hidden, is that cancellation does not interrupt a blocking call.
On the servlet side the equivalent is that there is no disconnect event at all: the first sign a
client is gone is a write that throws, which is why the heartbeat is the probe rather than a
On the servlet stack there is no disconnect event at all: the first sign a client is gone is a write that throws, which is why the heartbeat is the probe rather than a
courtesy and why a failed beat is recorded as disconnect evidence.
### One pre-existing flake was fixed
`HttpThrottleFixture.awaitSlotTaken` polled for a 503 while each probe spent quota, and refilled the
quota only after the loop. On a machine loaded enough that the holding request took a while to
occupy the slot, the quota ran out first and every remaining probe answered 429 — so the loop never
saw its 503 and failed on the deadline, which reads as a capacity bug and is a fixture bug. It now
refills before every probe and fails loudly if a probe is refused for quota immediately after a
refill. Found because the new virtual-thread and blocking-bridge tests load the machine enough to
trigger it.
### Verification
```bash
cd src
./gradlew :adapter:inbound:web:test # 861 tests, Advanced included
./gradlew :adapter:inbound:web:webAdvancedTest # 147, the Advanced lane on its own
./gradlew :adapter:inbound:web:webCrossStackParityTest
./gradlew :adapter:inbound:web:webNginxProxyTest # Docker
./gradlew :adapter:inbound:web:test # the shipped web leaf
./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
./gradlew :adapter:inbound:web:webJettyCompatTest # Jetty, real socket
./gradlew :adapter:inbound:web-advanced:test # the opt-in Advanced leaf
./gradlew :adapter:inbound:web-advanced:webAdvancedTest # the tagged Advanced lane
```
See `docs/web/advanced-capabilities.md`, `docs/web/streaming-contract.md`,
+34 -54
View File
@@ -3,68 +3,48 @@
What an operator needs when the HTTP boundary misbehaves. Organised by what you observe, because
that is what you have at 3am — not by which module owns it.
## Reading the two "too much traffic" answers
## Reading a `429`
The platform never answers these two interchangeably, and the difference tells you where to look.
`RateLimitInterceptor` answers `429 RATE_LIMIT_EXCEEDED` with `Retry-After` when the edge rate
limit refuses a caller. `RATE_LIMIT_UNAVAILABLE` means the rate-limit store could not be reached,
not that the caller exceeded anything — look at the store, not the caller.
| You see | It means | Where to look |
| --- | --- | --- |
| `429 RATE_LIMITED` climbing for one caller | that caller exceeded its quota | the caller. Nothing is wrong with the service. |
| `429` climbing across **all** callers | quota is being charged for requests the service then shed | look at 503 first; see below |
| `503 ADMISSION_REJECTED` | the service has no capacity | saturation: check the admission profile's concurrency and what is holding slots |
## Errors that are not the `Envelope`
The second row is a real consequence of the design and worth knowing before it confuses you. Quota
is charged *before* capacity is requested, deliberately — the reverse order lets a caller who is
about to be rate-limited occupy a slot on the way to being told so. Under sustained overload every
caller's quota therefore drains on requests that never ran. **Rising 429 during an incident is a
symptom of shedding, not of callers misbehaving.** Read the 503 rate first.
Every HTTP error the application writes is the `Envelope` from `GlobalExceptionHandler`
(`spring.mvc.problemdetails.enabled=false`), with an `error.code` a client branches on.
## A control that appears configured and does nothing
This has happened here, and the failure is silent by construction. A configured-but-unwired control
behaves exactly like a working one until it is needed.
- **Check first:** the platform snapshot's `uninstalledControls()`. `WebPlatformStartupValidator`
fails startup on a missing required control, so a running instance with one missing means it was
not in the required list.
- **The instance found the hard way:** the problem catalog was complete, fully unit-tested, and
reached by nothing on the framework's error path. Spring answered failures with its own
`ProblemDetail` — RFC 9457-shaped, so it looked correct — carrying no `code` field. It was found
by a cross-stack parity recording, not by any test of the catalog.
- **How to confirm quickly:** send a request that must fail validation and check the body has a
`code`. No `code` means the platform's handler is not installed.
- **How to confirm quickly:** send a request that must fail validation and check the body has
`error.code`. A body without it (Spring's `ProblemDetail`, or the container's error page) means
the handler is not installed or the response came from the edge.
## A response is truncated or the connection dies mid-document
Two different causes, distinguished by the status the client did receive.
- **Client got a status, then nothing** — the response budget was crossed after commit. The
platform cannot retract a status, so it ends the connection: a truncated response the client
rejects is better than a short one it accepts as complete. Raise `maxResponseBytes` for that
operation's profile, or make the endpoint paginate.
- **Client got nothing at all** — either the request budget was crossed before headers, in which
case there is a problem document, or the proxy refused it. `client_max_body_size` in nginx is
below the application's body budget by default, and nginx answers with its own HTML rather than a
problem document. See `repository-adaptation.md` §8 for which bound fires where.
- **Client got a status, then nothing** — the response failed after commit. The status cannot be
retracted, so the connection ends mid-document.
- **Client got nothing from the application** — the proxy refused it. `client_max_body_size` in
nginx answers with its own HTML rather than the `Envelope`. See `repository-adaptation.md` §8.
## A retried write happened twice
The idempotency key is the control, and there are exactly three ways it fails to apply.
1. **The client did not send one.** The operation profile says `OPTIONAL`, so it ran unguarded.
Change the profile to `REQUIRED` if a duplicate is unacceptable.
2. **The client sent a different body.** Answered `422 IDEMPOTENCY_KEY_REUSED`, never a replay —
replaying would hand back a receipt for a request the caller never made.
1. **The client did not send one.** The endpoint does not require the key, so it ran unguarded.
Require it if a duplicate is unacceptable.
2. **The client sent a different body.** Answered `422 IDEMPOTENT_REQUEST_MISMATCH`, never a
replay — replaying would hand back a receipt for a request the caller never made.
3. **The record expired.** TTL is per-operation with a 72h cap. A retry after expiry is a new
request by definition.
A `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` is not a failure: an earlier attempt is still running and
A `409 IDEMPOTENT_IN_FLIGHT` is not a failure: an earlier attempt is still running and
the caller should retry after `Retry-After`.
## Rolling deploy stalls with instances half-drained
`shutDownGracefully` waits for in-flight work, and on Reactor Netty an open-but-idle keep-alive
connection counts as in-flight. Calling `stop()` while that wait is in progress hangs.
`shutDownGracefully` waits for in-flight work, and an open-but-idle keep-alive connection can count
as in-flight. Calling `stop()` while that wait is in progress hangs.
- **Symptom:** an instance neither serving nor exiting, no error in its log.
- **Cause:** an unbounded graceful wait. `GracefulShutdownProbe` bounds it at a stated grace period
@@ -74,9 +54,8 @@ connection counts as in-flight. Calling `stop()` while that wait is in progress
## Metrics stopped arriving, or the bill jumped
Almost always a high-cardinality tag. `WebMetricCardinalityPolicy` refuses anything off an
eight-name allowlist at the point of recording, so a new tag cannot appear by accident — but a
`routeTemplate` carrying a *resolved* path can, and that is one series per resource.
Almost always a high-cardinality tag — typically a `routeTemplate` carrying a *resolved* path, which
is one series per resource.
- **Check:** the tag values in the metrics backend for `routeTemplate`. Braces mean templates;
identifiers mean the resolved path leaked through.
@@ -85,14 +64,17 @@ eight-name allowlist at the point of recording, so a new tag cannot appear by ac
## Cross-origin requests fail only in the browser
The API answers correctly and the browser refuses the response. Everything below is refused at
startup by `WebCorsPolicyValidator`, so a running instance with one of these means the profile was
built somewhere that does not validate.
The API answers correctly and the browser refuses the response. CORS is `CorsSettings`
(`ca-skeleton.cors.*`) applied by `SecurityConfig`. Startup refuses two settings:
- `*` with credentials — no browser honours it.
- An origin with a path, a trailing slash, or uppercase — never matches what the browser sends.
- `https://*.example.com` — matches nothing; CORS compares origins exactly.
- Wildcard `allowedHeaders` on a credentialed profile — not honoured with credentials.
- `APP_SECURITY_CORS_ENABLED=true` with no origin.
- `*` in `APP_SECURITY_CORS_ORIGINS` with `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true` — no browser
honours it.
Two more start fine and still fail in the browser:
- `https://*.example.com` in the origin list — it is compared as a literal and matches nothing.
- An origin with a path (`https://app.example.com/ui`) — an origin is scheme, host and port only.
A preflight answered `401` means CORS ran after authentication. Preflights carry no credentials by
design; the order is asserted by `WebPipelineOrderContract`.
@@ -109,8 +91,6 @@ both times, and every latency percentile computed from that data is wrong while
```bash
cd src
./gradlew :adapter:inbound:web:test # unit, boundary, architecture
./gradlew :adapter:inbound:web:webCrossStackParityTest # Tomcat vs Jetty vs Reactor Netty
./gradlew :adapter:inbound:web:webNginxProxyTest # real proxy; needs Docker, fails without it
./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
./gradlew :adapter:inbound:web:webJettyCompatTest # second servlet container
./gradlew :adapter:inbound:web:webFluxContractTest # reactive stack
```
+9 -3
View File
@@ -1,6 +1,12 @@
# Web streaming: the client contract
What a client must implement to consume SSE, NDJSON or `application/json-seq` from this platform.
What a client must implement to consume NDJSON or `application/json-seq` from this platform. SSE
framing exists, but since the WebFlux twin was removed (2026-09-25) nothing on the servlet stack
writes it.
The writers ship in `adapter:inbound:web-advanced` (opt-in, switched by
`backend.web.advanced.ndjson.enabled` / `backend.web.advanced.json-sequence.enabled`); no default
composition carries them.
## Three outcomes, not two
@@ -8,8 +14,8 @@ After the first byte the HTTP status is 200 and cannot change. So the status tel
whether the stream succeeded, and a closed connection is ambiguous. There are three endings:
1. **A `Complete` envelope.** The stream finished. `lastSequence` is the final position.
2. **A `Failure` envelope.** Something failed after commit. Carries a `ProblemCode` and a
client-safe message. The status is still 200.
2. **A `Failure` record.** Something failed after commit. Carries an error code and a client-safe
message. The status is still 200.
3. **Neither.** The connection closed mid-stream. The server records this as `ABRUPT_CLOSE`; from
the client's side it is indistinguishable from a completed stream *unless the client is looking
for the terminal envelope*.
+6 -6
View File
@@ -16,7 +16,8 @@ that used to be shed at the front door is shed at the back, after the cost of ac
## Enabling it
Two settings, and the profile refuses to be constructed with only one:
The profile ships in `adapter:inbound:web-advanced`, which no default composition carries. Add
that leaf to the service, then two settings — the profile refuses to be constructed with only one:
```yaml
backend:
@@ -70,9 +71,8 @@ never used virtual threads at all.
## Rolling back
Set `enabled: false`. The rollback test asserts that Stable behaviour is then identical — if it is
not, the feature was never optional and every deployment has it.
Set `enabled: false`, or drop the leaf. The rollback test asserts that Stable behaviour is then
identical — if it is not, the feature was never optional and every deployment has it.
This is one of only two web Advanced capabilities that affect requests which do not use them (the
other is the WebFlux blocking bridge), which is why its soak is 24 hours and its rollback test is
the one that matters most.
This is the only web Advanced capability that affects requests which do not use them, which is why
its rollback test is the one that matters most.