docs(adapter-inbound): inbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: 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.
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 목록과 수는 레지스트리가 정한다). 즉 레지스트리는 닫혀 있지 않았고,
|
||||
"확장하면 게이트가 깨진다"는 전제는 과했다. 두 플랫폼이 서로 다른 패턴을 쓰고 있으므로
|
||||
**어느 쪽으로 통일할지는 미결 아키텍처 결정**이다.
|
||||
|
||||
|
||||
@@ -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<Principal> authenticate(Met
|
||||
이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS,
|
||||
external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다.
|
||||
|
||||
## Test
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
|
||||
@@ -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<T>`), 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<T>`)만 구현하고,
|
||||
`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`.
|
||||
|
||||
@@ -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
|
||||
|
||||
+136
-179
@@ -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<T>`) 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<T>`) or
|
||||
`Optional<T>` 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<T>`)을 써서 JSON `null`이 primitive `0`이 되지 못하게
|
||||
한다.
|
||||
- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는
|
||||
*없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에
|
||||
`org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나 `Optional<T>` 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<T>` + `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<T>` + `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<T>` (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<T>`(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
|
||||
|
||||
@@ -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 두 계층이 서로 다른
|
||||
|
||||
@@ -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<T>` 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<T>` 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은 주지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user