Files
messaging-library/messaging/CLAUDE.md
T
donghyeon-kaandClaude Opus 5.5 6397f52dc8 review-followup Wave 3 라운드 2(P18): outbox canonical 통일, composition 모듈, legacy Kafka seam 삭제
- 결정 7: `LegacyOutboxAppendPort`·legacy 저장 모델·relay·Kafka R0 seam 삭제, 템플릿 JSON encoder(`JsonIntegrationEventEncoder`),
  durable operation·sample 이벤트가 `OutboxAppendPort` + encoder로, persistence-jpa V19(pre-canonical 미발행 row 거부)
- 결정 3: outbox relay·멱등성 executor 조립을 `composition:outbox-relay`·`composition:idempotency`로,
  sample이 복사한 bootstrap 인프라를 `composition:service-runtime`으로(sample `SampleIdempotencyConfig` 복사본 삭제)
- persistence-jpa outbox·멱등성 패키지 feature 기준 이동, messaging outbox·inbox leaf를 reliability / reliability-jdbc-postgresql로
- messaging outbox header를 jsonb로(P18-new-1 — `\`로 끝나는 값이 다음 header를 삼키던 결함)
- 통합(충돌 22건): P25 A-10c(전략 선택 설정 삭제)를 service-runtime `DomainContextConfig`에 적용, P25 startup 예외 통합을
  composition 설정 테스트에, P25 `CommandUseCase.handle` 이름을 PG 통합 테스트에, P15 `EventJson`은 호출자 0이 되어 삭제
- root CLAUDE.md의 legacy seam 문장 수정(P18-new-2)

검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,OutboxAppendTransactional,OutboxConcurrentRelay,OutboxRowLifecycle}IntegrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest --continue 통과(700 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 12:30:01 +09:00

141 lines
9.1 KiB
Markdown

# messaging — local authority for the messaging platform family
이 문서는 messaging family의 **local authority**다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에
필요한 증거, runtime membership이 비어 있다는 사실의 의미.
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
## Family와 framework 규칙
leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의
역할로 정해진다.
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `*-api` (`core-api`, `schema-api`, `policy`, `reliability-api`, `admin-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
| `runtime-core`, `security`, `observability`, `admin-runtime`, `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`,
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
가졌고 inbox도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
## Public surface 정책
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
`implementation`으로 둔 것이 그 예다.
- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production
source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의
`build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가
들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만
등장하고 adopter가 이름 부를 일이 없다.
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
## Application runtime에 포함되는 기준
기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에
`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와
`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이
사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다.
모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다.
일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표).
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
qualification/support 상태를 함께 변경한다.
## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료)
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
- application-owned port: `IntegrationEventPublishPort`
- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter`
- platform boundary: `EncodedMessagePublisher`
- central implementation: `DefaultMessagePublisher`
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
package는 `messaging-core-api`와 `messaging-schema-api`만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
profile(`KafkaSecurityConfigurer`)을 적용한다.
canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의
`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`)
안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한
`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과
다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.
## Stable 승격에 필요한 증거
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
상태를 기록한다):
1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
`BrokerCertificationEvidence`를 산출한다.
2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다.
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
증거가 아니다.
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
Experimental에서도 금지다(MSG-022).
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
있을 때만.
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
```bash
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain
```
레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며,
통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다.
게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고,
레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다).
skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는
`messaging-certification` 태그로 제외된다.
## Focused test
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
```bash
cd src
./gradlew <gradle-path>:test --console=plain
```
Family 전체 검증:
```bash
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew architectureCheck --console=plain
./gradlew verifyDependencyLocks --console=plain
```