문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
257 lines
20 KiB
Markdown
257 lines
20 KiB
Markdown
# 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세대 플랫폼과 함께 지웠다.
|
|
> 내보내는 애플리케이션은 더는 아래 애플리케이션 칸을 강제하지 않는다. `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) | `maxBodyBytes`(플랫폼 상한 8 MiB) | 더 작은 쪽. nginx는 HTML로 413 |
|
|
| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 |
|
|
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 |
|
|
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 |
|
|
| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 늘 애플리케이션 |
|
|
|
|
둘 다 직관과 반대라서 적어 둘 만한 결과가 둘 있다.
|
|
|
|
**edge 한도가 애플리케이션 한도보다 낮으면 client는 애플리케이션의 오류 본문을 절대 보지 못한다.** nginx가 자기
|
|
HTML 오류 쪽을 답하므로, `error.code`로 분기하는 client는 파싱할 수 없는 본문을 받는다. client에게 중요한 차원이면
|
|
edge 한도를 애플리케이션보다 *높게* 두어 애플리케이션이 거부하게 한다.
|
|
|
|
**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션의 meter가 세기 전에 문제가 될 만큼 큰 본문과
|
|
프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다.
|
|
|
|
## 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`를
|
|
본다.
|