Files
DongHyeonka dd194784c3
main / main-check (push) Successful in 8m35s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.

- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
  타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
  고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
  (Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
  Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
  grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
  Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
  docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
  인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
  docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
  이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
  시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
  않았다.

검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.

Refs: design-docs repo-structure/05-library-repos.md 14.2절
2026-11-08 16:16:38 +09:00

13 KiB

messaging — 메시징 플랫폼 family의 지역 정본

이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 config/architecture/modules.json이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 필요한 증거, runtime membership이 비어 있다는 사실의 의미.

루트 AGENTS.md와 충돌하면 루트가 이긴다.

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 모듈 리뷰 뒤 소유자가 정한 배치, 2026-11-08에 별도 repo로 옮김), messaging:* leaf는 템플릿의 domain-core·application-core·shared-contract 어느 타입에도 의존하지 않는다. 다른 repo가 된 지금은 그 타입에 닿을 길 자체가 없다. 복사본을 고칠 때(키 길이 검사, 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의 api closure에 broker client 두 개가 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 등장하고 adopter가 이름 부를 일이 없다.
  • 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.

Application runtime에 포함되는 기준

소비자는 지금 백엔드 템플릿 하나다(dev.cakit.messaging:*를 Gitea Packages에서 버전으로 받는다). 템플릿의 기본 조립에는 Messaging family가 없다. 서비스가 템플릿 app-bootstrap/build.gradle에 runtimeOnly project(':adapter:outbound:messaging-kafka') 한 줄을 넣으면 그 모듈이 bridge와 messaging-spring-boot-starter-kafka(core starter 포함)의 transitive 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 상태를 함께 변경한다. 소비하는 앱 쪽 edge(템플릿 registry의 「허용 라이브러리」 칸)는 그 앱 repo에서 바꾼다.

application이 이 family에 도달하는 경로 (cutover 완료)

아래 경로와 타입 이름은 백엔드 템플릿 쪽이다(이 repo에는 없다). 리뷰(템플릿 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가 현재 상태를 기록한다):

  1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 BrokerCertificationEvidence를 산출한다.
  2. NetworkFaultScenario 전 항목에 대해 evidence가 있거나, 없는 항목이 knownGaps로 명시된다.
  3. capability 선언이 코드에서 파생된다 — MessagingCapabilities에 손으로 true를 쓰는 것은 증거가 아니다.
  4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 Experimental에서도 금지다.
  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에서 읽어 파생한다. repo 루트에서 돌린다.

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

Family 전체 검증:

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