diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md index 1a2e72c..d0325b2 100644 --- a/docs/messaging/support-matrix.md +++ b/docs/messaging/support-matrix.md @@ -27,7 +27,7 @@ > `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만 > `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter / > auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와 -> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다. +> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다. ## 브로커 등급 diff --git a/messaging/AGENTS.md b/messaging/AGENTS.md new file mode 100644 index 0000000..9c68440 --- /dev/null +++ b/messaging/AGENTS.md @@ -0,0 +1,176 @@ +# messaging — 메시징 플랫폼 family의 지역 정본 + +이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 +`src/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 모듈 리뷰 뒤 소유자가 정한 배치), `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의 `api` closure에 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`가 현재 +상태를 기록한다): + +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는 그 실행의 출력이다: + +```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 :test --console=plain +``` + +Family 전체 검증: + +```bash +./gradlew verifyCleanArchitectureDependencies --console=plain +./gradlew architectureCheck --console=plain +./gradlew verifyDependencyLocks --console=plain +``` diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index 807a589..43c994c 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -1,176 +1 @@ -# 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의 `api` closure에 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`가 현재 -상태를 기록한다): - -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는 그 실행의 출력이다: - -```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 :test --console=plain -``` - -Family 전체 검증: - -```bash -./gradlew verifyCleanArchitectureDependencies --console=plain -./gradlew architectureCheck --console=plain -./gradlew verifyDependencyLocks --console=plain -``` +@AGENTS.md diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java index 22527fd..c42097b 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java @@ -34,7 +34,7 @@ import org.junit.jupiter.api.Test; * *

So the rule is one-directional and mechanical: a vendor library named in a public or protected * signature is declared {@code api}; one used only behind private members stays {@code - * implementation}. {@code src/platforms/messaging/CLAUDE.md} states it as policy — this holds it to + * implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to * the source so the two cannot drift. * *

The libraries checked are the ones an adopter would otherwise have to reverse-engineer into