AGENTS.md와 src/**/CLAUDE.md는 본문에 지난 리뷰 ID를 두지 않는다 (docs/work/README.md 8절). 번역한 CLAUDE.md 넷에 짝 하나짜리 번호가 남았다: persistence-jpa·app-bootstrap의 「07-08」, grpc의 「11-M9」, messaging의 「06-01 수정」. check-work-docs.py는 단독 NN-NN을 일부러 잡지 않으므로(범위·절 번호와 구별할 수 없다) 통과했다(번역 묶음 D2b가 넘긴 것). ID 대신 그 발견의 내용과 날짜를 적었다. 원래 ID와 근거 리뷰 파일은 docs/work/evidence.md 10절 끝에 행 넷으로 남겼다(앞 행들과 같은 칸). 검증(노트북): check-work-docs.py OK, --history(바꾼 파일) 이력 ID 0, check-docs.py OK. 이 넷을 읽는 테스트는 없다(git grep 'CLAUDE.md' -- '*Test.java').
12 KiB
messaging — 메시징 플랫폼 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 — api·schema 패키지, policy, reliability-api, transport-spi) |
값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
schema-* (json/avro/protobuf), cloudevents |
인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
runtime-core, security, observability, admin(계약 admin + 실행 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도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 jdbc-postgresql로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 jsonb · FOR UPDATE SKIP LOCKED · ON CONFLICT · TIMESTAMPTZ로 PostgreSQL
전용이다. jpa라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
공용 다이제스트 헬퍼를 복사해 두는 이유
messaging-admin(HmacApprovalVerifier, PlanDigest)과 messaging-claim-check
(ClaimCheckIntegrityGuard)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
shared-contract digest/Sha256·HmacSha256을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), messaging:* leaf는
domain-core·application-core·shared-contract 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
shared-contract의 정본과 같은 규칙인지 함께 본다.
인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization)
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
- category 기본값:
FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false. 소비 쪽 재시도 엔진(DefaultRetryDecisionEngine)은 policy가 category를 따로 정하지 않으면 이 기본값과 descriptor의retryable을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다. - publish 거부의
retryable:KafkaPublishFailureClassifier는 인증·인가 거부에retryable = true를 붙인다. broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 publish를 거부한 뒤 멈추기 때문이다.retryable을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 않게 하려는 것이다.
다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두 publish 경로, 소비 경로 동작은 그대로):
KafkaPublishFailureClassifier: 인증·인가 거부를retryable = true로.DefaultMessagePublisher: runtime이 없을 때의 거부(PUBLISH_RUNTIME_UNAVAILABLE)를retryable = true로.KafkaMessagingTransport: 닫힌 transport의 거부(KAFKA_TRANSPORT_CLOSED)를retryable = true로.MessagingShutdownLifecycle.PHASE: platform 밖 relay의 순서 테스트가 참조하도록 public.
버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로
번역하는 것. 버린 이유: retryable은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
PublishResult를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
relay, composition:outbox-relay)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
Public surface 정책
- vendor 타입을 public signature에 노출하면 그 의존성은
api로 선언한다. 숨긴다고 타입이 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. (kafka-clients,cloudevents-api,micrometer-core,avro,protobuf-java가 이 규칙으로api다.) - 반대로 노출하지 않는 것은
implementation으로 낮춘다. starter가 노출하지 않는 하위 모듈을implementation으로 내린 것이, JSON codec이ObjectMapper를 private으로만 쓰고 Jackson을implementation으로 둔 것이 그 예다. - 이 규칙은 문서가 아니라
MessagingPublicSurfaceContractTest가 붙들고 있다. leaf의 production source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의build.gradle이api로 선언했는지 대조하고, starter의apiclosure에 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에 도달하는 경로 (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만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정). 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가 현재
상태를 기록한다):
- 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
BrokerCertificationEvidence를 산출한다. NetworkFaultScenario전 항목에 대해 evidence가 있거나, 없는 항목이knownGaps로 명시된다.- capability 선언이 코드에서 파생된다 —
MessagingCapabilities에 손으로true를 쓰는 것은 증거가 아니다. - publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 Experimental에서도 금지다.
- 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