# Web 플랫폼 — 저장소 적응 inbound HTTP API 실행 플랫폼 설계서 (`docs/history/packages/web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md`)는 따로 선 저장소를 전제로 썼다. 그 가정 중 넷이 여기서는 맞지 않는다. 이 문서는 각각이 무엇이 됐고 왜 그런지 적는다. 설계와 트리를 비교하는 사람이 차이가 결정인지 실수인지 짐작하지 않게 하려는 것이다. > **2026-09-25 (D4, Wave 2 W2-3).** 템플릿은 virtual thread 위의 servlet(Spring MVC)이다. WebFlux 쌍, 2세대 > problem-document/budget/throttle/admission 플랫폼, 지속 작업 HTTP 투영, leaf 안의 모듈 경계 검사를 지웠다. HTTP > 오류는 `GlobalExceptionHandler`가 쓰는 `Envelope`다. 무엇을 지웠고 마지막으로 있던 commit이 무엇인지는 > `docs/capability-status.md`(「제거된 코드」)에 있다. ## 1. Gradle 모듈 스물셋이 leaf의 하위 package가 됐다 설계는 플랫폼을 `modules/web/web-core-api`, `web-contract`, `web-mvc` 같은 식으로 배치한다. 이 저장소의 `gradle/modules.json`은 leaf 목록을 가진, 닫힌 쪽으로 실패하는 registry다. leaf 스물셋을 더하는 것은 설계가 저장소 대신 내릴 수 없는 아키텍처 결정이다. JPA와 GraphQL 플랫폼도 같은 갈림길에서 같은 답을 냈다. 그래서 이것은 새 답이 아니라 이미 정한 답이다. 설계 모듈은 지금 web leaf(`adapter:inbound:web`)와 Advanced leaf(`adapter:inbound:web-advanced`)의 package로 나뉘어 있다. Gradle 의존성 게이트는 leaf 안을 보지 못한다. package edge를 검사하던 leaf 안의 모듈 지도 (`WebStableModule`)는 2세대 플랫폼과 함께 지웠다. 남은 것은 web leaf testFixtures의 `testkit/arch`에 있는 ArchUnit 규칙(`WebArchitectureRules`)이다. | 설계 모듈 | 지금 있는 곳(package는 `dev.caskeleton.adapter.inbound.web` 아래) | 상태 | | --- | --- | --- | | `web-core-api` | web leaf `core` | 있음 | | `web-contract` | web-advanced leaf `advanced.contract` | 있음(라이브러리) | | `web-error` | web leaf `error` | 있음 | | `web-pagination` | web leaf `pagination` | 있음 | | `web-idempotency` | web-advanced leaf `advanced.idempotency`. 저장소 SPI는 `application-core`(6절) | 있음 | | `web-idempotency-jpa` | web 쪽에는 없다. `persistence-jpa`의 `PostgreSqlIdempotencyStore`(6절) | 다른 곳에 있음 | | `web-idempotency-redis` | web 쪽에는 없다. `cache-redis`의 `RedisIdempotencyStoreAdapter`(6절) | 다른 곳에 있음 | | `web-versioning` | web-advanced leaf `advanced.versioning` | 있음(라이브러리) | | `web-security-integration` | web leaf `auth`, `authz` | 있음 | | `web-observability` | web leaf `observability` | 있음 | | `web-openapi` | web leaf `config`의 `OpenApiContractConfig`(springdoc, 3.1), web-advanced leaf `advanced.openapi`(3.2 생성기) | 있음 | | `web-mvc` | web leaf `mvc` | 있음 | | `web-webflux` | — | 지움(D4: servlet만) | | `web-admin` | web-advanced leaf `advanced.admin` | 있음(라이브러리) | | `web-operation-jpa` | web 쪽에는 없다. `persistence-jpa`의 `operation`(7절) | 다른 곳에 있음 | | `web-operation-messaging` | — | 없음 | | `web-spring-boot-starter-mvc` | web leaf `mvc.autoconfigure`(`WebAdapterAutoConfiguration`) | 있음 | | `web-spring-boot-starter-webflux` | — | 지움(D4: servlet만) | | `web-testkit-*` | web leaf testFixtures의 `testkit`(`arch`, `fault`, `mvc`, `order`, `performance`) | 있음 | | — | web leaf `conditional`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | 있음, 설계보다 먼저 있었다 | | — | web leaf `operation`(지속 작업 HTTP 면, 7절) | 있음 | | — | 파일서버·알림 HTTP 면 | 따로 된 leaf `adapter:inbound:web-fileserver`, `adapter:inbound:web-notification` | ## 2. Root package 설계는 `io.backend.skeleton.web`을 쓴다. 이 저장소의 package root는 `dev.caskeleton.adapter.inbound.web`이고, registry, ArchUnit 규칙, 조립 루트의 component scan이 모두 그것을 기준으로 쓰였다. ## 3. Gradle DSL 설계의 조각은 Kotlin DSL이다. 이 저장소의 빌드 파일은 모두 Groovy DSL이고, `build-logic`이 leaf가 물려받는 공용 convention plugin을 가진다. 빌드 로직은 복사하지 않고 옮겨 썼다. ## 4. Spring Boot 기준 설계는 「Spring Boot 4.1 BOM」을 든다. 이 저장소의 기준은 Spring Boot 4.0 계열이다(정확한 버전은 `gradle/libs.versions.toml`의 `springBoot`). 설계가 4.1에만 있는 API에 기대는 곳은 그 차이를 조용히 흡수하지 않고 호출하는 자리에 적는다. ## 5. 샘플 애플리케이션 설계의 `examples/web-platform-sample`에 해당하는 모듈은 없다. 그 역할을 하던 샘플 leaf는 2026-11-07에 지웠고, 그 안의 OpenAPI 드리프트 검사와 실서버 계약 lane도 함께 사라졌다. 예시는 `docs/manual/`과 `scripts/new-feature.sh` 출력이 맡는다. ## 6. 멱등성: 설계의 저장소 SPI는 이미 `application-core`가 가진다 설계는 `web-idempotency`에 자기 `IdempotencyStore`, `IdempotencyRecord`, `IdempotencyState`, `IdempotencyScope`, `RequestFingerprint`를 준다. 이 저장소에는 이미 `application-core/idempotency`에 같은 것들이 있다: `IdempotencyStorePort`, `IdempotencyState`, `IdempotencyScopeDigest`, `RequestFingerprint`. port 뒤에는 provider 저장소가 둘 있다. PostgreSQL(`persistence-jpa`의 `PostgreSqlIdempotencyStore`)과 Redis(`cache-redis`의 `RedisIdempotencyStoreAdapter`)이고, `app.capabilities.idempotency.provider`로 고른다. 설계의 Task 39와 40이 요구하는 것이 이것이고, registry가 허락하는 방향으로 만들었다. 설계의 SPI를 글자 그대로 구현하려면 `adapter-outbound-persistence-jpa → adapter-inbound-web` edge가 필요했다. registry가 금하는 edge이고, 어쨌든 방향이 틀렸다. 저장소는 두 transport가 함께 쓸 수 있는 애플리케이션 관심사이지, HTTP 계층이 가질 것이 아니다. 그래서 web 쪽에는 정말 HTTP인 부분만 남는다: 다시 보내는 애플리케이션 결과의 JSON 인코딩이고, `adapter:inbound:web-advanced`에 있다. 잡기, 범위, fingerprint 만들기, 다시 보내기 정책은 애플리케이션 use case 경계에 남는다. | 설계 관심사 | 여기 | | --- | --- | | store / record / scope / claim / replay | `application-core/idempotency` | | 요청 fingerprint 정책 | 애플리케이션 use case. 어떤 필드가 같은 일을 정하는지는 use case만 안다 | | `Idempotency-Key` 꺼내기 | 멱등성을 골라 쓰는 구체 inbound endpoint | | 다시 보내기 JSON 인코딩 | `adapter-inbound-web-advanced/idempotency/JsonIdempotentResponseCodec` | 이렇게 하면 「같은 요청」을 정하는 권한이 둘이 되지 않는다. HTTP 어댑터는 자기 DB 다시 보내기 정책을 돌리지 않는다. transport 입력을 애플리케이션 멱등성 context로 옮기고, 중복 실행은 use case가 갖게 한다. ## 7. 지속 작업: 설계의 `web-operation-jpa`는 여기 있을 수 없다 설계는 web 플랫폼에 자기 persistence 모듈 `modules/web/web-operation-jpa`를 준다. 오래 도는 작업을 위한 JPA 저장소를 담고, port(`DurableOperationStore`)는 `web-core-api`에 `WebProblem` 옆에 둔다. `gradle/modules.json`은 그 두 절반을 모두 금한다. - `:adapter:inbound:web`은 registry가 허락한 leaf에만 의존할 수 있다(`domain-core`, `application-core`, `shared-contract`, `adapter-outbound-support`). 그래서 web leaf는 JPA 의존성을 가질 수 없다. - `:adapter:outbound:persistence-jpa`는 outbound 어댑터라 inbound 어댑터에 의존할 수 없다. 그래서 JPA 저장소는 web 타입을 볼 수 없다. 6절과 같은 모양이고 같은 해결을 쓴다. 저장소가 멱등성에 이미 쓴 해결이다. 거기서 `IdempotencyStorePort`는 `application-core`에, `PostgreSqlIdempotencyStore`는 `persistence-jpa`에 있다. | 설계 타입 | 여기 | | --- | --- | | `DurableOperationStore` | `application-core/operation/DurableOperationStorePort` | | `OperationSubmission` | `application-core/operation/DurableOperationSubmission` | | 저장한 작업 | `application-core/operation/DurableOperation` | | lease | `application-core/operation/OperationLease` | | 저장한 실패 | `application-core/operation/OperationFailure` — code와 이미 안전한 메시지. 예외가 아니다 | | `JpaDurableOperationStore`, `JpaOperationEntity`, `V002__web_operation.sql` | `persistence-jpa/operation/*`, `db/migration/postgresql/V11__durable_operation.sql` | | `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | 2026-09-25에 지움 — web `operationasync` 투영과 `/api/v1/operations` controller는 운영 연결이 없었고 실패를 `WebProblem`으로만 내보냈다 | 이 나눔은 registry 우회만이 아니다. 각 절반을 그 불변식이 속한 곳에 둔다. problem document는 HTTP 개념이고 저장될 이유가 없다. 그래서 저장한 실패는 code와 안전한 메시지다. HTTP 면은 2026-09-25에 애플리케이션 use case 위의 얇은 transport로 다시 더했다(소유자 결정 15). `adapter:inbound:web` `operation/DurableOperationController`다. - `POST /operations`(202 + `Location`), `GET /operations/{id}`, `DELETE /operations/{id}`(202). - `Envelope` 계약으로 답한다. - 호출자의 것이 아닌 작업은 없는 작업과 같은 404(`OPERATION_NOT_FOUND`)다. controller와 use case 셋은 `composition:durable-operation`(`DurableOperationAutoConfiguration`)이 조립한다. 작업 저장소와 outbox append port가 있을 때만 켜진다(JPA 모듈과 `app.outbox.enabled=true`). 제출과 취소에는 `operation:submit` / `operation:cancel`이 필요하다(그 모듈의 `config/module-defaults/durable-operation.yml`이 둘 다 `operation-submit` role에 준다). 상태 기계는 일부러 세 번 강제한다: `DurableOperation`의 생성자, `V11__durable_operation.sql`의 `CHECK` 제약, 행을 바꾸는 모든 문의 `WHERE` 절. 생성자는 애플리케이션 결함을 잡고, 제약은 다른 쓰는 쪽을 잡고, 조건은 전이마다 원자적으로 만든다. 일하는 동안 lease가 끝난 worker는 이어받은 worker 위에 결과를 기록할 수 없다. 그 `UPDATE`가 행에 맞지 않고, worker는 바뀐 행 수로 그것을 안다. ## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것 > **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다. > 내보내는 애플리케이션이 직접 강제하는 칸은 요청 본문 한도뿐이다. JSON 본문은 web 한도(`app.web.mvc.max-json-body-size`, > 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope), multipart는 Spring 기본 한도다. 나머지 칸의 이름(`maxUriBytes` 등)은 > `budget` 목록(`WebRequestBudget`, `WebBudgetCatalog`)의 값이고, 그 목록은 `adapter:inbound:web-advanced`에 라이브러리 > 코드로만 남았다. 쓰이지 않던 meter(`WebBudgetMeter`와 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다. 설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다. 같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다. | 차원 | Edge (nginx) | 애플리케이션 | 넘으면 누가 답하나 | | --- | --- | --- | --- | | 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 | | 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 | | 요청 본문 | `client_max_body_size`(기본 1m) | JSON 본문: `app.web.mvc.max-json-body-size`(기본 1 MiB, 강제함). multipart 본문: Spring 기본 한도(`spring.servlet.multipart.*`, 넘으면 Envelope 413). 그 밖의 raw 본문: 전역 한도 없음, endpoint가 둔다 | 더 작은 쪽. nginx는 HTML로 413, 애플리케이션은 Envelope로 413 | | query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) | | JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 깊이는 Jackson 기본 `StreamReadConstraints`만 걸린다. 배열 크기는 아무도 막지 않는다 | | 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | edge. 애플리케이션 칸은 목록 값뿐이다 | | 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) | 둘 다 직관과 반대라서 적어 둘 만한 결과가 둘 있다. **edge 한도가 애플리케이션 한도보다 낮으면 client는 애플리케이션의 오류 본문을 절대 보지 못한다.** nginx가 자기 HTML 오류 쪽을 답하므로, `error.code`로 분기하는 client는 파싱할 수 없는 본문을 받는다. client에게 중요한 차원이면 edge 한도를 애플리케이션보다 *높게* 두어 애플리케이션이 거부하게 한다. **edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션이 막지 않는 차원(위 표의 「아무도 막지 않는다」)에서 큰 요청과 프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다. ## 9. Nginx lane (2026-09-25에 지움) `webNginxProxyTest` lane은 forwarded header 라이브러리(`proxy`, `http.External*`)를 Testcontainers `nginx:1.27-alpine` 뒤에서 돌렸다. 그 라이브러리는 내보내는 경로가 `server.forward-headers-strategy`로 하는 일을 다른 방식으로 하는 것이었다. 그래서 라이브러리와 lane을 함께 지웠다(`docs/capability-status.md`, 「제거된 코드」). 그 lane에서 얻은 발견 하나는 이 서비스 앞의 어떤 Nginx에도 여전히 맞다. Nginx의 배열 지시어 상속 규칙은 *교체*다. `location` 안의 `proxy_set_header` 하나가 `server`에서 물려받은 `proxy_set_header`를 모두 버린다. 그래서 forwarded header를 `server` 수준에 한 번 두고 `location`마다 `X-Forwarded-Prefix`만 더하면 나머지는 하나도 보내지 않고, 애플리케이션은 upstream 자신의 `Host`로 물러선다. forwarded header는 include 파일 하나에 두고 모든 `location`에서 `include`한다. ## Advanced capability Advanced 확장 계획서는 `modules/web-advanced/` 아래에 Gradle 모듈 열하나를 요구한다. 여기서는 따로 된 leaf `adapter:inbound:web-advanced`의 `advanced.**` package다. Stable 플랫폼이 leaf 하나인 것과 같은 이유다. `gradle/modules.json`이 닫힌 쪽으로 실패하고 leaf 목록을 가진다. 폴더 배치를 맞추려고 항목 열하나를 더하는 것은 아키텍처 변경이 아니라 registry 변경이다. 설계가 나눔으로 얻으려던 것은 대신 registry가 강제한다. registry는 `adapter-inbound-web-advanced → adapter-inbound-web` 방향만 허락한다. 그래서 Stable 클래스가 Advanced 타입을 이름 대면 Gradle 의존성 게이트 (`verifyCleanArchitectureDependencies`)가 빌드를 실패시킨다. feature flag는 bean을 만들지 정할 뿐 컴파일 시점 edge에는 아무것도 하지 않는다. 그런 edge 하나면 Advanced 없이는 Stable을 빌드할 수 없다. `advanced.patch`와 `advanced.codec`은 framework에 묶이고, 묶일 수밖에 없었다. 앞의 것은 Jackson의 tree 모델 때문이다. merge patch의 「null은 지움」은 Java 객체로 표현할 수 없어서 applier가 node 위에서 일한다. 뒤의 것은 `XMLInputFactory` 때문이다. `advanced.stream.encoding`을 `advanced.stream`에서 떼어 낸 것도 같은 이유다. framing은 직렬화하고, 직렬화는 Jackson에 묶인다. ### 복사하지 않고 고친 것 **`WebStreamErrorPolicy`의 factory 메서드는 `startOver` / `resumeFromPosition` / `nothingToDo`다.** 설계의 이름은 record 자신의 accessor와 겹쳤고, Java가 그것을 거부한다. **codec backend는 compile 전용이고, 그 이유를 알아내는 데 조립 루트 하나가 깨졌다.** `WebCborMapperFactory`와 `WebXmlMapperFactory`를 구현했고, 실패 모드를 지닌 부분도 함께 구현했다. - `SecureXmlInputFactory`: DTD와 외부 entity 기본값. 둘 다 터져도 오류를 내지 않는다. - `CodecBudget`: 표현마다 둔다. CBOR 1메가바이트는 몇 바이트로 원소 10억 개짜리 배열을 선언할 수 있다. - `RepresentationNegotiationPolicy`: 관문 셋. `Accept` 헤더는 그 route가 그 codec으로 시험됐다는 증거가 아니다. 처음에는 `jackson-dataformat-cbor`와 `jackson-dataformat-xml`을 `implementation`으로 선언했다. backend가 없을 때 그것을 협상한 첫 요청에서 `NoClassDefFoundError`로 드러나지 않게 하려는 것이었다. jar가 하는 일에 대해 그 판단은 틀렸다. Spring Boot의 Jackson auto-configuration은 각 backend가 런타임 classpath에 올라오는 순간 `xmlMapper`와 `cborMapper` bean을 등록하고, Spring은 그것으로 XML 메시지 변환기를 등록한다. 두 가지가 뒤따랐고, 시끄러운 것은 첫째뿐이었다. - 조립 루트가 `ObjectMapper` bean 셋(`webStrictObjectMapper`, `xmlMapper`, `cborMapper`)을 가졌다. 그래서 모든 `@Autowired ObjectMapper`가 모호해지고 애플리케이션이 시작하지 않았다. `app-bootstrap` 테스트 여섯 개가 `UnsatisfiedDependencyException`으로 실패했다. - 모든 배포가 조용히 `application/xml` 요청 본문을 받기 시작했다. 배포가 이름을 대지 않으면 꺼져 있어야 하는 capability에서, 의존성 하나를 더해서 얻은 XXE 면이다. 그래서 둘 다 `compileOnly`와 `testImplementation`이다. factory는 컴파일되고, 그 테스트는 실제 backend로 돌고, 런타임 classpath는 capability를 켜는 배포의 몫이다. `WebRepresentation.available()`은 없는 backend를 빠진 좌표를 이름 댄 문장으로 바꾼다. `RepresentationBackendScopeTest`는 `build.gradle`을 읽고 둘 중 하나라도 `implementation`으로 돌아가면 실패한다. 다른 어떤 것도 그것을 잡지 못하기 때문이다. codec 자체 테스트는 어느 쪽이든 통과하고, 실패는 이 leaf를 조립하는 곳에서만 나타난다. **framing과 writer는 따로다.** `NdjsonFraming`과 `JsonSequenceFraming`이 계약을 가지고, `MvcStreamWriter`가 그것을 응답에 싣는다. MVC SSE writer는 없다. 이 저장소의 `NO_SSE_EMITTER` ArchUnit 규칙이 `SseEmitter`를 아예 금하고, 유일한 SSE writer는 2026-09-25에 지운 WebFlux 것이었다. 그래서 servlet stack은 NDJSON과 JSON-seq를 스트리밍하고, SSE는 framing만 있다. servlet writer가 생기기 전에는 아무것도 SSE를 내보내지 않는다. **`MessagingReplayBridge`는 이 모듈이 어디서도 구현하지 않는 interface인 `WebStreamReplaySource`다.** 설계의 요구는 web 모듈이 지속되는 이벤트 이력을 저장하지 않는 것이다. 여기서 구현하면 그것이 금하는 바로 그것이 된다. ### 실행 계층이 맞혀야 했던 것 servlet stack에는 연결 끊김 이벤트가 아예 없다. client가 사라졌다는 첫 신호는 예외를 던지는 쓰기다. 그래서 heartbeat는 예의가 아니라 탐침이고, 실패한 heartbeat는 연결 끊김 증거로 기록한다. ### 확인 ```bash ./gradlew :adapter:inbound:web:test # 내보내는 web leaf ./gradlew :adapter:inbound:web:systemTest # Tomcat, 실제 socket ./gradlew :adapter:inbound:web:webJettyCompatTest # Jetty, 실제 socket ./gradlew :adapter:inbound:web-advanced:test # 골라 쓰는 Advanced leaf ./gradlew :adapter:inbound:web-advanced:webAdvancedTest # tag를 단 Advanced lane ``` `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`, `docs/adr/ADR-WEB-ADV-00{1,2,3}-*.md`를 본다.