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

9.1 KiB

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는 그 실행의 출력이다:

./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에서 읽어 파생한다.

cd src
./gradlew <gradle-path>:test --console=plain

Family 전체 검증:

./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew architectureCheck --console=plain
./gradlew verifyDependencyLocks --console=plain