133 lines
8.4 KiB
Markdown
133 lines
8.4 KiB
Markdown
# 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는 그 실행의 출력이다:
|
|
|
|
```bash
|
|
./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에서 읽어 파생한다.
|
|
|
|
```bash
|
|
cd src
|
|
./gradlew <gradle-path>:test --console=plain
|
|
```
|
|
|
|
Family 전체 검증:
|
|
|
|
```bash
|
|
./gradlew verifyCleanArchitectureDependencies --console=plain
|
|
./gradlew verifyDocumentedLeafCount --console=plain
|
|
./gradlew verifyDependencyLocks --console=plain
|
|
```
|