Files
messaging-library/messaging/CLAUDE.md
T
DongHyeonkaandClaude Opus 5 a855647a5b refactor(build,ci): 현재 상태 검증을 걷어내고 불변조건만 남기는 검증 표면 축소
외부 리뷰("현재 상태를 유지하기 위한 검증이 너무 많고, 그 검증 자체를
다시 검증하는 구조까지 생겼다")를 설계 문서로 정리하고 코드로 반영한다.
설계·판단 근거는 docs/superpowers/specs/2026-09-16-verification-surface-reduction-design.md.

삭제
- .github/ci-gate-matrix.yml(1,025줄) + verify-gate-matrix.sh(568줄):
  Gradle task graph와 workflow graph에 이미 있는 정보의 3중 복제
- verify-gradle-wrapper.sh(799줄): workflow 바이트 해시 잠금.
  wrapper 검증은 gradle/actions/wrapper-validation(full SHA 핀)에 위임
- DeveloperExperienceContractTest 등의 CI YAML mutation 테스트:
  애플리케이션 test suite가 GitHub Actions YAML 파서를 검증하던 계층 역전
- 문서 drift 파서: verifyReadmeCommands, verifyRunbookReferences,
  verifyDocumentedLeafCount, verifyTestSourceSetRegistry
- 빈 레지스트리를 지키던 커스텀 YAML 파서: verifyTrivyignore,
  verifyQuarantineSunset, flaky-quarantine.yaml
- verifyConfigurationPropertiesProcessor, verifyOneTypePerFile:
  각각 ca.spring-config convention과 Checkstyle OneTopLevelClass가 대체
- 정상 입력으로도 성공할 수 없던 messaging always-fail task
- ModuleRegistry의 JSON 필드 집합 정확 일치, sample-portfolio negative guard

이동
- java/quality/spring 공통 설정을 configure(subprojects) 블록에서
  ca.java-conventions / ca.quality-conventions / ca.java-library /
  ca.spring-library convention plugin으로
- 아키텍처 검증을 ca.architecture로, JPA·messaging qualification을
  gradle/qualification/ 아래로, verifyEnvKeys를 :app-bootstrap 소유로

완화
- Git revision은 releaseCheck·아카이브 생성에서만 요구. 일반 빌드는 SNAPSHOT
- SpotBugs/FindSecBugs는 로컬 check에서 빼고 qualityCheck 레인으로

task 계층
- leaf check는 그 leaf만. architectureCheck / qualityCheck /
  configContractCheck / integrationCheck / ci / releaseCheck로 이름 분리

CI
- _reusable-gradle.yml 신규. checkout + wrapper validation + JDK/캐시 공통화
- fileserver-release.yml -> fileserver-certification.yml (CD가 아니라 certification)
- GitHub Actions = CI + artifact, Argo CD = CD 경계를 docs/ci-cd/boundary.md로 고정

순증감 +3,274 / -7,483.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-16 20:33:19 +09:00

8.4 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, rabbit, pulsar-experimental, nats-experimental, kafka-share-experimental broker adapter 해당 broker client. Spring은 rabbit의 spring-rabbit처럼 client가 곧 Spring인 경우만
outbox-jdbc-postgresql, inbox-jdbc-postgresql 관계형 신뢰성 adapter Spring JDBC / Spring TX. JPA 아님 — 이름이 곧 계약이다
spring-boot-starter, spring-cloud-stream-bridge 조립 경계 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, spring-rabbit, 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로 취급한다.

Runtime membership이 비어 있다는 것의 의미

이 절은 한동안 사실이 아닌 채로 남아 있었다. "registry의 모든 messaging leaf는 runtime_memberships가 비어 있고 따라서 build-only"라고 쓰여 있었는데, 다섯 어댑터 remediation이 messaging-spring-boot-starter를 app-bootstrap 의존성으로 넣으면서 그 closure 전체가 런타임 classpath에 올라갔다. 정확한 목록은 registry가 소유하므로 여기서 세지 않는다 — 세는 순간 다시 drift한다.

지금 의미는 이렇다:

  • 대부분의 leaf는 runtime_memberships에 app-bootstrap을 갖는다. 배포된 아티팩트가 싣고 있고, master switch app.messaging.enabled로 켜진다. 기본값은 false다.
  • 여전히 비어 있는 leaf(experimental transport, 일부 codec, bridge, testkit)만이 build-only / incubating이다.
  • 런타임에 있다는 것과 자격이 증명됐다는 것은 다르다. Kafka publish 경로만 실브로커 round trip으로 자격 검증됐고(MessagingLiveRoundTripQualificationTest), Rabbit·JDBC inbox/outbox·claim check·admin plane은 shipped, inactive, unqualified다. 이 구분은 MessagingMembershipQualificationTest가 문서가 아니라 테스트로 붙들고 있다.
  • 애플리케이션에 새로 배선하려면 registry의 runtime_memberships를 먼저 바꾸고 verifyRuntimeModuleMembership을 통과시켜야 한다. 코드만 추가하는 것으로는 런타임에 들어가지 않는다.
  • 지원 상태 문서(docs/messaging/support-matrix.md)의 tier는 이 사실과 별개다. tier는 "무엇이 증명되었는가", membership은 "무엇이 실행되는가"다.

application이 이 family에 도달하는 경로 (MSG-015, 미해결)

리뷰(docs/reviews/2026-08-14-messaging-module-code-review.md §6.1·§6.3)가 정한 흐름은 application-owned port → platform anti-corruption bridge → platform이고, §6.2는 그 bridge의 자리를 adapter/outbound/messaging/platformbridge/로 지정한다. §6.3 첫 규칙: application은 신규 broker/runtime 타입을 직접 보지 않고 자기 port만 소유한다.

현재 그 bridge가 없다. adapter/outbound/messaging은 platform에 의존하지 않고(registry의 allowed_dependencies 참조), app-bootstrap이 starter를 직접 문다. 그래서 서로를 모르는 messaging 스택 두 개가 한 아티팩트에 있고, 그것이 kafkaSeamProducer/messagingKafkaProducer bean 이름 충돌로 드러났다.

이것이 리뷰의 MSG-015 (P0) 이며 닫히지 않았다. 지금 안전한 이유는 설계가 아니라 기본값이다 — app.messaging.enabled=false. 이 스위치를 켜는 배포는 port를 거치지 않는 경로로 platform을 쓰게 된다. bridge 구현은 런타임 배선 변경이라 리뷰가 말한 대로 별도 change set이다.

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