Files
messaging-library/messaging/CLAUDE.md
T
DongHyeonkaandClaude Opus 5.5 5e44be9ab4 refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(b5114b9b)과 함께 기록.

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

8.6 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 framework-free 실행 로직 Micrometer는 observability에서만. 나머지는 stdlib
kafka broker adapter 해당 broker client. Spring은 client가 곧 Spring인 경우만
outbox-jdbc-postgresql, inbox-jdbc-postgresql 관계형 신뢰성 adapter Spring JDBC / Spring TX. JPA 아님 — 이름이 곧 계약이다
spring-boot-starter, spring-boot-starter-kafka 조립 경계 Spring Boot autoconfigure. 여기서만
testkit 테스트 지원 Testcontainers, JUnit. production leaf가 의존하지 않는다

outbox/inbox leaf가 jdbc-postgresql로 명명된 이유: 구현은 Spring JDBC이고 SQL은 ?::jsonb · FOR UPDATE SKIP LOCKED · ON CONFLICT · TIMESTAMPTZ로 PostgreSQL 전용이다. jpa라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. vendor 중립 계약은 messaging-reliability-api에 있다.

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, canonical bridge 구현 / legacy 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가 끝난 것은 아니다. legacy OutboxEvent와 realtime publisher는 schema/order/tenant 등 canonical metadata가 부족해 아직 MessageBroker → KafkaSender R0 경로를 사용한다. 그 metadata를 추측해 platform envelope를 만드는 것은 금지한다. 따라서 legacy outbox storage/relay migration을 별도 change set으로 완료한 뒤에만 R0 seam을 제거한다.

canonical bridge의 producer identity는 app.messaging.producer-id로 명시한다. 값이 없으면 bridge bean을 만들지 않으며 spring.application.name/host/pod 이름에서 identity를 발명하지 않는다.

ca-skeleton.outbox.canonical-transport-enabled=true는 bridge 존재만으로 충분하지 않다. Stable composition은 애플리케이션 계약 catalog/schema source를 임의로 만들지 않으므로 adopter가 IntegrationEventEncoderPort를 명시적으로 제공해야 한다. 템플릿은 구현체를 주지 않는다(후보였던 R1 JSON Schema encoder는 2026-09-25에 삭제). OutboxCanonicalTransportRequirementValidator는 publisher 또는 encoder 중 하나라도 없으면 startup을 거부한다. 즉 canonical flag가 켜졌는데 정본 encoder가 없는 상태로 성공 기동하는 경로는 없다.

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