# Conflicts: # docs/ci-cd/template-vs-consumer.md # src/platforms/grpc/CLAUDE.md
285 lines
18 KiB
Markdown
285 lines
18 KiB
Markdown
# Web platform — repository adaptation
|
|
|
|
The inbound HTTP API execution platform design
|
|
(`docs/history/packages/web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md`)
|
|
was written against a standalone repository. Four of its assumptions do not hold here, and this
|
|
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.
|
|
This repository's `src/config/architecture/modules.json` is a fail-closed registry that owns the leaf
|
|
list, and adding twenty-three leaves to it is an architecture decision the design cannot make on the
|
|
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.
|
|
|
|
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-error` | `error` | present |
|
|
| `web-pagination` | `pagination` | present |
|
|
| `web-idempotency` | `idempotency` | present |
|
|
| `web-idempotency-jpa` | `idempotency.jpa` | planned |
|
|
| `web-idempotency-redis` | `idempotency.redis` | planned |
|
|
| `web-versioning` | `versioning` | planned |
|
|
| `web-security-integration` | `auth`, `authz` | present |
|
|
| `web-observability` | `observability` | present |
|
|
| `web-openapi` | `openapi` | planned |
|
|
| `web-mvc` | `mvc` | 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` | — | 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 |
|
|
|
|
## 2. Root package
|
|
|
|
The design uses `io.backend.skeleton.web`. This repository's package root is
|
|
`dev.caskeleton.adapter.inbound.web`, and the registry, the ArchUnit rules and the composition root's
|
|
component scan are all written against it.
|
|
|
|
## 3. Gradle DSL
|
|
|
|
The design's snippets are Kotlin DSL. Every build file in this repository is Groovy DSL, and
|
|
`src/build-logic` carries the shared convention plugins the leaf inherits. The build logic is
|
|
translated, not copied.
|
|
|
|
## 4. Spring Boot baseline
|
|
|
|
The design names "Spring Boot 4.1 BOM". This repository's baseline is **4.0.8** — see
|
|
`.vscode/settings.json` for why the 4.1 minor line is a planned migration rather than a currency
|
|
fix. Where the design depends on a 4.1-only API the difference is recorded at the call site rather
|
|
than silently absorbed.
|
|
|
|
## 5. Sample application
|
|
|
|
설계의 `examples/web-platform-sample`에 해당하는 모듈은 없다. 그 역할을 하던 샘플 leaf는 2026-11-07에
|
|
지웠고, 그 안의 OpenAPI 드리프트 검사와 실서버 계약 lane도 함께 사라졌다. 예시는 `docs/manual/`과
|
|
`scripts/new-feature.sh` 출력이 맡는다.
|
|
|
|
## 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 the
|
|
equivalents in `application-core/idempotency` — `IdempotencyStorePort`, `IdempotencyState`,
|
|
`IdempotencyScopeDigest` and `RequestFingerprint` — with two provider stores behind the port:
|
|
PostgreSQL (`PostgreSqlIdempotencyStore` in `persistence-jpa`) and Redis
|
|
(`RedisIdempotencyStoreAdapter` in `cache-redis`), selected by
|
|
`app.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
|
|
points the wrong way regardless: the store is an application concern that two transports could
|
|
share, not something the HTTP layer owns.
|
|
|
|
So the web leaf keeps only the part that is genuinely HTTP: JSON encoding of a replayed
|
|
application result. Claiming, scope, fingerprint construction and replay policy remain at the
|
|
application use-case boundary.
|
|
|
|
| Design concern | Here |
|
|
| --- | --- |
|
|
| 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-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
|
|
the use case own duplicate execution.
|
|
|
|
## 7. Durable operations: the design's `web-operation-jpa` cannot exist here
|
|
|
|
The design gives the web platform its own persistence module — `modules/web/web-operation-jpa` —
|
|
holding a JPA store for long-running operations, with the port
|
|
(`DurableOperationStore`) in `web-core-api` beside `WebProblem`.
|
|
|
|
`src/config/architecture/modules.json` forbids both halves of that:
|
|
|
|
- `:adapter:inbound:web` may depend only on `domain-core`, `application-core` and
|
|
`shared-contract`, so the web leaf cannot take a JPA dependency.
|
|
- `:adapter:outbound:persistence-jpa` is an outbound adapter and cannot depend on an inbound one,
|
|
so a JPA store cannot see a web type.
|
|
|
|
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
|
|
`PostgreSqlIdempotencyStore` in `persistence-jpa`:
|
|
|
|
| Design type | Here |
|
|
| --- | --- |
|
|
| `DurableOperationStore` | `application-core/operation/DurableOperationStorePort` |
|
|
| `OperationSubmission` | `application-core/operation/DurableOperationSubmission` |
|
|
| the stored operation | `application-core/operation/DurableOperation` |
|
|
| 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` | 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.
|
|
|
|
The HTTP surface was added back on 2026-09-25 (owner decision 15) as a thin transport over the
|
|
application use cases: `adapter:inbound:web` `operation/DurableOperationController` —
|
|
`POST /operations` (202 + `Location`), `GET /operations/{id}`, `DELETE /operations/{id}` (202),
|
|
answers in the `Envelope` contract, and a caller's operation that is not theirs is the same 404
|
|
(`OPERATION_NOT_FOUND`) as one that does not exist. The controller and the three use cases are
|
|
assembled by `composition:durable-operation` (`DurableOperationAutoConfiguration`), which turns on only
|
|
when the operation store and the outbox append port exist (the JPA module with
|
|
`app.outbox.enabled=true`). Submit and cancel need `operation:submit` / `operation:cancel`
|
|
(that module's `config/module-defaults/durable-operation.yml` grants both to the `operation-submit`
|
|
role).
|
|
|
|
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
|
|
that changes a row. The constructor catches application bugs, the constraints catch any other
|
|
writer, and the predicates make each transition atomic — a worker whose lease lapsed while it was
|
|
still working cannot record a result over the worker that took over, because its `UPDATE` matches
|
|
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.
|
|
|
|
| Dimension | Edge (nginx) | Application | Who answers when crossed |
|
|
| --- | --- | --- | --- |
|
|
| Request line / URI | `large_client_header_buffers` (default 8k) | `maxUriBytes` | Edge first — nginx answers 414 with its own HTML |
|
|
| Request headers | `large_client_header_buffers` | `maxHeaderBytes` | Edge first — nginx 400, no problem document |
|
|
| Request body | `client_max_body_size` (default 1m) | `maxBodyBytes` (platform ceiling 8 MiB) | Whichever is smaller; nginx answers 413 with HTML |
|
|
| Query parameter count | not enforced | `maxQueryParameters` | Application, always |
|
|
| JSON depth / array size | not enforced | `maxJsonDepth`, `maxArrayElements` | Application, always |
|
|
| Execution time | `proxy_read_timeout` (default 60s) | `maxExecutionTime` (ceiling 2 min) | Edge first if the platform's is larger |
|
|
| Response size | not enforced | `maxResponseBytes` (ceiling 32 MiB) | Application, always |
|
|
|
|
Two consequences worth stating, because both are counterintuitive:
|
|
|
|
**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.
|
|
|
|
**An edge limit above the application's is not redundant.** It is the only thing standing between
|
|
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.
|
|
|
|
## 9. The Nginx lane (removed 2026-09-25)
|
|
|
|
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`, "제거된 코드").
|
|
|
|
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
|
|
|
|
The Advanced expansion plan asks for eleven Gradle modules under `modules/web-advanced/`. They are
|
|
packages under `advanced.**` in this leaf, for the reason the Stable platform is one leaf:
|
|
`src/config/architecture/modules.json` is fail-closed and owns the leaf list, and eleven entries to
|
|
satisfy a directory layout is a registry change rather than an architecture one.
|
|
|
|
What the design wanted from the separation is enforced instead by two machine checks:
|
|
|
|
- **`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.
|
|
|
|
`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
|
|
|
|
**`WebStreamErrorPolicy`'s factory methods are `startOver` / `resumeFromPosition` / `nothingToDo`.**
|
|
The design's names collided with the record's own accessors, which Java rejects.
|
|
|
|
**The codec backends are compile-only, and finding out why cost a broken composition root.**
|
|
`WebCborMapperFactory` and `WebXmlMapperFactory` are implemented, along with the parts that carry
|
|
the failure modes: `SecureXmlInputFactory` (the DTD and external-entity defaults, both of which
|
|
produce no error when they fire), `CodecBudget` (per representation, because a megabyte of CBOR can
|
|
declare an array of a billion elements in a handful of bytes), and `RepresentationNegotiationPolicy`
|
|
(three gates, because an `Accept` header is not evidence the route was tested against that codec).
|
|
|
|
`jackson-dataformat-cbor` and `jackson-dataformat-xml` were declared `implementation` first, so that
|
|
a missing backend could not surface as a `NoClassDefFoundError` at the first request that negotiated
|
|
one. That reasoning was wrong about what the jars do. Spring Boot's Jackson auto-configuration
|
|
registers an `xmlMapper` and a `cborMapper` bean the moment each backend is on the runtime
|
|
classpath, and Spring registers an XML message converter with it. Two things followed, and only the
|
|
first was noisy:
|
|
|
|
- The composition root held three `ObjectMapper` beans — `webStrictObjectMapper`, `xmlMapper`,
|
|
`cborMapper` — so every `@Autowired ObjectMapper` became ambiguous and the application would not
|
|
start. Six `app-bootstrap` tests failed with `UnsatisfiedDependencyException`.
|
|
- Every deployment silently began accepting `application/xml` request bodies. An XXE surface,
|
|
acquired by adding a dependency, on a capability that is supposed to be off unless a deployment
|
|
names it.
|
|
|
|
So both are `compileOnly` plus `testImplementation`: the factories compile, their tests run against
|
|
real backends, and the runtime classpath belongs to the deployment that enables the capability.
|
|
`WebRepresentation.available()` turns an absent backend into a sentence naming the missing
|
|
coordinate. `RepresentationBackendScopeTest` reads `build.gradle` and fails if either coordinate
|
|
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 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
|
|
here would be the thing it forbids.
|
|
|
|
### What the execution layer had to get right
|
|
|
|
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.
|
|
|
|
### Verification
|
|
|
|
```bash
|
|
cd src
|
|
./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`,
|
|
`docs/web/patch-contract.md`, `docs/web/virtual-thread-profile.md`,
|
|
`docs/web/openapi-32-compatibility.md`, and `docs/adr/ADR-WEB-ADV-00{1,2,3}-*.md`.
|