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:
co-authored by
Claude Opus 5.5
parent
208077fddf
commit
6d27356e2b
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
```
|
||||
|
||||
@@ -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*.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user