From 5a3784be58590d78d43a3d8bc206adc6f19870e3 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:12:03 +0900 Subject: [PATCH] =?UTF-8?q?docs(adapter-inbound):=20inbound=20=EC=96=B4?= =?UTF-8?q?=EB=8C=91=ED=84=B0=20=EB=AA=A8=EB=93=88=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=EB=A5=BC=20=ED=95=9C=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=98=AE?= =?UTF-8?q?=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: inbound 어댑터 leaf(messaging, web, web-advanced, websocket, graphql, grpc)의 CLAUDE.md가 영어이거나 영어 절이 섞여 있다. 다섯 CLAUDE.md는 Spring Boot 버전(4.0.0, 4.0.8)을, graphql README는 leaf 개수(19·24·43)를 복사해 두었고 그 수는 registry가 바뀌면 틀린다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을, leaf 수는 registry를 가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다: web CLAUDE.md의 `adapter-persistence`(없는 이름)를 `adapter:outbound:persistence-jpa`로, Jackson 속성 위치를 `spring.jackson.serialization.*`·`generator.*`에서 실제 키 `spring.jackson.deserialization.*`·`spring.jackson.datatype.*`로, 「`WRITE_BIGDECIMAL_AS_PLAIN=true`로 고정」을 「설정 키가 아니라 `JacksonSerializationPolicyTest`가 지수 표기 없음을 단언」으로 고친다. 매뉴얼 장 번호만 쓴 참조는 경로와 절 제목으로 바꾼다. 위험: ArchUnit 규칙 이름의 대소문자(문서는 소문자, 코드는 대문자 상수)는 이 커밋에서 그대로 두고 다음 커밋에서 한꺼번에 맞춘다. 검증: python3 scripts/check-docs.py rc=0(language 줄 4개, number 줄 7개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0. --- scripts/check-docs-exceptions.txt | 11 - src/adapter/inbound/graphql/CLAUDE.md | 56 ++-- src/adapter/inbound/graphql/README.md | 6 +- src/adapter/inbound/grpc/CLAUDE.md | 52 ++-- src/adapter/inbound/messaging/CLAUDE.md | 40 ++- src/adapter/inbound/web-advanced/CLAUDE.md | 66 ++--- src/adapter/inbound/web/CLAUDE.md | 315 +++++++++------------ src/adapter/inbound/web/README.md | 15 +- src/adapter/inbound/websocket/CLAUDE.md | 181 ++++++------ 9 files changed, 335 insertions(+), 407 deletions(-) diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 08f57e77..2b41d107 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -146,10 +146,6 @@ language docs/web/runbook.md language docs/web/streaming-contract.md language docs/web/virtual-thread-profile.md language docs/websocket/runbook.md -language src/adapter/inbound/messaging/CLAUDE.md -language src/adapter/inbound/web-advanced/CLAUDE.md -language src/adapter/inbound/web/CLAUDE.md -language src/adapter/inbound/websocket/CLAUDE.md language src/adapter/outbound/cache-redis/CLAUDE.md language src/adapter/outbound/cache-redis/README.md language src/adapter/outbound/fileserver/CLAUDE.md @@ -189,13 +185,6 @@ number docs/jpa/repository-adaptation.md Spring Boot 4.0.8 number docs/manual/01-generator.md 5 leaf number docs/mongodb/repository-adaptation.md 19 leaf number docs/mongodb/repository-adaptation.md Spring Boot 4.0.8 -number src/adapter/inbound/graphql/CLAUDE.md Spring Boot 4.0.0 -number src/adapter/inbound/graphql/README.md 19개 leaf -number src/adapter/inbound/graphql/README.md 24개 leaf -number src/adapter/inbound/graphql/README.md 43개 leaf -number src/adapter/inbound/grpc/CLAUDE.md Spring Boot 4.0.0 -number src/adapter/inbound/web/CLAUDE.md Spring Boot 4.0.0 -number src/adapter/inbound/websocket/CLAUDE.md Spring Boot 4.0.8 number src/adapter/outbound/cache-redis/CLAUDE.md Spring Boot 4.0.0 number src/adapter/outbound/fileserver/CLAUDE.md Spring Boot 4.0.0 number src/adapter/outbound/httpclient/CLAUDE.md Spring Boot 4.0.0 diff --git a/src/adapter/inbound/graphql/CLAUDE.md b/src/adapter/inbound/graphql/CLAUDE.md index 89dd89bf..bec9db91 100644 --- a/src/adapter/inbound/graphql/CLAUDE.md +++ b/src/adapter/inbound/graphql/CLAUDE.md @@ -1,12 +1,12 @@ -# adapter:inbound:graphql — inbound GraphQL adapter (skeleton machinery) +# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치) -## Registered identity +## 등록 정보 -- Module ID: `adapter-inbound-graphql` -- Gradle path: `:adapter:inbound:graphql` -- Focused test (derived from Gradle path): `./gradlew :adapter:inbound:graphql:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `adapter-inbound-graphql` +- Gradle 경로: `:adapter:inbound:graphql` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. Package root: `dev.caskeleton.adapter.inbound.graphql`. @@ -46,7 +46,7 @@ sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값 두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의 required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다. -## Responsibility +## 책임 - GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`, 프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를 @@ -62,28 +62,26 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 명시해야 한다. -## Error-code ownership +## 오류 코드 소유 -`docs/registries/error-codes.yaml` is the skeleton-wide `OperationalError` SSOT; it is not a -catch-all registry for transport-specific presentation codes. GraphQL therefore keeps its own finite -platform wire-code catalogue in `GraphQlErrorCode`. +`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현 +코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를 +`GraphQlErrorCode`에 둔다. -- GraphQL platform mappers must use `GraphQlErrorCode.platform(...)`. An unregistered platform code - fails immediately. -- application/domain `ApiErrorCode` values remain a separate namespace and pass through with - `GraphQlErrorCode.of(...)`; GraphQL must not rename product errors. Only a registered - `ApiErrorCode` reaches the wire this way — a DataLoader per-key failure carries one, never a free - string (owner decision 2026-09-25). -- new GraphQL-owned platform codes use the `GRAPHQL_` prefix. The existing unprefixed platform - values are frozen legacy wire contracts and are listed explicitly by - `legacyUnprefixedPlatformCodes()`. -- modelled-only capability codes are not added to `platformCodes()` until that capability reaches - the shipped request path. +- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 + 실패한다. +- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다. + GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 — + DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25). +- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire + 계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다. +- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에 + 더하지 않는다. -`GraphQlErrorCodeCatalogTest` pins the exact shipped catalogue, the prefix rule and the -application/platform namespace split. +`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를 +고정한다. -## Allowed +## 허용 - `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제 의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이 @@ -107,7 +105,7 @@ application/platform namespace split. `@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티 게이트가 이 선언을 요구한다. -## Forbidden +## 금지 - outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit @@ -117,7 +115,7 @@ application/platform namespace split. `HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. - 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다. -## Error mapping (`Category → ErrorType`) +## 오류 대응 (`Category → ErrorType`) 모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 @@ -181,7 +179,7 @@ health 스키마만 소유한다. (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 형태로 새로 만든다. -## Test +## 테스트 ```bash cd src diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index ff9c7c63..98e59e89 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -176,15 +176,15 @@ composition root 는 이 leaf 를 채택할 때 인증/인가 및 CORS 정책을 ## 설계서의 "모듈"을 Gradle 모듈로 만들지 않은 이유 -설계서는 Stable 16 + Advanced 12 = 28개 Gradle 모듈을 전제한다. 구현 시점의 레지스트리 -(`src/config/architecture/modules.json`)는 19개 leaf 였고, 28개를 추가하는 것은 레지스트리· +설계서는 Stable 16 + Advanced 12 = 28개 Gradle 모듈을 전제한다. 그 28개를 구현 시점의 레지스트리 +(`src/config/architecture/modules.json`)에 추가하는 것은 레지스트리· `settings.gradle` fail-closed 검증·의존 게이트를 동시에 건드리는 변경이다. GraphQL 표면은 하나의 인바운드 전송 경계이므로 그 **내부** 분할을 레포 전역 SSOT 까지 밀어올리지 않기로 하고, **모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 366개 java 파일을 같은 방식으로 담는다). **정직하게 기록해 둘 반례:** 이후 main 에 통합된 자매 플랫폼 messaging 은 정반대로 -**24개 leaf 를 레지스트리에 등록**했다(현재 총 43개 leaf). 즉 레지스트리는 닫혀 있지 않았고, +**자기 leaf 를 레지스트리에 하나씩 등록**했다(지금의 leaf 목록과 수는 레지스트리가 정한다). 즉 레지스트리는 닫혀 있지 않았고, "확장하면 게이트가 깨진다"는 전제는 과했다. 두 플랫폼이 서로 다른 패턴을 쓰고 있으므로 **어느 쪽으로 통일할지는 미결 아키텍처 결정**이다. diff --git a/src/adapter/inbound/grpc/CLAUDE.md b/src/adapter/inbound/grpc/CLAUDE.md index 5c4dff1a..9b4ef61f 100644 --- a/src/adapter/inbound/grpc/CLAUDE.md +++ b/src/adapter/inbound/grpc/CLAUDE.md @@ -1,19 +1,19 @@ -# adapter:inbound:grpc — inbound gRPC adapter (skeleton machinery) +# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치) -## Registered identity +## 등록 정보 -- Module ID: `adapter-inbound-grpc` -- Gradle path: `:adapter:inbound:grpc` -- Focused test (derived from Gradle path): `./gradlew :adapter:inbound:grpc:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `adapter-inbound-grpc` +- Gradle 경로: `:adapter:inbound:grpc` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. Package root: `dev.caskeleton.adapter.inbound.grpc`. 코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). -## Responsibility +## 책임 - gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`), feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` + @@ -22,13 +22,13 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`. - feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을 이름으로 알지 않는다. -## Allowed +## 허용 - `:application-core`, `:domain-core`, `:shared-contract`. - `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services), `spring-boot-starter`, `spring-boot-starter-validation`. -## Forbidden +## 금지 - outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit @@ -38,7 +38,7 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`. - 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의 `HealthcheckController` 와 동일 원칙). -## Config knobs (`app.grpc.server.*`) +## 설정 손잡이 (`app.grpc.server.*`) 타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 (모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이 @@ -69,24 +69,22 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`. `enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면 configuration binding/startup 단계에서 실패한다. -## Adopting this capability +## 이 capability 채택하기 -gRPC is also a **build-composition opt-in**. The default bootJar does not contain this leaf. +gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다. -1. Add `:adapter:inbound:grpc` to the consuming composition and add the corresponding allowed - dependency edge in `config/architecture/modules.json`. -2. Register settings through the capability root; do not add - `dev.caskeleton.adapter.inbound.grpc` to the shipped `@ConfigurationPropertiesScan`. -3. Provide any feature `BindableService` plus exactly one `GrpcAuthenticationPolicy`. -4. Run `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification` before promotion. -5. Production adoption is incomplete until composition-owned configuration/env registry entries - exist for the selected runtime contract. +1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존 + edge를 더한다. +2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에 + `dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다. +3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다. +4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다. +5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다. -**Current transport limit:** the P1 server is plaintext and deliberately permits only loopback -binding. It is therefore suitable for local-process or same-Pod sidecar communication only. It -cannot bind `0.0.0.0` for a normal Kubernetes Service, cannot accept cross-Pod traffic, and must -not be presented as a cluster-facing gRPC endpoint. Cluster exposure requires the deferred TLS/mTLS -credential path and a separately qualified non-loopback bind. +**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은 +Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을 +받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS +credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다. ## Feature 기여 방법 @@ -109,7 +107,7 @@ listener 시작이 실패한다. 정책은 `Optional authenticate(Met 이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS, external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다. -## Test +## 테스트 ```bash cd src diff --git a/src/adapter/inbound/messaging/CLAUDE.md b/src/adapter/inbound/messaging/CLAUDE.md index 11d9c1a2..e1637a6e 100644 --- a/src/adapter/inbound/messaging/CLAUDE.md +++ b/src/adapter/inbound/messaging/CLAUDE.md @@ -1,25 +1,23 @@ # adapter:inbound:messaging -- Module ID `adapter-inbound-messaging`, Gradle path `:adapter:inbound:messaging`. Registry SSOT: +- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본: `src/config/architecture/modules.json`. -- Responsibility: the application's consume side of the vendored messaging platform — the inbox - parts the platform needs from the application (`JdbcInboxRepository` over the application - DataSource, a `TransactionRunner` over its `PlatformTransactionManager`, the inbox migration as - its own Flyway stream `MessagingInboxSchemaStream`) and the application's `MessageHandler` - implementations, each turning a delivery into one use case call. A handler registers nothing - else: the platform decodes what its `destination()` and `schemaVersions()` declare. -- Boundaries: no business rule in a handler (HARD-STOP 4); no persistence entity or repository; no - broker SDK type. Allowed edges come only from the registry entry. -- A handler that calls a write use case is `@SystemCaller(reason = ...)` and constructs the - `@SystemInvoked` use case itself; the use case is never a bean, and no user transport calls the - handler (manual 09 「소비」 step 4, manual 07 「시스템이 부르는 쓰기」, +- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는 + inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의 + `TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의 + `MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에 + 아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다. +- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이 + 없다. 허용 edge는 registry 항목에서만 온다. +- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접 + 만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다 + (`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계, + `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」, `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, - `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). The handler implements only project types - (`MessageHandler`), never `Runnable` or another type outside the project - (`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). -- Tests: focused auto-configuration and inbox behavior tests; `./gradlew :adapter:inbound:messaging:check`. - The real Kafka + PostgreSQL redelivery lane is `messagingInboxRedeliveryIntegrationTest` - (`:integrationCheck`). -- Coordinates: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. Do not drop them — - with the default group this project and `:adapter:outbound:messaging` are one module to Gradle. -- Design and rejected alternatives: `README.md`. + `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler`)만 구현하고, + `Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). +- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`. + 실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`). +- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본 + group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다. +- 설계와 버린 대안: `README.md`. diff --git a/src/adapter/inbound/web-advanced/CLAUDE.md b/src/adapter/inbound/web-advanced/CLAUDE.md index 18d3212d..1f11e209 100644 --- a/src/adapter/inbound/web-advanced/CLAUDE.md +++ b/src/adapter/inbound/web-advanced/CLAUDE.md @@ -1,46 +1,42 @@ -# adapter:inbound:web-advanced — opt-in web library +# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리 -## Registered identity +## 등록 정보 -- Module ID: `adapter-inbound-web-advanced` -- Gradle path: `:adapter:inbound:web-advanced` -- Focused test (derived from Gradle path): `./gradlew :adapter:inbound:web-advanced:test --console=plain` -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `adapter-inbound-web-advanced` +- Gradle 경로: `:adapter:inbound:web-advanced` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain` +- registry 정본: `src/config/architecture/modules.json`. -Package root: `dev.caskeleton.adapter.inbound.web.advanced`. What it provides, the one line a -service adds and the settings are in [README.md](README.md). +패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄, +설정은 [README.md](README.md)에 있다. -## Responsibility +## 책임 -- Web library code that the servlet production path does not reach: streaming, virtual-thread - admission, JSON Patch / Merge Patch, CBOR/XML codecs, OpenAPI 3.2 generator and breaking-change - policy, URI/method policy, versioning, operation/budget/contract catalogs, security-context - bridge, idempotent response codec, route inventory. -- The three switched MVC capabilities (virtual threads, NDJSON, JSON sequence), each an - `@AutoConfiguration` listed in this leaf's `AutoConfiguration.imports` and off by default. +- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch / + Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning, + operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록. +- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의 + `AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다. -## Rules +## 규칙 -- Not in any default composition. `app-bootstrap` main은 이 leaf에 의존하지 않는다; - `app-bootstrap` takes it `testRuntimeOnly` so the whole-repository ArchUnit import reads it. -- It depends on `adapter:inbound:web` (the `core` vocabulary), never the reverse. -- No component-scannable stereotype. A consuming application may scan the adapter packages - (서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다), so a - `@Configuration`/`@Component` here would be created whatever its switch says. Switched wiring is - `@AutoConfiguration` + an imports line; imported helpers carry no stereotype - (`MvcStreamingSupportConfiguration`). -- No setting that no code reads, no gate or evidence type in `main` that only tests call — the - release gate and OpenAPI promotion report were removed for exactly that - (`docs/capability-status.md`). -- One generation per feature. Nothing here may re-implement what the production web path already - does another way: forwarded headers (`server.forward-headers-strategy`), CORS/CSRF - (`CorsSettings`/`SecurityConfig`), cache headers (`CacheControlFilter`), the JSON mapper (Boot's - `JsonMapper`), OpenAPI customization (`OpenApiContractConfig`). Those duplicates and the WebFlux - `functional` package were removed on 2026-09-25 (`docs/capability-status.md`). -- Inbound adapter rules from `adapter:inbound:web` apply: no repository access, no business rules, - no DTO leaking into `application-core`/`domain-core`. +- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다. + `app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다. +- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다. +- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다 + (서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나 + `@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports + 한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`). +- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와 + OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`). +- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다: + forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache + header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`). + 그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`). +- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음, + `application-core`·`domain-core`로 새는 DTO 없음. -## Test +## 테스트 ```bash cd src diff --git a/src/adapter/inbound/web/CLAUDE.md b/src/adapter/inbound/web/CLAUDE.md index 35c66ca8..f4903614 100644 --- a/src/adapter/inbound/web/CLAUDE.md +++ b/src/adapter/inbound/web/CLAUDE.md @@ -1,213 +1,170 @@ -# adapter:inbound:web — inbound HTTP adapter +# adapter:inbound:web — inbound HTTP 어댑터 -## Registered identity +## 등록 정보 -- Module ID: `adapter-inbound-web` -- Gradle path: `:adapter:inbound:web` -- Focused test (derived from Gradle path): `./gradlew :adapter:inbound:web:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `adapter-inbound-web` +- Gradle 경로: `:adapter:inbound:web` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. -Package root: `dev.caskeleton.adapter.inbound.web`. +패키지 루트: `dev.caskeleton.adapter.inbound.web`. 코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). -## Responsibility +## 책임 -- HTTP controllers. -- Request/response DTOs. -- Request DTO to application command mapping. -- Authentication, validation, error mapping, filters, and web/security settings. -- Sanitized request correlation context exposed through application-owned `CorrelationIdPort`. -- Transport-owned OpenAPI customization that keeps `ApiError.details` as `type: object` without - leaking Swagger dependencies into `shared-contract`. +- HTTP controller. +- 요청·응답 DTO. +- 요청 DTO를 application command로 바꾸기. +- 인증, 검증, 오류 대응, filter, web·보안 설정. +- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥. +- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는, + 전송 계층이 가진 OpenAPI 손질. -Every service ships this leaf, so it holds only what the servlet production path reaches: its -`AutoConfiguration.imports` roots (`WebAdapterAutoConfiguration` imports the envelope, filters, -health and rate-limit beans; `WebSecurityAutoConfiguration` imports the JWT chain, so an application -with its own posture excludes only that root; `WebMethodSecurityAutoConfiguration` imports method -security and the permission port and stays when the chain is replaced; nobody scans -this leaf), and the types -`app-bootstrap`, `web-fileserver` and `composition:fileserver-platform` name — -plus their transitive references. Library code that no production path reaches (streaming, virtual -threads, patch, codecs, OpenAPI 3.2, URI/method policy, versioning, operation, budget, contract, -security-context bridge, `JsonIdempotentResponseCodec`, route inventory) lives in the opt-in leaf -`adapter:inbound:web-advanced`. A new type that nothing on the -production path uses belongs there, not here. This leaf never depends on it (Gradle registry + -ArchUnit `WEB-ARCH-ADV`). +모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports` +루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다. +`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만 +뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다. +이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이 +이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual +thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context +bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다. +운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다 +(Gradle registry + ArchUnit `WEB-ARCH-ADV`). -## Allowed +## 허용 - `:application-core` - `:domain-core` - `:shared-contract` -- `:adapter:outbound:support` — `StrictSettingsBinder` only. `app.security` (`SecuritySettings`, the - authentication mode included) is bound by the one strict binder every module uses (since - 2026-11-01); the ArchUnit inbound/outbound rules allow that class and nothing else from the - leaf. -- Spring Web/Security/Validation dependencies. +- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는 + 모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그 + leaf에서 이 클래스만 허용한다. +- Spring Web·Security·Validation 의존성. -## Forbidden +## 금지 -- Direct dependency on `adapter-persistence` or any other `adapter-outbound` type. -- Direct repository or JPA entity access from controllers. -- Core business rules in controller, filter, config, mapper, or settings code. -- DTO leakage into application or domain. +- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기. +- controller에서 repository나 JPA 엔티티에 직접 접근하기. +- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙. +- DTO가 application이나 domain으로 새는 것. -## Boundary validation & mapper contract +## 경계 검증과 mapper 계약 -`feature-boundary-validation-mapping-contract` (design record) fixes the -behaviour at this layer's boundaries. The repo-level guardrails (ArchUnit + -Jackson config + handler) only catch the static violations — the contract below -also drives the runtime patterns reference implementations must follow. +`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위 +가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임 +패턴도 정한다. -- **B1 — Jackson policy at the request boundary.** `spring.jackson.deserialization` - pins `fail-on-unknown-properties`, `fail-on-null-for-primitives`, - `fail-on-ignored-properties` to `true` and `read-unknown-enum-values-as-null` - to `false`. Do NOT undo this per-DTO with class-level - `@JsonIgnoreProperties(ignoreUnknown = true)` — ArchUnit rule - `request_dtos_do_not_silence_unknown_fields` blocks it. Use wrapper types - (`Integer`, `Long`, `Boolean`, `Optional`) in request records so JSON - `null` cannot become primitive `0`. -- **B2 — PATCH semantics.** Do not adopt RFC 7396 `application/merge-patch+json` - (`null = deletion`). PATCH endpoints must distinguish *absent* (no change), - *explicit null* (clear field), and *value* (replace). Use - `org.openapitools:jackson-databind-nullable` (`JsonNullable`) or - `Optional` wrappers on request records. -- **B3 — Mapper-internal failures.** Map record canonical-constructor - `IllegalArgumentException`, MapStruct generated NPE, ACL normalization - failures, etc. by throwing `MappingException`; the global handler routes it to `MAPPING_FAILED` (HTTP 400), - never to `BAD_PARAMETER` or `INTERNAL_ERROR`. Plain `IllegalArgumentException` - remains `BAD_PARAMETER` for non-mapper callers. -- **B4 — Validation layering.** Class-level Bean Validation constraints belong - to the *syntax* layer (request DTO). Domain invariants belong to - `application-core` / `domain-core`. Use `@GroupSequence(...)` to short-circuit - invariant evaluation when syntax fails. Keep `@Valid` cascade depth ≤ 3. -- **B5 — Polymorphic deserialization.** Calling - `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()` or - referencing `LaissezFaireSubTypeValidator` is the CVE-2019-14379 RCE entry - point and is blocked by ArchUnit (`no_jackson_laissez_faire_subtype_validator`, - `no_jackson_enable_default_typing_call`). Sealed `Command` types must use - `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`, or a - `BasicPolymorphicTypeValidator` allowlist. -- **B6 — Virtual thread context propagation.** With - `spring.threads.virtual.enabled=true`, do not use `InheritableThreadLocal` - (ArchUnit rule `no_inheritable_thread_local`). Filters and interceptors must - propagate `requestId` / `traceId` via SLF4J 2.0+ MDC or - `RequestContextHolder`. -- **B7 — Outbound ACL mapper scope.** Outbound HTTP / messaging adapter - responses must pass through an ACL mapper (normalization, masking, public - field selection) before reaching `application-core` or `domain-core` — the - same boundary contract as inbound. Raw external response types must not leak - into `domain-core`. -- **B8 — Bulk endpoint partial success.** Envelope `success = true` only when - every item succeeded. Partial failure responds with `success = false` + - `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]` (per-item array) — - a different shape from the single-item endpoint. Document the shape divergence - in the OpenAPI spec. +- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`, + `fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을 + `false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지 + **않는다** — ArchUnit 규칙 `request_dtos_do_not_silence_unknown_fields`가 막는다. 요청 record에는 + wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 + 한다. +- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 + *없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에 + `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 `Optional` wrapper를 쓴다. +- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL + 정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로 + 보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한 + `IllegalArgumentException`은 계속 `BAD_PARAMETER`다. +- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은 + `application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다. + `@Valid` cascade 깊이는 3 이하로 둔다. +- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나 + `LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다 + (`no_jackson_laissez_faire_subtype_validator`, `no_jackson_enable_default_typing_call`). sealed `Command` + 타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다. +- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지 + 않는다(ArchUnit 규칙 `no_inheritable_thread_local`). filter와 interceptor는 SLF4J 2.0+ MDC나 + `RequestContextHolder`로 `requestId` / `traceId`를 전파한다. +- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에 + 닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답 + 원본 타입은 `domain-core`로 새면 안 된다. +- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가 + 실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로 + 답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다. -Domain `@RestControllerAdvice` in a consuming module must be annotated -`@Order(Ordered.HIGHEST_PRECEDENCE)` (or otherwise ordered ahead of this -module's base `GlobalExceptionHandler`), because the base handler's catch-all -`@ExceptionHandler(Exception.class)` would otherwise resolve domain exceptions -to `INTERNAL_ERROR`. +이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는 +다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의 +catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다. -The base operational handler (`error/GlobalExceptionHandler`), the error-code -contract (`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), the -`error/ErrorResponseFactory`, and the `envelope/EnvelopeBodyAdvice` now live in -production modules (`adapter:inbound:web` / `shared-contract`), so the running application -provides them. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`). +기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약 +(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`, +`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는 +애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`). -## Schema / serialization contract +## schema·직렬화 계약 -`feature-schema-serialization-contract` (design record) fixes the -*response producer* side of the wire contract — the sibling of the B1 *request -consumer* policy above. The deserialization switches (B1) and the -null/empty/missing 3-state (`Patch` + `JsonNullable`, B2) already cover the -inbound side; the rules below cover the outbound side. The Jackson properties -live in `app-bootstrap` (`application.yml` `spring.jackson.serialization.*` / -`spring.jackson.generator.*`); ArchUnit + effective-config tests live in -`app-bootstrap` (`JacksonSerializationPolicyTest`, `no_bigdecimal_double_constructor`). +`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1 +*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch` + `JsonNullable`, +B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의 +`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제 +설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `no_bigdecimal_double_constructor`). -- **S1 — Date / time / timezone.** `WRITE_DATES_AS_TIMESTAMPS=false` is - pinned, so `java.time` values serialize as ISO-8601 strings via `JavaTimeModule` - (`OffsetDateTime` → `"...Z"`, `LocalDate` → `"YYYY-MM-DD"`), never a numeric - epoch or `[y,m,d,...]` array. Server timezone is **UTC**: emit instants as - `OffsetDateTime`/`Instant` with a `Z` offset. Use `LocalDate` only for - date-only calendar fields. Do **not** put timezone-less `LocalDateTime` on a - response DTO — it serializes without an offset and breaks the contract. -- **S2 — Money / BigDecimal.** Default scale 2, rounding `HALF_UP` unless - the domain documents otherwise (KRW/JPY = scale 0 with a schema note). - `WRITE_BIGDECIMAL_AS_PLAIN=true` is pinned so values never serialize in - scientific notation. Pick **one** JSON representation per API and state it in - the OpenAPI schema: **string** (`@JsonSerialize(using = ToStringSerializer.class)`) - for public / financial endpoints (client parses, no precision loss), or - **number + plain** for internal service-to-service endpoints. Never rely on - the default — decide at endpoint design time. -- **S3 — `new BigDecimal(double)` is banned.** The `double`/`float` constructors - capture binary floating-point error (`new BigDecimal(0.1)` ≠ `0.1`). Build from - a `String` (`new BigDecimal("0.1")`) or `BigDecimal.valueOf(double)`. Enforced - by the `no_bigdecimal_double_constructor` ArchUnit rule. -- **S4 — Enum / null·empty·missing.** Request-side unknown enum → - `VALIDATION_FAILED` (B1 `read-unknown-enum-values-as-null=false`); legacy values - map through an explicit adapter, never a silent fallback. The - absent / explicit-null / value distinction is owned by the inbound web mapper - (Controller DTO → Command), expressed with `Patch` (B2); `domain-core` and - `application-core` receive the already-resolved 3-state, never a wire type. -- **S5 — Out of this branch's scope.** OpenAPI drift enforcement is owned by - the verification suite / api-contract-baseline; removed-field-reuse ban tooling - (`x-removed-fields` vs markdown catalog) is `needs-confirmation`; Avro - Schema Registry for outbox/event and response field rename/versioning - (`feature-api-compatibility-deprecation-contract`) are separate branches. +- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은 + `JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` → + `"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z` + offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대 + 없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다. +- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과 + schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가 + 큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융 + endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를 + 잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할 + 때 정한다. +- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다 + (`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로 + 만든다. ArchUnit 규칙 `no_bigdecimal_double_constructor`가 강제한다. +- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1 + `read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지 + 않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch`(B2)로 + 나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다. +- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운 + 필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용 + Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은 + 다른 브랜치다. -## Business rule validation contract +## 업무 규칙 검증 계약 -`feature-business-rule-validation-contract` (design record) fixes **which -rule is validated at which boundary**, so "validation" does not collapse into the -controller DTO or a DB constraint. It sits on top of the boundary/mapping contract -above and is enforced by ArchUnit + contract tests (not new runtime mechanism). +`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서, +「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과 +계약 시험이 강제한다(새 런타임 장치가 아니다). -| Layer | Owner | Validates | `error.category` | Enforced by | +| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 | |---|---|---|---|---| -| syntax / shape | `adapter:inbound:web` request DTO (`@Valid` / `jakarta.validation`) | request shape, types, required fields | `VALIDATION` | `validation_constraints_stay_at_web_boundary` ArchUnit rule | -| use case policy | `application-core` | authorization, cross-aggregate policy, state preconditions | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | -| domain invariant | `domain-core` model / value object **constructor** | business invariants (e.g. end ≥ start) | `CONFLICT` / `VALIDATION` | domain unit tests (e.g. `PeriodTest`) — constructor is the sole, immutable construction path | -| persistence integrity | `adapter-persistence` (translator owned by `feature-persistence-failure-baseline`) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + leak test | +| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `validation_constraints_stay_at_web_boundary` | +| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | +| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | +| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | -- **C1 — Validation annotations stay at the web boundary.** `jakarta.validation` - (`@NotNull`, `@Valid`, …) must appear only in `adapter:inbound:web`. `domain-core` and - `application-core` express invariants and policy as plain Java. The - `validation_constraints_stay_at_web_boundary` ArchUnit rule fails the build if a - Bean Validation annotation leaks into `..domain..` or `..application..`. -- **C2 — Business invariants live in the domain, un-bypassable.** Enforce invariants - in the value-object / entity **constructor** (the sole construction path) and keep - the type immutable, so no application-service or persistence path can hand out an - invariant-violating instance. A DB constraint is a backstop, never the only check - (Forbidden: "DB constraint as only invariant"). -- **C3 / C7 — Persistence integrity maps to an operational error, leak-free.** A - unique/FK/check/serialization failure maps to `DATA_INTEGRITY` / `CONFLICT` with a - **client-safe message only**. The raw SQL, constraint/index name, SQLState code, - exception class, and stack frame must never reach `error.message` or - `error.details`. The base `GlobalExceptionHandler` catch-all already replaces the - message with the opaque shared message (`ClientErrorMessages.OPAQUE`) and emits `null` details; the - category-correct mapping (23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …) is owned by - `feature-persistence-failure-baseline`'s persistence-adapter translator. -- **C8 — Duplicate validation needs a canonical owner.** The same rule MAY be - pre-checked at another layer for UX / performance (e.g. an application pre-check - mirroring a DB unique constraint), but the **canonical owner** of the rule must be - named in a code comment or the relevant `CLAUDE.md`. A duplicate validator with no - documented owner is a review failure (silent contradiction risk). This is a process - gate (PR review), not an automated rule — `needs-confirmation` until an owner-marker - annotation is justified. +- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 + `adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로 + 나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙 + `validation_constraints_stay_at_web_boundary`가 빌드를 실패시킨다. +- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성 + 경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴 + 인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만 + 지키기」). +- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는 + **클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index + 이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본 + `GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로 + 바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은 + `feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다. +- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수 + 있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나 + 관련 `CLAUDE.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날 + 위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지 + `needs-confirmation`이다. -Out of this branch's scope (cross-referenced, not re-implemented here): the -SQLState→code 9-row matrix and the `DataAccessException` translator -(`feature-persistence-failure-baseline`); the Jackson B1/B2 request-boundary switches -and mapper sentinel (`feature-boundary-validation-mapping-contract`); the envelope, -`Category` enum, and `OperationalError` codes +이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와 +`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper +표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드 (`feature-operational-error-observability-foundation`). -## Test +## 테스트 ```bash cd src diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 134acd95..a2d2830e 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -16,13 +16,12 @@ route inventory)는 opt-in leaf `adapter:inbound:web-advanced` 에 있다 --- -## OpenAPI contract stabilization +## OpenAPI 계약 고정 -Springdoc 3 represents an untyped Java `Object` as an unconstrained OAS 3.1 schema (`{}`). -`OpenApiContractConfig` owns the transport-specific correction for the shared `ApiError.details` -field and publishes it as `type: object`. This preserves the committed HTTP contract without adding -Swagger annotations or dependencies to `shared-contract`. Real-server OpenAPI tests import this -production configuration and compare the result with the committed snapshot. +Springdoc 3은 타입 없는 Java `Object`를 제약 없는 OAS 3.1 schema(`{}`)로 나타낸다. +`OpenApiContractConfig`가 공용 `ApiError.details` 필드에 대한 전송 계층 보정을 가지고 그 필드를 +`type: object`로 낸다. 그래서 `shared-contract`에 Swagger 애너테이션이나 의존성을 더하지 않고 커밋한 HTTP +계약을 지킨다. 실제 서버 OpenAPI 시험은 이 운영 설정을 import하고 결과를 커밋한 snapshot과 비교한다. --- @@ -374,7 +373,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML ## ratelimit -### provider-neutral edge contract +### provider 중립 edge 계약 - inbound web은 `shared-contract`의 `EdgeRateLimitPort`만 호출한다. Redis key, Lua, local counter와 provider 설정을 알지 못한다. @@ -579,7 +578,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML ## idempotency -### Ownership +### 소유 - `Idempotency-Key`는 HTTP 경계가 읽어 application command/context로 전달할 수 있지만, **claim / fingerprint / replay / in-flight arbitration은 application use case가 소유**한다. - web leaf에는 별도 DB replay 엔진을 두지 않는다. 같은 요청 의미를 web/application 두 계층이 서로 다른 diff --git a/src/adapter/inbound/websocket/CLAUDE.md b/src/adapter/inbound/websocket/CLAUDE.md index 4b54b060..cc19b9f8 100644 --- a/src/adapter/inbound/websocket/CLAUDE.md +++ b/src/adapter/inbound/websocket/CLAUDE.md @@ -1,127 +1,120 @@ -# adapter:inbound:websocket — conditional WebSocket/STOMP boundary +# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계 -## Registered identity +## 등록 정보 -- Module ID: `adapter-inbound-websocket` -- Gradle path: `:adapter:inbound:websocket` -- Focused test: `./gradlew :adapter:inbound:websocket:test --console=plain` -- Runtime baseline: Java 21, Spring Boot 4.0.8 -- Registry SSOT: `src/config/architecture/modules.json` +- 모듈 ID: `adapter-inbound-websocket` +- Gradle 경로: `:adapter:inbound:websocket` +- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain` +- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json` -Package root: `dev.caskeleton.adapter.inbound.websocket`. +패키지 루트: `dev.caskeleton.adapter.inbound.websocket`. -## Responsibility +## 책임 -This leaf contains **two different scopes** and they must not be read as one deployed feature: +이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다. -1. **Opt-in STOMP/SockJS channel** — `stomp/**` owns the Spring transport configuration, typed - `app.websocket.*` settings, handshake principal/origin checks, destination policy, - fixed client-safe STOMP `ERROR` mapping, and best-effort in-process event projection. -2. **Servlet handler library** — `servlet/`, `outbound/`, `budget/` plus the two id records - `core/WebSocketConnectionId` and `protocol/WebSocketMessageId`. No settings keys, no Spring - configuration: a service's own adapter leaf constructs `PlatformWebSocketHandler` and registers - it. README "라이브러리 API" lists the entry points and the wiring. +1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정, + handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는 + 만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다. +2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘 + `core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의 + 어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을 + 적는다. -This leaf does not deduplicate commands and owns no storage SPI. The former `idempotency/` -package (command ledger, `WebSocketActorReference`, `WebSocketEndpointName`) was removed on -2026-09-25. A command that must run at most once goes through the application -`IdempotencyExecutor` inside its use case, with a scope that survives a reconnect (endpoint + actor -+ the client's own message id), never the connection id. +이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command +원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는 +command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도 +살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다. -The module itself is absent from both shipped runtime compositions. Being registered and tested -does not activate either scope. +이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다. -## Allowed +## 허용 -- Registered dependency on `:domain-core` for the `@DomainEvent` marker. -- Spring Boot WebSocket and validation starters, managed by the repository BOM. -- Test-only embedded Tomcat/Jetty/SockJS/STOMP clients and Testcontainers (Nginx lane). +- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존. +- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter. +- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane). -## Forbidden +## 금지 -- Direct dependency on any `adapter:outbound:*` module. -- Repository, Spring Data, persistence entity, or business policy access. -- Raw `@DomainEvent` payload transmission or reflection-based event serialization. -- Wildcard/blank handshake origins when enabled. -- Anonymous handshakes, arbitrary topic subscriptions, or client sends to broker destinations. -- A production feature `@MessageMapping` in this skeleton leaf. -- A module-local YAML file; composition roots own property values. -- Settings keys, flags or catalogs for behaviour no code in this leaf performs. A bound that the - handler does not enforce is not a field of `WebSocketConnectionBudget`. -- Reactive (WebFlux) WebSocket code: the template is servlet-only. +- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기. +- repository, Spring Data, 영속 엔티티, 업무 정책 접근. +- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화. +- 켜져 있을 때 wildcard·빈 handshake origin. +- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기. +- 이 골격 leaf 안의 운영 기능 `@MessageMapping`. +- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다. +- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는 + `WebSocketConnectionBudget`의 필드가 아니다. +- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다. -## Typed settings (`app.websocket.*`) +## 타입 있는 설정 (`app.websocket.*`) -There is one property tree and one operator env prefix: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. -They configure the STOMP channel only. The default bootJar does not contain this leaf, so these -values matter only in a composition that adopts it. +속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만 +설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다. -| property | env | default / role | +| 속성 | env | 기본값·역할 | | --- | --- | --- | -| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`; `false` turns the STOMP/SockJS channel off | +| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 | | `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` | -| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`; explicit origins only | +| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 | | `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | -| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`; messages each STOMP channel (client inbound, client outbound, broker) queues before rejecting | -| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB` (Spring default, now explicit) | -| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB` (Spring default, now explicit) | -| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s` (Spring default, now explicit) | -| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s` (Spring default, now explicit) | -| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`; STOMP sessions per node, the next is closed with 1013 | +| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 | +| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) | +| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) | +| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) | +| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) | +| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 | -`WebSocketSettings` is `@Validated`. Invalid enabled settings fail context startup. +`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다. -## Adopting this capability +## 이 capability 채택하기 -WebSocket is a **build-composition opt-in**, not a dormant feature inside the default bootJar. +WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다. -1. Add `:adapter:inbound:websocket` to the consuming composition's dependencies and add the - matching allowed edge in `config/architecture/modules.json`. -2. Keep settings registration with the capability root; do not add - `dev.caskeleton.adapter.inbound.websocket` back to the shipped - `@ConfigurationPropertiesScan`. -3. The STOMP/SockJS channel is registered by this leaf's own `AutoConfiguration.imports` and is on - whenever the leaf is on a servlet classpath; set a non-wildcard origin allowlist, and - `app.websocket.enabled=false` to turn it off. -4. For the handler library, follow README "라이브러리 API". The handler must be a bean so its - `SmartLifecycle` stop (1001 to every open connection) runs before the web server stops. -5. Run the leaf lanes and the repository conditional-transport aggregate before promoting the - composition: +1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용 + edge를 더한다. +2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에 + `dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다. +3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에 + 있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로 + 한다. +4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그 + `SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다. +5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다: `./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`. -## Inbound policy (STOMP) +## inbound 정책 (STOMP) -- The HTTP upgrade must already have a nonblank `Principal`; the adapter does not authenticate - credentials itself. -- STOMP `SUBSCRIBE` is allowed only for the configured broadcast destination. -- Authenticated `SEND` is allowed only below `/app/**`. -- Client `SEND` to `/topic/**` and other destinations is rejected. -- Every client-visible processing failure becomes an ERROR frame with an empty payload and the - fixed `message` `WEBSOCKET_REQUEST_REJECTED`. Its `error-code` header is the carried - `ApiErrorCode` of the first `ApiErrorCarrier` in the cause chain (even behind an - `IllegalArgumentException`), `BAD_PARAMETER` for an `IllegalArgumentException`, and - `WEBSOCKET_REQUEST_REJECTED` otherwise. +- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다. +- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다. +- 인증된 `SEND`는 `/app/**` 아래에만 허용한다. +- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다. +- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진 + ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은 + `ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그 + 밖에는 `WEBSOCKET_REQUEST_REJECTED`다. -## Event projection contract +## 이벤트 projection 계약 -A future feature may contribute a `LiveEventProjector` bean for one exact `@DomainEvent` class. -The broadcaster sends only when exactly one projector matches. Zero or duplicate projectors, -projection failures, invalid event types, null fields, and over-limit maps are dropped. The wire -envelope contains only `type`, bounded string `fields`, and `occurredAt`. The broker channel has its -own bounded executor, so the simple broker's fan-out to subscribers never runs on the thread that -published the domain event; a full broker queue drops the event (best-effort, R1). +나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector` bean을 기여할 수 있다. +broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이 +실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는 +`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로, +simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면 +이벤트를 버린다(best-effort, R1). 템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다. -## Evidence and limits +## 증거와 한계 -| lane | what it proves | +| lane | 증명하는 것 | | --- | --- | -| `test` | STOMP settings/policy, queue/writer/budget, handler size and overflow closes | -| `systemTest` | real Tomcat: STOMP boundary (`WebSocketBoundaryQualificationTest`), handler runtime and abuse contracts, context close sends 1001 | -| `websocketJettyTest` | the handler runtime contract on Jetty | -| `websocketNginxTest` | upgrade/forwarding behind a real Nginx (Docker required; fails without it) | -| `websocketTransportQualificationTest` | no-skip execution of the STOMP boundary test | +| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 | +| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 | +| `websocketJettyTest` | Jetty에서 handler 런타임 계약 | +| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) | +| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 | -The simple broker is local, single-process, best-effort R1 evidence only. Broker relay, -multi-node/durable delivery, rollback-safe publication and replay/resume are not provided. +simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달, +롤백에 안전한 발행, replay·resume은 주지 않는다.