Files
clean-architecture-backend-…/docs/web/repository-adaptation.md
T
DongHyeonka 268bfdd1d8 Merge remote-tracking branch 'origin/claude/d1-docs-system-fd4a0f' into claude/i1-layout-docs-merge-217f1e
# Conflicts:
#	docs/ci-cd/template-vs-consumer.md
#	src/platforms/grpc/CLAUDE.md
2026-11-07 14:59:56 +09:00

18 KiB

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

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.