문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
284 lines
18 KiB
Markdown
284 lines
18 KiB
Markdown
# Web platform — repository adaptation
|
|
|
|
The inbound HTTP API execution platform design
|
|
(`docs/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
|
|
|
|
The design's `examples/web-platform-sample` is the existing `sample-portfolio` leaf, which already
|
|
carries the OpenAPI drift gate and the contract lanes the design's sample is specified to provide.
|
|
|
|
## 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`.
|