Files
clean-architecture-backend-…/docs/web/repository-adaptation.md
T
DongHyeonka 7fdbbcaa87 docs: leaf 안내와 web 한도 표의 틀린 위치·주체를 코드에 맞춘다
문제(새 눈 리뷰):
- web-notification 안내가 callback 서명 검증을 유스케이스가 한다고 적었다.
  실제로는 composition의 ProviderCallbackIngressBridge가 outbound provider
  adapter(SES는 SnsSignatureVerifier)로 검증하고 검증된 event만 넘긴다.
- application-notification 안내가 없는 패키지 platform.port.out을 나가는 포트
  위치로 적었고, testFixtures를 「포트마다 fake 하나」라고 실제보다 크게 적었다.
- web-fileserver 책임 목록에 lifecycle(삭제·복사·이동)과 http(Range·조건부
  다운로드 계획) 패키지가 없었다.
- redis-runtime README가 app.redis.* 기본값 위치를 잘못 적었다. objectstorage
  README가 포트 개수를 복사했다.
- web 한도 표가 multipart 한도를 「전역 한도 없음」이라 했고, 아무도 막지 않는
  칸을 「늘 애플리케이션」이라 했다.
- TESTING_STRATEGY가 묶음 태스크를 셋이라 세며 performanceCheck를 빠뜨렸다.
- roadmap messaging-r2 이력 블록의 날짜·이유가 틀렸다(6d27356e, 2026-09-25).
- 지운 ComposeMergeCharacterizationTest 행의 커밋이 지운 쪽 기준이 아니었다.

고친 것: 위 문장을 지금 코드대로 고쳤다. 공개 경로 스냅숏 문장과 fileserver
「오류 코드」 절 안내는 공개 표면 PR·계약 PR이 만드는 것이라 병합 순서로 맞춘다.

검증: check-docs.py·check-work-docs.py rc=0.

Refs: RR9-04-09, RR9-04-21, RR9-04-35, RR9-04-42, RR9-03-30
2026-11-13 05:20:40 +09:00

20 KiB

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는 연결 끊김 증거로 기록한다.

확인

./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를 본다.