# messaging-library Spring Boot 앱에 브로커 중립 메시징을 붙이는 라이브러리다. 발행·소비 API와 transport SPI, Kafka adapter, 관계형 outbox·inbox(PostgreSQL)와 relay, 재시도·DLQ·redrive 정책, 보안·관측 규칙, schema codec(JSON·Avro·Protobuf·CloudEvents), 운영자 admin 계약, 실제 브로커로 만든 인증 증거를 준다. ```text 앱 소유 port ──> 앱의 adapter(bridge) ──> messaging-core-api (Java 표준 라이브러리만: envelope·destination·publish 결과·port) └─ messaging-spring-boot-starter (조립, broker 중립) ├─ messaging-runtime-core (중앙 publish 경로) ├─ messaging-reliability (+ -api, -jdbc-postgresql): outbox·inbox ├─ messaging-policy · -security · -observability · -admin └─ messaging-spring-boot-starter-kafka (Kafka transport capability) ``` ## 받는 법 Maven group은 `dev.cakit.messaging`, artifact는 모듈 이름 그대로다(`messaging-core-api`, `messaging-spring-boot-starter-kafka`, …). 저장소는 소유자 Gitea Packages이고, 공개라 읽을 때 토큰이 필요 없다. ```groovy // settings.gradle dependencyResolutionManagement { repositories { exclusiveContent { forRepository { maven { url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' } } filter { includeGroupByRegex 'dev\\.cakit(\\..*)?' } } mavenCentral() } } ``` ```groovy // build.gradle dependencies { implementation 'dev.cakit.messaging:messaging-core-api:1.0.0' runtimeOnly 'dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0' } ``` `exclusiveContent`는 `dev.cakit` group을 이 저장소에서만, 나머지는 Maven Central에서만 찾게 한다. 같은 이름을 공개 저장소에 올리는 공격이 통하지 않고, Gitea가 느려도 다른 의존성 해석에는 영향이 없다. 신뢰성 migration은 `messaging-reliability-jdbc-postgresql` jar 안의 classpath 위치 `db/migration/messaging`(`V1001`~`V1005` outbox·admin journal, `V1101` inbox)에 있다. 받는 앱의 Flyway가 그 위치를 읽게 한다. 이 위치와 파일 내용은 배포한 뒤 바꾸지 않는다. ## 지원 표 | 라이브러리 | Spring Boot(컴파일·시험한 줄) | Kafka client · 인증한 broker | PostgreSQL(시험) | Java | | --- | --- | --- | --- | --- | | 1.0.x | 4.0.x (`4.0.9`) | `kafka-clients` 4.1.2(Boot가 관리) · `apache/kafka:4.1.0` | 16 | 21 | 무엇을 인증했고 무엇은 지켜보기만 하는지는 `docs/messaging/support-matrix.md`다. 인증 증거는 `messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`이고, main 단계가 실제 Kafka로 다시 만들어 대조한다. ## 프로젝트 구조 | 폴더 | 무엇 | | --- | --- | | `messaging/` | 모듈. 규칙은 `messaging/AGENTS.md` | | `build-logic/` | 백엔드 템플릿에서 복사해 줄인 Gradle convention 플러그인. 출처는 `build-logic/UPSTREAM.md` | | `config/` | 모듈 registry(`architecture/modules.json`), Checkstyle·SpotBugs 설정, 테스트 컨테이너 이미지 | | `scripts/` | 검증 진입점 `verify.sh`, 고정 도구 `tool.sh`, 릴리스 보조 `release/` | | `.gitea/workflows/` | 단계 파일: `pr.yml`(`ci`), `main.yml`(`mainCheck`), `release.yml`(`releaseCheck release`), `signing-check.yml`(수동) | | `docs/` | 문서. 지도는 `docs/README.md` | ## 문서 지도 - 작업 방법: `docs/work/README.md`(고치기·리뷰), `docs/work/gates.md`(게이트), `docs/work/release.md`(릴리스·버전 규칙·비밀 값) - 제품 문서: `docs/messaging/`(설정 참조, 전달 보장, outbox·inbox, 재시도·DLQ·redrive, 보안, 운영, 지원 표, 실험 정책, 이전·cutover 안내) - 설계서: `docs/design/2026-08-10-messaging-platform-design.md` - 바뀐 것: `CHANGELOG.md` ## 서명 배포 파일마다 PGP 서명(`.asc`)이 붙는다. 서명 키는 RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07에 만료된다. grpc-library와 같은 키다. 키를 바꾸는 법은 `docs/work/release.md` 1절이다. ```text -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBGrv1SYBEADGgq8CTE7wdDPIg0zNRXelPvlgyK04tpDTL0b9k1INxDwFEiS0 87bTL22Zjipp+2uDg012TALeLsDV12yh1IToNaYq7zR9bRvEua25+351zw91ojC+ z2/1Y7S98o813hu6qP6EFUHnsWPVLEt40mlGDn3kl8iXMLgjozVYbylomweh/Yvz HLJd5lQGE76mIejIeGp3m1OA5M2RV4xspA8K8TZkXXSqe3nbfSjPXAOwysPmRRd9 IoLDwakSq4tRI9dlm08bzznsoaaTCRcJ0XAbJK7+ZrQkSwIrsi/gsBkCOJI6Wcs6 +R+9Wy7tYsyd59TdgIdjq3uHadSLWQ3dc0g0ux2krxSL0PHXrT9Upmcorj2+Ltkh 9J1I6hUv1O7e0Y8Es7Ov5WUPfdSdQ5ApwtwFX5aSwYokoW9wXMLg2zdQx0JEx1ix /qTEvpSKfM0/zVbKJO9RDF/F7HZkDWSOhZe+4x7dak+xN6KOfEQVmcBneaGtPqgJ eAsIBgRwp42G5llqnTcWAHLAKCDEE9wHK3+gJt5f5rO5e+r1GoYHLn0Iw3iiX6rC NFot/5my/oePTeRur5tjv14kw1FMXHVNvLOxHeaiZzfVVjO/vbwAtGvZDiRdAgd6 kHyt9Ch/JccIa0ylA9Tttb0A33ZGTQl6sAC6jTSIhfnEAdlCX7MVAE8n4wARAQAB tCNkb25naHllb24ua2FuZyA8ZG9uZzUxMjlAZ21haWwuY29tPokCVwQTAQoAQRYh BJJkbOr+gWz4ucJJ8KHJNtf3kfirBQJq79UmAhsDBQkDwmcABQsJCAcCAiICBhUK CQgLAgQWAgMBAh4HAheAAAoJEKHJNtf3kfir2j8P/RWRT0GTxBNQvm76iO6XnvFD mDPGq37A5iuD4pJ624/BccKTGe8+WWqtlpAiN6AdHGNi/LGhuYaGL9ce6Gja5tTX y/ZY8jthbEoi41g6cim8W8knd3v2Ne/qj3dKvphSiVsZBrumEzrZyw2UUD3IRqVx r2WQZTcSa4UDd7+Qie0h8IrnmfMYIseDCWjDCATNJqr9PBGoKYehv8+Wo3QDVBRd B0lWepudJjLTsPCXsgFnFJ2HmltRQr1JB+I4CPasfsBp3xqF23hywUuW6fOsHZvv g5QU7qYfaoxG6E8krGpiibocF5EKXtpEYzDOBFoDS9uNVBAD/LzS7OGtTFr5x3qL is3eccwNClQS1jeX8Guxam+TlO8XaqnQLCIpdau20/sge6PqXKXauKZiBTGCak1j zVDQ/sro3VRPePusNHK1CdOi6wiruXw4ZLWO3aEHibi8LbgfwymxXHEtJO5zwFcD qAnp7KEAkOG8y5LR0FfwWWYnqUZxWJ0ua2Acf8gL8o6DO5pVyJSYrdgCpWjwEWcp Ms2iit9bCNIMaH6EVgLA2NWCuIL9xAFdXqw/VXrMVK3XXftzNvayvLJCH2eintRg IKLO/ewISKIFQd3+II3/MM80eUvKGtfi8Y1mj1zyQtcPVykru5DEHjpaLs2SPxdI Lp+HGQo/NvzwdpIV+8TQ =eD8w -----END PGP PUBLIC KEY BLOCK----- ``` 받은 파일을 확인하는 법: 위 키를 `gpg --import`로 넣고 `gpg --verify <파일>.asc <파일>`. 배포 토큰 secret 이름은 설계 문서의 `PACKAGES_TOKEN`이 아니라 등록된 `PACKAGE_TOKEN`이다. ## 이력 - 2026-08-14 ~ 2026-11-07: 백엔드 템플릿 `clean-architecture-backend-template` 안에서 만들었다(`src/messaging/` → 2026-11-07부터 `src/platforms/messaging/`). - 2026-11-08: `git filter-repo`로 그 경로들과 `docs/messaging/`, 설계서, `messaging-certification.yml`, 저장소 계약 테스트 `MessagingPublicSurfaceContractTest`의 이력을 이 repo로 옮겼다(템플릿 main `2959eff0` 기준). 옮긴 모듈 폴더의 트리 해시는 템플릿 기준 커밋과 같다. - filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(`MSG-…`, `RR-…`, `S7-#9c` 등)는 **템플릿 repo** 기준이다. 그 리뷰 문서는 템플릿 `docs/reviews/`에 남아 있다. - 설계와 결정: design-docs `repo-structure/05-library-repos.md`(소유자 승인 2026-11-07, 이름 변경 2026-11-08).