Merge branch 'refactor/review-followup': 리뷰 후속 Wave 1–3(보안·정합성·구조)

2026-09-24 리뷰 두 건의 후속 반영. Wave 1(보안·데이터), Wave 2(정합성), Wave 2.5, Wave 3(구조) 완료.
현황표 docs/reviews/2026-09-25-review-followup-status.md: 완료 606 · 해당 없음 133 · 보류 5 · 남음 173(W4 테스트 규칙 63 · W5 문서 110).
Wave 3 종료 검증 전부 통과(check · ci · mainCheck · integrationCheck · build-logic · optional-platforms · releaseCheck).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 17:02:03 +09:00
co-authored by Claude Opus 5.5
336 changed files with 6462 additions and 14583 deletions
+50 -50
View File
@@ -21,20 +21,16 @@ Application의 canonical integration event를 platform publish pipeline으로
producing-service identity다.
값이 없으면 `IntegrationEventPublishPort` bridge 자체를 만들지 않는다. `spring.application.name`이나
현재 process 이름으로 추론하지 않는다. 기존 legacy `OutboxEvent`/realtime 경로는 별도 cutover가
끝날 때까지 `app.messaging.broker` 경로를 유지한다.
현재 process 이름으로 추론하지 않는다. 모든 발행(outbox relay 포함)이 이 bridge를 지나므로 messaging
모듈이 켜진 상태에서 값이 없으면 기동이 거부된다.
## Outbox canonical transport-only cutover
## Outbox
`APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED` / `ca-skeleton.outbox.canonical-transport-enabled`은
기존 `outbox_event` writer/claim/status authority를 유지한 채 canonical row의 **transport만** platform
publish path로 보내는 compatibility gate다. 기본값은 `false`이며 `POLLING_V2`를 활성화하지 않는다.
`true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다.
legacy row는 계속 `MessageBroker`를 사용한다. 따라서 mixed-row compatibility 기간에는 relay가 켜져
있다면 `app.messaging.broker`도 계속 필요하며, canonical path를 위해 `IntegrationEventPublishPort`도
추가로 필요하다. legacy backlog가 0이라는 별도 증거 없이 broker 요구를 제거하지 않는다.
outbox는 canonical 하나다(2026-09-28). use case가 `IntegrationEventEncoderPort`로 만든
`ValidatedIntegrationEvent`를 `OutboxAppendPort`로 append하고, relay는 claim한 row의 exact envelope
bytes를 `IntegrationEventPublishPort`로 보낸다. 예전의 `app.outbox.canonical-transport-enabled`
gate와 legacy `MessageBroker → KafkaSender` 경로는 삭제됐다. 발행할 contract의 logical destination마다
아래 destination profile을 선언한다(템플릿의 durable operation event는 `durable-operations`).
## Destination profile
@@ -135,9 +131,10 @@ app:
## Broker profile
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`이 어느 계열의 설정이 적용되는지
결정하며, 다른 계열의 키(Kafka 항목의 `prefetch` 같은)는 무시되지 않고 부팅 실패로 거절된다 —
무시하면 그 줄을 쓴 사람은 무언가가 적용됐다고 믿게 된다.
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가
있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와
`type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라,
지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.
### Kafka
@@ -160,32 +157,17 @@ app:
authentication-enabled: false # production이면 필수
```
### RabbitMQ
```yaml
app:
messaging:
brokers:
rabbit-primary:
type: rabbitmq
stable: true
production: false
addresses: [rabbit-1:5671]
publisher-confirms: true # stable에서 필수
publisher-returns: true # stable에서 필수
mandatory: true # stable에서 필수
confirm-timeout: 5s
auto-ack: false # 항상 금지
prefetch: 16
quorum-queues: true # durable work queue 필수
tls-enabled: false
authentication-enabled: false
```
`production: true`인 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
그렇지 않으면 `KafkaProfileValidator` / `RabbitProfileValidator`가 부팅을 거절한다. 위 예시가
`production: true`인 Kafka 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
그렇지 않으면 `KafkaProfileValidator`가 부팅을 거절한다. `app.messaging.broker`로 고를 수 있는 값은
`kafka`뿐이다. 위 예시가
`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.
Kafka producer는 이 항목 하나로 만든다. `bootstrap-servers`, `acks`, `enable-idempotence`,
`max-in-flight-requests-per-connection`, `delivery-timeout`이 그대로 client 설정이 된다.
`spring.kafka.bootstrap-servers`는 읽지 않는다. type이 `kafka`인 항목이 정확히 하나가 아니면 기동에
실패한다. `send()`가 metadata를 기다리며 호출 스레드를 막는 시간(`max.block.ms`)은 기본 publish
timeout(5s)이다.
## 보안
```yaml
@@ -197,6 +179,8 @@ app:
consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
# admin은 application runtime에 설정하지 않는다
hostname-verification: true
# 사설 CA로 서명된 TLS 브로커면(tls-enabled: true일 때만):
# trust-store: { location: /etc/kafka/ca.p12, type: PKCS12, password-credential-id: kafka-truststore }
access:
publishable: [order-events]
consumable: []
@@ -211,21 +195,37 @@ app:
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
## Experimental / Optional
`SASL_SCRAM`·`USERNAME_PASSWORD`의 사용자 이름은 `CredentialProvider.username(credentialId)`가
준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지
않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은
재기동 없이 rotation된다(`security.md`).
기본값은 전부 `false`다.
`MUTUAL_TLS`는 클라이언트 인증서를 key store로 제출한다. `credential-id`는 key store 비밀번호를
가리킨다.
```yaml
app:
messaging:
experimental:
kafka-share: false
pulsar: false
nats: false
bridge:
spring-cloud-stream: false
```text
producer:
type: MUTUAL_TLS
credential-id: kafka-producer-tls # key store 비밀번호
key-store: { location: /etc/kafka/producer.p12, type: PKCS12 }
```
`trust-store`를 생략하면 JVM 기본 trust store를 쓴다. 사설 CA 브로커는 `trust-store.location`
(PKCS12·JKS·PEM)과, 잠긴 store면 `password-credential-id`를 준다.
Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
`sasl.jaas.config`, `sasl.client.callback.handler.class`, `ssl.truststore.*`, `ssl.keystore.*`,
`ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로 조용히 넘어가지
않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나 `authentication-enabled`를 켰는데
`app.messaging.security.<broker>`가 없을 때, security 항목은 있는데 `CredentialProvider` bean이 없을
때, 같은 브로커에 맞는 항목이 둘 이상일 때, provider가 SASL 사용자 이름을 주지 않을 때,
`MUTUAL_TLS`인데 `key-store`가 없거나 `tls-enabled`가 꺼져 있을 때, `trust-store`를 줬는데
`tls-enabled`가 꺼져 있을 때, store 파일을 열 수 없을 때.
`access.publishable`은 강제된다. security 항목이 있는 브로커의 destination은 이 목록에 있어야
publish된다. 목록 밖 publish는 `REJECTED`(`PUBLISH_FORBIDDEN`)이고, 빈 목록이면 아무것도 publish되지
않는다.
## Backpressure
```yaml
+3 -2
View File
@@ -27,8 +27,9 @@
`PublishResult` → `OutboxPublishOutcome`. registry에 leaf를 추가하는 변경이라 별도 커밋.
- golden contract 테스트: event/message ID, type, schema revision, partition/order/correlation/
causation/tenant/trace, payload digest, wire version이 bytes 단위로 보존되는지.
- 단일 publication authority: 기존 `OutboxPublicationAuthority` fence를 재사용해 writer/relay가
동시에 ACTIVE가 되지 않도록. **dual write/publish는 금지** — 한 business fact가 두 durable store와
- 단일 publication authority: writer/relay가 동시에 ACTIVE가 되지 않도록 하는 fence. 이 용도로 쓰려던
outbox V2의 `OutboxPublicationAuthority`는 한 번도 조립되지 않은 채 2026-09-25에 삭제됐으므로
(`docs/capability-status.md` "제거된 코드") cutover가 자기 fence를 새로 가져야 한다. **dual write/publish는 금지** — 한 business fact가 두 durable store와
두 relay로 나가는 상태가 cutover에서 가장 위험하다.
- 첫 cutover 범위는 **transport만** 교체(저장소는 기존 유지). storage migration은 shadow read →
authority switch → old backlog drain 순서로 별도 release.
+9 -48
View File
@@ -17,24 +17,22 @@ stopsAcceptingNewWorkDuringShutdown
**Experimental**은 아직 그 증명이 끝나지 않은 어댑터다.
현재 Experimental 어댑터는 없다. Kafka Share Group·Pulsar·NATS JetStream(Experimental), RabbitMQ,
Spring Cloud Stream bridge(Optional)는 SDK 없는 seam이거나 선택할 수 없는 상태여서 2026-09-25에
삭제했다(`docs/capability-status.md` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다.
## 규칙
### 1. 기본 비활성
```yaml
messaging.experimental.kafka-share: false
messaging.experimental.pulsar: false
messaging.experimental.nats: false
```
새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 `false`다.
활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다.
Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다.
### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다
Gradle 의존 그래프로 강제된다. `messaging-spring-boot-starter`의 `allowed_dependencies`에
`messaging-kafka-share-experimental`, `messaging-pulsar-experimental`,
`messaging-nats-experimental`, `messaging-spring-cloud-stream-bridge`가 **없다**.
Gradle 의존 그래프로 강제된다. Experimental leaf는 `messaging-spring-boot-starter`의
`allowed_dependencies`에 넣지 않는다.
`verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다.
@@ -45,45 +43,8 @@ Experimental 어댑터는 브로커의 차이를 `MessagingCapabilities`로 표
### 4. 없는 기능을 광고하지 않는다
| 어댑터 | 광고하지 않는 것 | 이유 |
|---|---|---|
| Kafka Share Group | orderedStream, keyedOrdering, replay, brokerTransaction | 경쟁 소비자 + 개별 ack는 partition 순서를 유지할 수 없다 |
| Pulsar | brokerTransaction | Pulsar에 있지만 플랫폼 Contract Suite로 증명되지 않았다 |
| Pulsar (Shared) | keyedOrdering | round-robin 분배 |
| NATS JetStream | nativeDeadLetter | delivery limit 초과 시 terminate할 뿐 라우팅하지 않는다 |
| NATS JetStream | keyedOrdering | subject 기반 모델에 per-key 순서가 없다 |
`false`인 capability를 요구하는 profile은 startup에서 실패한다.
조용히 약화되지 않는다.
### 5. 명시적 거부
| 조합 | 결과 |
|---|---|
| Kafka Share Group + ordering != NONE | 거부 |
| Kafka Share Group + pause/resume | `MessagingCapabilityUnavailableException` |
| Pulsar Shared + ordering=KEY | 거부 (Key_Shared 필요) |
| Pulsar + ordering=DESTINATION | 거부 |
| NATS Core + AT_LEAST_ONCE | 거부 (JetStream 필요) |
| NATS ordered consumer + 경쟁 워커 > 1 | 거부 |
| NATS + ordering=KEY | 거부 |
## Spring Cloud Stream bridge
Experimental이 아니라 **Optional**이다. 위험이 다르다.
Stream은 자체 binder 설정을 소유하므로, binding이 destination profile이 모르는
serializer·error handling·acknowledgement mode를 조용히 획득할 수 있다.
따라서 브리지는 **플랫폼 보장에 의존하지 않는 destination에만** 허용한다.
```text
ordering scope 선언 → 거부
retry policy 선언 → 거부
dead letter 선언 → 거부
```
이 셋 중 하나라도 필요하면 native adapter를 쓴다. 거기서만 실제로 강제되기 때문이다.
Contract Suite로 증명하지 않은 capability는 `MessagingCapabilities`에서 `false`로 둔다.
`false`인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다.
## 승격 조건
+1 -2
View File
@@ -3,8 +3,7 @@
## 배포 전 체크
```bash
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew verifyRuntimeModuleMembership --console=plain
./gradlew architectureCheck --console=plain
./gradlew checkstyleMain --console=plain
```
+40 -8
View File
@@ -21,8 +21,8 @@ Flyway version `1000..1999`를 예약해서 애플리케이션의 일반적인
classpath:db/migration/messaging
```
현재 순서는 `V1001..V1004`(outbox/admin)와 `V1101`(inbox)이다. starter 테스트가 두 JDBC
모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
현재 순서는 `V1001..V1005`(outbox/admin)와 `V1101`(inbox)이고, 모두
`messaging-reliability-jdbc-postgresql`에 있다. starter 테스트가 그 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
의미와 전환 순서는 [migration-guide.md](migration-guide.md)를 따른다.
## Outbox
@@ -39,13 +39,18 @@ COMMIT;
### relay
```text
leaseBatch(100, 30s) -- lease로 다중 relay 인스턴스 안전
claimBatch(owner, 100, 30s, now, maxAttempts) -- owner + fencing token으로 다중 relay 인스턴스 안전
→ publish (messageId 그대로)
→ CONFIRMED → markPublished
→ AMBIGUOUS → markAmbiguous (같은 messageId로 재시도 가능)
→ REJECTED → markFailed
```
row 하나의 실패는 그 row에서 끝난다. envelope로 만들 수 없는 row(예약 header `msg.*`를 담은 row
등)는 `FAILED`가 되고, publisher가 예외를 던지면 결과를 모르므로 `AMBIGUOUS`가 된다. 같은 batch의
나머지 row는 그대로 publish된다. pass 전체가 실패하면(DB 연결 등) WARN 로그를 남기고
`messaging.outbox.relay.failed.passes` 카운터를 올린다.
### 핵심 규칙: ambiguous는 같은 messageId로 재시도
새 id를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어
@@ -61,8 +66,16 @@ status IN ('PENDING','AMBIGUOUS','IN_FLIGHT')
AND (lease_expires_at IS NULL OR lease_expires_at <= now)
AND next_attempt_at <= now
AND attempts < maxAttempts
AND (ordering_key IS NULL
OR 같은 destination·ordering_key의 더 오래된 미완료 row가 없음)
```
`ordering_key`가 있는 row는 같은 key의 더 오래된 row가 `PENDING`·`AMBIGUOUS`·`IN_FLIGHT`인 동안
claim되지 않는다. 이 조건이 없으면 두 relay가 같은 key의 두 row를 나눠 가져가거나, AMBIGUOUS로
재시도되는 row보다 뒤의 row가 먼저 나간다(`OutboxPostgresIT#aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`).
`V1005`의 partial index가 이 확인을 받친다. 더 오래된 row가 `FAILED`·`EXHAUSTED`가 되면 뒤의 row는
진행한다.
`IN_FLIGHT`가 목록에 있는 것이 핵심이다. relay가 publish 도중 죽으면 row는 `IN_FLIGHT`로 남는데,
이를 제외하면 그 메시지는 **영원히** 발행되지 않는다 — outbox가 막으려던 바로 그 실패다. 대신
lease가 만료됐을 때만 회수하므로, 살아 있는 relay가 들고 있는 row는 회수되지 않는다.
@@ -95,6 +108,24 @@ transactions.inTransaction(() -> {
별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다.
### 소비와 연결 (소유자 결정 10)
consume 계약은 `MessageHandler<T>` 하나다. handler를 bean으로 등록하면 `messaging-spring-boot-starter-kafka`가
그 handler가 가리키는 destination마다 Kafka consumer를 연다(`app.messaging.enabled=false`면 없다).
- destination profile이 `guarantees.external-side-effect: INBOX_TRANSACTIONAL`이면 platform이 handler를
`InboxMessageHandler`로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된
message는 handler를 부르지 않고 `Success`로 settle한다. 이 경우 애플리케이션이 `IdempotentConsumer`
bean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다.
- inbox의 consumer 식별자와 Kafka `group.id`는 destination의 `consumer.group`이다. 없으면 기동이 실패한다.
- offset은 handler가 `Success`로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는
DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다.
- `Retry`·예외·timeout은 `retry.max-attempts`까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에
원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다.
- `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다.
실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다.
### 복합 키
`PRIMARY KEY (message_id, consumer_id)`.
@@ -107,13 +138,14 @@ message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째
broker의 최대 redelivery window보다 **길어야** 한다.
row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
## Debezium CDC 대안
outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다.
repository port에는 개수 제한 없는 삭제 메서드가 없다.
polling relay 대신 WAL을 읽는다. polling interval과 lease 경합이 사라지지만
인프라와 그 자체의 실패 모드가 추가된다.
## CDC 대안
wire contract는 동일하다. `DebeziumOutboxEventRouter`가 polling relay와 같은 reserved header를
방출하므로 consumer는 어느 쪽이 발행했는지 구분할 수 없고, 전환은 배포 결정일 뿐 계약 변경이 아니다.
relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는
곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의
`routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
## Claim Check
+9
View File
@@ -49,6 +49,15 @@ full jitter는 `[0, delay]` 균등 분포다. jitter가 없으면 같은 초에
pause-and-seek는 메시지가 로그의 자기 자리를 떠나지 않는다. partition을 멈추고, 기다리고,
같은 offset으로 seek해 재전달한다. 뒤의 메시지도 함께 기다리며 이것이 의도된 동작이다.
`KafkaConsumerRegistrar`가 handler 실패(예외, settle 없이 끝남, timeout)를 다루는 방식:
- 재전달은 destination `retry`의 backoff 뒤에 한다. 최소 1초. 0초 재시도는 없다.
- 같은 offset의 실패 횟수가 `retry.maxAttempts`에 닿으면 `KafkaQuarantinePublisher`에 쓰고,
쓰기가 확인되면 offset을 넘긴다. quarantine이 없으면 backoff로 계속 재시도한다(메시지를 버리지
않는다). 그래서 `production` destination은 quarantine 없이 만들 수 없다(`KAFKA_QUARANTINE_REQUIRED`).
- handler timeout이 지나도 handler가 끝날 때까지 partition slot을 잡고 있는다. `CompletableFuture`를
cancel해도 handler는 멈추지 않으므로, slot을 먼저 풀면 같은 offset이 두 번 동시에 돈다.
## RabbitMQ: delayed retry queue
core broker에 per-message delay가 없으므로 **TTL + DLX**로 구현한다.
+22 -6
View File
@@ -36,17 +36,30 @@ heap dump나 설정 출력에서 사용 가능한 credential이 나오지 않는
`CredentialIds`는 `bearer `, `sk-`, `-----begin`, `eyJ` 같은 접두사를 거부한다.
참조가 들어갈 자리에 secret 자체를 붙여넣는 가장 흔한 사고를 막는다.
SASL(PLAIN·SCRAM) 사용자 이름도 `CredentialProvider.username(credentialId)`가 준다. credential id는
저장소 안의 참조이지 broker가 아는 사용자 이름이 아니다. provider가 이름을 주지 않으면 기동에
실패한다.
key store·trust store는 경로만 설정에 둔다. 비밀번호는 credential id로 provider가 해석한다
(`configuration-reference.md` 보안 절).
## Rotation
`CredentialRotationPlan.isDue()`는 만료 **전에** 참이 된다.
broker가 연결을 거부하기 시작한 시점에는 이미 publish가 실패하고 consumer가 멈춰 있다.
rotation은 세대 교체다. `DefaultMessagingRuntimeRegistry.install()`이 새 세대를 원자적으로
게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
진행 중인 publish는 시작한 연결에서 confirm을 받는다.
Kafka SASL credential은 producer를 다시 만들지 않고 바뀐다. JAAS 설정에는 login module 이름만
있고, `KafkaCredentialCallbackHandler`가 연결이 인증할 때마다 `CredentialRuntimeRegistry`에서
사용자 이름과 비밀번호를 읽는다. registry는 provider가 준 만료 시각의 rotation lead(기본 30분)
안으로 들어오면 새로 가져오므로, 새 연결과 재인증(broker `connections.max.reauth.ms`)이 새 값을
쓴다. 만료 시각을 주지 않는 provider의 credential은 캐시된 값을 계속 쓴다.
drain deadline이 이 대기를 제한한다. 없으면 lease 하나가 새면 폐기된 credential이
무기한 열려 있고, rotation이 보안상 무의미해진다.
key store·trust store 비밀번호는 예외다. Kafka가 SSL context를 만들 때 한 번 읽으므로 바꾸려면
producer를 다시 만들어야 한다(재기동).
transport 세대 교체(`DefaultMessagingRuntimeRegistry.install()`)는 transport 자체를 바꿀 때 쓴다.
새 세대를 원자적으로 게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
drain deadline이 이 대기를 제한한다.
## Header
@@ -66,10 +79,13 @@ logical identity가 호출자 제어가 된다.
## ACL
`DestinationAccessValidator`가 broker ACL **이전에** 검사한다.
publisher가 broker ACL **이전에** 검사한다(`PUBLISH_FORBIDDEN`).
broker ACL 거부는 애플리케이션 컨텍스트가 없는 연결 수준 오류로 도착하므로
"어느 모듈이 어디에 publish하려 했는가"가 조사 대상이 된다.
publish 가능한 destination은 선언된 destination이다. broker에 `app.messaging.security.<broker>`
항목이 있으면 그중 `access.publishable`에 적힌 것만 남는다(빈 목록이면 publish 불가).
## 관측성 누출
`MessagingRedactor`는 denylist다.
+29 -49
View File
@@ -4,10 +4,12 @@
여기 없는 조합은 지원되지 않는다.
> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. RabbitMQ가 Stable에서 내려온
> 이유가 이것이다 — 어댑터는 공유 contract 7개를 통과하고 `RabbitBrokerIT`가 실 컨테이너에서 정상
> 경로를 돌리지만, 이 저장소의 Stable 기준인 **장애 시나리오 증거**가 하나도 없다. 레인이 생겨
> 증거를 내면 등급은 코드 수정 없이 따라 올라간다.
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. 레인이 생겨 증거를 내면 등급은
> 코드 수정 없이 따라 올라간다.
> **삭제된 어댑터.** RabbitMQ(선택할 수 없던 validator·설정 모음), Pulsar·NATS JetStream·Kafka Share
> Group(Experimental, SDK 없는 seam), Spring Cloud Stream bridge, Debezium outbox 매핑은 2026-09-25에
> 삭제했다. 복구 경로는 `docs/capability-status.md`의 제거 표에 있다.
> **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다. 이전 판은
> Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와
@@ -15,8 +17,10 @@
> `BrokerFailureMatrix.shipped()` 하드코딩이 아니라 레인이 낸 증거(`BrokerCertificationEvidence`)에서
> 나온다. 증거가 없는 조합은 `NOT_COVERED`다 (MSG-014).
> **모듈 이름과 런타임 편입.** `messaging-outbox-jdbc-postgresql` / `messaging-inbox-jdbc-postgresql`은
> 이전에 `-jpa`로 불렸다. 구현은 Spring JDBC이고 SQL은 PostgreSQL 전용(`?::jsonb`,
> **모듈 이름과 런타임 편입.** 관계형 신뢰성 구현은 `messaging-reliability-jdbc-postgresql`,
> 그 port만 보는 relay·consumer 로직은 `messaging-reliability`다(2026-09-28에
> `messaging-outbox-jdbc-postgresql` / `messaging-inbox-jdbc-postgresql`을 이렇게 나눴다). 그 전에는
> `-jpa`로 불렸다. 구현은 Spring JDBC이고 SQL은 PostgreSQL 전용(`jsonb`,
> `FOR UPDATE SKIP LOCKED`, `ON CONFLICT`, `TIMESTAMPTZ`)이므로, 그 이름은 쓰지 않는 기술을
> 광고하고 vendor 중립 port(`messaging-reliability-api`)의 위치를 가렸다 (MSG-023).
>
@@ -29,10 +33,7 @@
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|---|---|---|---|---|
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental |
| RabbitMQ | Experimental | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | **현재 starter에서 선택 불가** — production `RabbitChannelPublisher`/transport bridge가 없어 `app.messaging.broker=rabbit`은 startup에서 거부된다. 장애 시나리오 증거도 아직 없음 |
| Pulsar | Experimental | 4.0 LTS + 4.2 | typed publish/consume, Shared, Key_Shared, schema | transaction 미승격, 기본 비활성 |
| NATS JetStream | Experimental | 2.14.x | stream, durable consumer, explicit ACK, dedupe, replay | native DLQ 없음(플랫폼이 대행), 기본 비활성 |
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group 미지원 |
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
## Capability 매트릭스
@@ -40,27 +41,20 @@
`MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은
**startup에서 실패**하며, 조용히 약화되지 않는다.
| Capability | Kafka | Kafka Share | RabbitMQ | Pulsar | NATS JS |
|---|---|---|---|---|---|
| brokerAcknowledgement | O | O | O | O | O |
| replicationOrPersistenceEvidence | O | O | O | O | O |
| perMessageSettlement | O | O | O | O | O |
| batchSettlement | O | X | X | O | O |
| orderedStream | O | **X** | X | X | O |
| keyedOrdering | O | **X** | X | Key_Shared만 | X |
| replay | O | X | X | O | O |
| delayedDelivery | X | X | retry queue로 대행 | O | X |
| brokerTransaction | O | X | X | 미승격 | X |
| deduplicatedPublish | O | X | X | X | O |
| nativeDeadLetter | X | X | O | O | **X** |
| topologyManagement | O | X | O | O | O |
Kafka Share Group이 ordering 전부 `X`인 것은 설계 결정이다. share group은 개별 record를
경쟁 소비자에게 나눠주고 개별 ack하므로 partition 순서를 유지할 수 없다. ordered destination을
share group에 설정하면 `KafkaShareProfileValidator`가 거부한다.
NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery limit 초과 시 메시지를
**terminate**할 뿐 어디로도 라우팅하지 않으므로, 플랫폼이 DLQ publish를 직접 수행한다.
| Capability | Kafka |
|---|---|
| brokerAcknowledgement | O |
| replicationOrPersistenceEvidence | O |
| perMessageSettlement | O |
| batchSettlement | O |
| orderedStream | O |
| keyedOrdering | O |
| replay | O |
| delayedDelivery | X |
| brokerTransaction | O |
| deduplicatedPublish | O |
| nativeDeadLetter | X |
| topologyManagement | O |
## 기능 등급
@@ -73,8 +67,6 @@ NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery
| Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 |
| Broker transaction / partition / routing / subscription | M3 |
| Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin |
| Kafka Share Group, Pulsar, NATS | Experimental |
| Spring Cloud Stream bridge | Optional |
## 무엇이 "Stable"을 증명하는가
@@ -82,7 +74,7 @@ Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMat
### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개)
Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다.
### 2. 실 브로커 인증 (Testcontainers)
@@ -92,7 +84,6 @@ Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) |
| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 |
| `RabbitBrokerIT` | exchange가 confirm했는데 어떤 큐에도 바인딩되지 않은 publish가 **`REJECTED` + `UNROUTABLE`** 로 보고된다 |
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
@@ -137,7 +128,7 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서,
publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다.
2. **Rabbit confirm 경합** — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
2. **Rabbit confirm 경합**(2026-09-25에 삭제된 Rabbit transport) — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다.
둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다.
@@ -154,21 +145,10 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
- DLQ publish 확인 전 source ACK
## R1 compiler status
`adapter:outbound:messaging`의 contract/catalog/envelope compiler 군은 현재 **의도적으로 미배선**이다.
`DISABLED` + 빈 catalog/binding이 zero-resource 상태이며, 이 R1 compiler를 legacy
`MessagingConfig`에 연결해 Kafka ACK, wire compatibility, `ACTIVE_READY`, R2 qualification을
주장하지 않는다. 코드는 다음 세대 계약을 보존하지만 현재 채택 경로가 아니며, 실제 활성화는 별도 R2
composition/cutover에서 명시적으로 이뤄져야 한다.
### Optional mapping / bridge utilities
### Optional mapping utilities
- `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다.
내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured
CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를
인증하지 않는다.
- `messaging-spring-cloud-stream-bridge`는 현재 `ChannelSend` seam과 publish-evidence 판단을 제공하는
framework-neutral bridge contract다. Spring Cloud Stream `StreamBridge` dependency/auto-configuration은
제공하지 않으므로 shipped Spring Cloud Stream integration으로 분류하지 않는다.
- `messaging-claim-check`도 starter에 편입되지 않는 opt-in utility다.
+36 -31
View File
@@ -14,25 +14,28 @@ 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 금지 |
| `*-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-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. 여기서만 |
| `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가 의존하지 않는다 |
`outbox`/`inbox` leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring JDBC이고 SQL은
`?::jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL 전용이다.
`jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. vendor
중립 계약은 `messaging-reliability-api`에 있다.
신뢰성 기능은 세 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도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
## Public surface 정책
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `spring-rabbit`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.)
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
`implementation`으로 둔 것이 그 예다.
@@ -45,16 +48,19 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
## Application runtime에 포함되는 기준
Messaging family는 기본 application이 `messaging-spring-boot-starter`를 dependency로 가지므로 그
transitive project graph가 runtime에 포함된다. 이 사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에
동일한 membership 목록을 복제하지 않는다. `app.messaging.enabled=false`가 기본값이고 master switch가
activation을 결정한다.
기본 조립에는 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`로만 끈다.
experimental transport, 일부 codec/bridge/testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
일부 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에 도달하는 경로 (MSG-015, canonical bridge 구현 / legacy cutover 잔존)
## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료)
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
@@ -66,25 +72,24 @@ qualification/support 상태를 함께 변경한다.
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
package는 `messaging-core-api`와 `messaging-schema-api`만 보며 concrete runtime/transport/Kafka 타입을
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
다만 **MSG-015의 전체 cutover가 끝난 것은 아니다.** legacy `OutboxEvent`와 realtime publisher는
schema/order/tenant 등 canonical metadata가 부족해 아직 `MessageBroker → KafkaSender` R0 경로를
사용한다. 그 metadata를 추측해 platform envelope를 만드는 것은 금지한다. 따라서 legacy outbox
storage/relay migration을 별도 change set으로 완료한 뒤에만 R0 seam을 제거한다.
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** 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를 발명하지 않는다.
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
`ca-skeleton.outbox.canonical-transport-enabled=true`는 bridge 존재만으로 충분하지 않다. Stable
composition은 애플리케이션 계약 catalog/schema source를 임의로 만들지 않으므로 adopter가
`IntegrationEventEncoderPort`를 명시적으로 제공해야 한다. 저장소의 후보 구현은
`JsonSchemaIntegrationEventEncoder`이지만 이를 사용하려면 compiled contract descriptor,
`LocalJsonSchemaRegistry`, payload/envelope limits와 key material에 해당하는 application-owned 입력을
같이 조립해야 한다. `OutboxCanonicalTransportRequirementValidator`는 publisher 또는 encoder 중 하나라도
없으면 startup을 거부한다. 즉 canonical flag가 켜졌는데 정본 encoder가 없는 상태로 성공 기동하는
경로는 없다.
`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 승격에 필요한 증거
@@ -1,8 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-policy')
}
@@ -1,84 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-admin-api')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-security')
api project(':messaging:messaging-observability')
}
+14
View File
@@ -0,0 +1,14 @@
plugins {
id 'ca.platform-module'
}
// The admin plane: its contract (package `admin`) and the stdlib services that execute it
// (package `admin.runtime`). They were two leaves, and every consumer of the runtime took the
// contract too, so the split added a registry entry without separating anything (S7-#12).
dependencies {
api project(':messaging:messaging-core-api')
// ReplayService records a MessagingAuditEvent internally; no public signature names it, so
// Micrometer does not reach the journal adapters that implement the contract.
implementation project(':messaging:messaging-observability')
}
@@ -4,7 +4,6 @@ plugins {
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
// api, because CloudEventMapper's public signatures return io.cloudevents.CloudEvent.
//
@@ -1,46 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
/**
* Batch-wide facts about one delivered batch.
*
* <p>{@code orderingUnit} is what makes a batch safe to hand to an ordered destination. A batch
* drawn from two partitions cannot be settled or retried as a unit without reordering one of them,
* so an ordered destination requires the batch to name exactly one ordering unit and the runtime
* rejects a batch that spans more.
*
* @param destination the logical destination
* @param size the number of deliveries in the batch
* @param orderingUnit the single partition or queue the batch was drawn from, when it has one
* @param settlableAsBatch whether the broker can settle the whole batch in one operation
* @param receivedAt when the consumer assembled the batch
*/
public record BatchDeliveryMetadata(
DestinationName destination,
int size,
Optional<String> orderingUnit,
boolean settlableAsBatch,
Instant receivedAt) {
public BatchDeliveryMetadata {
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(orderingUnit, "orderingUnit must not be null");
Objects.requireNonNull(receivedAt, "receivedAt must not be null");
if (size < 1) {
throw new IllegalArgumentException("a delivered batch has at least one delivery");
}
}
/**
* Reports whether this batch may be handed to a destination with strict ordering.
*
* @return true when the batch came from exactly one ordering unit
*/
public boolean isSafeForOrderedDestination() {
return orderingUnit.isPresent();
}
}
@@ -1,29 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import java.util.List;
import java.util.Objects;
/**
* A batch of decoded messages handed to a batch handler.
*
* @param <T> the payload type
* @param deliveries the individual deliveries, in broker order
* @param metadata batch-wide facts
*/
public record BatchMessageDelivery<T>(
List<MessageDelivery<T>> deliveries, BatchDeliveryMetadata metadata) {
public BatchMessageDelivery {
Objects.requireNonNull(deliveries, "deliveries must not be null");
Objects.requireNonNull(metadata, "metadata must not be null");
deliveries = List.copyOf(deliveries);
if (deliveries.isEmpty()) {
throw new IllegalArgumentException("a delivered batch is never empty");
}
if (deliveries.size() != metadata.size()) {
throw new IllegalArgumentException(
"metadata size %d does not match %d deliveries"
.formatted(metadata.size(), deliveries.size()));
}
}
}
@@ -1,24 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import java.util.concurrent.CompletionStage;
/**
* The M2 batch consume entry point.
*
* <p>The handler returns one {@link HandleResult} for the whole batch. On a broker that settles
* batches atomically the runtime applies that result once; on a broker that settles per message it
* applies the same result to each delivery. Either way the handler is not asked to reason about
* which settlement mode it is running under.
*
* @param <T> the payload type
*/
public interface BatchMessageHandler<T> {
/**
* Handles one delivered batch.
*
* @param batch the batch to handle
* @return a stage completing with the outcome for the whole batch
*/
CompletionStage<HandleResult> handle(BatchMessageDelivery<T> batch);
}
@@ -1,18 +1,33 @@
package dev.caskeleton.messaging.api.delivery;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import java.util.concurrent.CompletionStage;
/**
* The M1 typed handler implemented by ordinary business code.
* The one consume contract, implemented by ordinary business code.
*
* <p>Handlers state an outcome and never touch broker acknowledgement APIs. Duplicate delivery is a
* normal condition, not an error: implementations are expected to be idempotent, or to sit behind
* the Inbox.
* normal condition, not an error: implementations are expected to be idempotent, or to consume a
* destination whose profile declares {@code INBOX_TRANSACTIONAL}, where the platform runs the
* handler inside the inbox reservation's transaction.
*
* <p>Registering an implementation as a bean is what turns consumption on: the broker starter opens
* a consumer for every destination at least one handler names. There is no second, batch or manual
* settlement contract; the platform settles, after the handler has answered.
*
* @param <T> the payload type
*/
public interface MessageHandler<T> {
/**
* The destination, message type and payload type this handler consumes.
*
* <p>A destination may carry several message types; each type has at most one handler.
*
* @return what this handler consumes
*/
MessageDestination<T> destination();
/**
* Handles one delivery.
*
@@ -1,33 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.util.concurrent.CompletionStage;
/**
* The M2 consumer flow-control entry point.
*
* <p>Pausing stops new deliveries; it does not abandon the ones already in flight. A paused
* consumer stays a member of its group and keeps its assignment, which is the point: leaving the
* group to stop consuming would trigger a rebalance and hand the work to another instance that is
* just as overloaded.
*/
public interface PauseResumeController {
/**
* Stops new deliveries for a destination scope.
*
* @param destination the logical destination
* @param scope the partition, queue, or {@code "*"} for every assigned unit
* @return a stage completing once no further deliveries will be dispatched
*/
CompletionStage<Void> pause(DestinationName destination, String scope);
/**
* Resumes deliveries for a destination scope.
*
* @param destination the logical destination
* @param scope the partition, queue, or {@code "*"} for every assigned unit
* @return a stage completing once deliveries may flow again
*/
CompletionStage<Void> resume(DestinationName destination, String scope);
}
@@ -1,11 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
/** How duplicate processing is neutralised once a message has been delivered. */
public enum ProcessingGuarantee {
/** The handler suppresses duplicate effects using the message id or a business key. */
APPLICATION_IDEMPOTENT,
/** Atomicity holds only inside the transaction scope the broker itself defines. */
BROKER_TRANSACTIONAL
}
@@ -1,15 +0,0 @@
package dev.caskeleton.messaging.api.destination;
/** Resolves the capability snapshot for a logical destination. */
public interface CapabilityRegistry {
/**
* Returns the capabilities of a destination.
*
* @param destination the logical destination
* @return the capability snapshot
* @throws dev.caskeleton.messaging.api.error.MessagingConfigurationException when the destination
* is not registered
*/
DestinationCapabilities capabilities(DestinationName destination);
}
@@ -1,5 +1,10 @@
package dev.caskeleton.messaging.api.destination;
import java.util.Collections;
import java.util.EnumSet;
import java.util.Objects;
import java.util.Set;
/**
* What a broker adapter can actually prove or do.
*
@@ -8,32 +13,35 @@ package dev.caskeleton.messaging.api.destination;
* capability exception — rather than quietly degrading, because a silently weakened guarantee is
* indistinguishable from a working one until the incident.
*
* @param brokerAcknowledgement the adapter can prove the broker accepted a publish
* @param replicationOrPersistenceEvidence the adapter can prove replication or persistence
* @param perMessageSettlement individual messages can be settled
* @param batchSettlement batches can be settled as a unit
* @param orderedStream the destination preserves order inside an ordering unit
* @param keyedOrdering order is preserved per key
* @param replay historical messages can be re-read
* @param delayedDelivery delivery can be scheduled for a future instant
* @param brokerTransaction the broker offers a transaction scope
* @param deduplicatedPublish the broker suppresses duplicate publishes of a stable id
* @param nativeDeadLetter the broker provides dead lettering itself
* @param topologyManagement topology can be inspected or created through the adapter
* <p>A set of named capabilities rather than a row of positional booleans. The record used to take
* twelve booleans in a fixed order, and an adapter declared itself with {@code new
* MessagingCapabilities(true, true, …, false, true)} — a line where swapping two arguments changes
* a guarantee and still compiles. Only the capabilities the platform reads are named: a flag
* nothing consults is a promise nobody checks.
*
* @param supported the capabilities the adapter can prove
*/
public record MessagingCapabilities(
boolean brokerAcknowledgement,
boolean replicationOrPersistenceEvidence,
boolean perMessageSettlement,
boolean batchSettlement,
boolean orderedStream,
boolean keyedOrdering,
boolean replay,
boolean delayedDelivery,
boolean brokerTransaction,
boolean deduplicatedPublish,
boolean nativeDeadLetter,
boolean topologyManagement) {
public record MessagingCapabilities(Set<Capability> supported) {
/** One capability the platform consults before relying on it. */
public enum Capability {
/** The destination preserves order inside an ordering unit; required by pause-and-retry. */
ORDERED_STREAM,
/** Delivery can be scheduled for a future instant; required by broker-delayed retry. */
DELAYED_DELIVERY,
/** The broker suppresses duplicate publishes of a stable id; required by publish dedup. */
DEDUPLICATED_PUBLISH
}
public MessagingCapabilities {
Objects.requireNonNull(supported, "supported must not be null");
supported =
Collections.unmodifiableSet(
supported.isEmpty() ? EnumSet.noneOf(Capability.class) : EnumSet.copyOf(supported));
}
/**
* Returns a capability set with nothing enabled.
@@ -41,7 +49,27 @@ public record MessagingCapabilities(
* @return the empty capability set
*/
public static MessagingCapabilities none() {
return new MessagingCapabilities(
false, false, false, false, false, false, false, false, false, false, false, false);
return new MessagingCapabilities(EnumSet.noneOf(Capability.class));
}
/**
* Returns a capability set holding exactly the named capabilities.
*
* @param first the first capability
* @param rest the remaining capabilities
* @return the capability set
*/
public static MessagingCapabilities of(Capability first, Capability... rest) {
return new MessagingCapabilities(EnumSet.of(first, rest));
}
/**
* Reports whether the adapter can prove a capability.
*
* @param capability the capability to look up
* @return true when it is supported
*/
public boolean supports(Capability capability) {
return supported.contains(Objects.requireNonNull(capability, "capability must not be null"));
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** Broker authentication failed. */
public class MessageAuthenticationException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.AUTHENTICATION;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageAuthenticationException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageAuthenticationException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageAuthenticationException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The broker could not be reached. */
public class MessageBrokerUnavailableException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageBrokerUnavailableException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageBrokerUnavailableException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageBrokerUnavailableException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The consumer runtime failed while handling a delivery. */
public class MessageConsumerException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PROCESSING_TRANSIENT;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageConsumerException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageConsumerException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageConsumerException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* Publishing to the dead letter destination failed.
*
* <p>The source message stays unsettled. Acknowledging a source whose DLQ publish failed would
* destroy the only remaining copy.
*/
public class MessageDeadLetterException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageDeadLetterException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageDeadLetterException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageDeadLetterException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* The handler exceeded its timeout.
*
* <p>Whether the handler committed a side effect before the deadline is unknown, so the delivery is
* recorded as possibly duplicated when it is retried.
*/
public class MessageHandlerTimeoutException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PROCESSING_TRANSIENT;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageHandlerTimeoutException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageHandlerTimeoutException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageHandlerTimeoutException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** A header was reserved, secret, or exceeded a limit. */
public class MessageHeaderRejectedException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageHeaderRejectedException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageHeaderRejectedException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageHeaderRejectedException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* The publish outcome could not be determined.
*
* <p>The broker may hold the message. Republishing is permitted only under the same logical message
* id, so that broker deduplication or a downstream Inbox can collapse the duplicate.
*/
public class MessagePublishAmbiguousException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessagePublishAmbiguousException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessagePublishAmbiguousException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessagePublishAmbiguousException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,53 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* The broker definitively refused the publish.
*
* <p>The message is known not to be stored, so abandoning this attempt is safe.
*/
public class MessagePublishRejectedException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessagePublishRejectedException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessagePublishRejectedException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessagePublishRejectedException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** A redrive operation failed. */
public class MessageRedriveException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageRedriveException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageRedriveException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageRedriveException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The retry policy's attempt budget was exhausted. */
public class MessageRetryExhaustedException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageRetryExhaustedException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageRetryExhaustedException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageRetryExhaustedException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The broker accepted the publish but could not route it. */
public class MessageRoutingException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageRoutingException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageRoutingException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageRoutingException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** Settlement was refused by the broker. */
public class MessageSettlementException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageSettlementException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageSettlementException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageSettlementException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,53 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* Settlement was sent but not confirmed.
*
* <p>Redelivery is possible. Callers must not treat this as a successful settlement.
*/
public class MessageSettlementUnknownException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageSettlementUnknownException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageSettlementUnknownException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageSettlementUnknownException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,25 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import java.util.List;
import java.util.concurrent.CompletionStage;
/**
* The M2 batch publish entry point.
*
* <p>A batch is a throughput optimisation, not a transaction. Entries succeed, fail, and go
* ambiguous independently, and {@link BatchPublishResult} keeps every entry's outcome against its
* submission index so the caller can act per entry. Nothing here rolls back: an adapter that
* reported a confirmed entry cannot un-publish it because a later entry was rejected.
*/
public interface BatchMessagePublisher {
/**
* Publishes a batch of independent requests.
*
* @param requests the entries to publish, in submission order
* @param options the batch-wide options
* @return a stage completing with one outcome per submitted entry
*/
CompletionStage<BatchPublishResult> publish(
List<PublishRequest<?>> requests, BatchPublishOptions options);
}
@@ -1,27 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.MessageId;
import java.util.Objects;
/**
* One item's outcome inside a batch publish.
*
* <p>Kept per index rather than collapsed into a batch-level success flag. A batch is not a
* transaction: some items confirm, some are rejected, and some are ambiguous, and the caller has to
* be able to act differently on each. A single boolean would force it to re-submit everything,
* which duplicates the items that already landed.
*
* @param index the item's position in the submitted list
* @param messageId the item's logical identity
* @param result the item's outcome and evidence
*/
public record BatchPublishItemResult(int index, MessageId messageId, PublishResult result) {
public BatchPublishItemResult {
Objects.requireNonNull(messageId, "messageId must not be null");
Objects.requireNonNull(result, "result must not be null");
if (index < 0) {
throw new IllegalArgumentException("index must not be negative");
}
}
}
@@ -1,42 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import java.time.Duration;
import java.util.Objects;
/**
* Options covering a whole batch publish.
*
* <p>There is no retry setting. A batch is not a transaction, and retrying the batch would resubmit
* entries that already confirmed, so the platform never retries one on the caller's behalf; the
* caller resubmits the individual entries it knows are duplicate-safe under their original {@code
* messageId}.
*
* @param timeout the deadline for the whole batch
* @param maxBatchSize the largest number of entries accepted in one call
* @param stopOnFirstRejection whether to skip remaining entries once one is rejected
*/
public record BatchPublishOptions(
Duration timeout, int maxBatchSize, boolean stopOnFirstRejection) {
private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(30);
private static final int DEFAULT_MAX_BATCH_SIZE = 500;
public BatchPublishOptions {
Objects.requireNonNull(timeout, "timeout must not be null");
if (timeout.isNegative() || timeout.isZero()) {
throw new IllegalArgumentException("batch timeout must be positive");
}
if (maxBatchSize < 1) {
throw new IllegalArgumentException("maxBatchSize must be at least 1");
}
}
/**
* Returns the defaults: thirty seconds, 500 entries, best-effort completion of every entry.
*
* @return the default options
*/
public static BatchPublishOptions defaults() {
return new BatchPublishOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_BATCH_SIZE, false);
}
}
@@ -1,44 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
/**
* The outcome of one batch publish.
*
* <p>There is no automatic batch retry. Re-submitting a whole batch because part of it failed
* duplicates the part that succeeded; the caller re-submits only the items it decides are
* duplicate-safe, under their original message ids.
*
* @param items each item's outcome, in submission order
* @param elapsed how long the batch took
*/
public record BatchPublishResult(List<BatchPublishItemResult> items, Duration elapsed) {
public BatchPublishResult {
Objects.requireNonNull(items, "items must not be null");
Objects.requireNonNull(elapsed, "elapsed must not be null");
items = List.copyOf(items);
}
/**
* Returns the items with a given completion.
*
* @param completion the completion to select
* @return the matching items
*/
public List<BatchPublishItemResult> withCompletion(PublishCompletion completion) {
return items.stream().filter(item -> item.result().completion() == completion).toList();
}
/**
* Reports whether every item confirmed.
*
* @return true when nothing was rejected or ambiguous
*/
public boolean allConfirmed() {
return items.stream()
.allMatch(item -> item.result().completion() == PublishCompletion.CONFIRMED);
}
}
@@ -1,30 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
/**
* The blocking facade over the asynchronous publisher.
*
* <p>Offered because most business code is written against a blocking data access layer, and
* forcing a {@code CompletionStage} through it produces worse code than a blocking call does. It is
* a facade rather than a second implementation: the core stays asynchronous, and this only converts
* the lifecycle.
*
* <p>It respects the publish deadline rather than waiting indefinitely, so a stalled broker
* surfaces as a timeout with ambiguous evidence instead of an exhausted thread pool.
*/
public interface BlockingMessagePublisher {
/**
* Publishes one message and waits for its outcome.
*
* @param <T> the payload type
* @param destination the logical destination
* @param message the envelope to publish
* @param options per-call options, including the deadline
* @return the outcome and its evidence
*/
<T> PublishResult publish(
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options);
}
@@ -1,28 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import java.time.Instant;
import java.util.concurrent.CompletionStage;
/**
* The M2 scheduled-delivery entry point.
*
* <p>Only destinations whose runtime declares {@code delayedDelivery} accept these calls. A plain
* Kafka topic does not: emulating a delay by holding the message in the producer would make the
* publisher's own liveness the schedule, so the platform rejects the call instead of pretending.
*/
public interface DelayedMessagePublisher {
/**
* Publishes a message the broker must not deliver before the given instant.
*
* @param <T> the payload type
* @param destination the logical destination
* @param message the envelope to publish
* @param deliverAt the earliest delivery time
* @return a stage completing with the publish outcome and its evidence
*/
<T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> message, Instant deliverAt);
}
@@ -100,6 +100,70 @@ public record PublishResult(
}
}
/**
* A publish the broker confirmed.
*
* @param level the confirmation the broker supplied
* @param routing whether the broker routed it; a broker with no routing step reports {@link
* RoutingOutcome#NOT_APPLICABLE}
* @param position the broker coordinate, when the broker reported one
* @param elapsed wall-clock time spent
* @return the confirmed result
*/
public static PublishResult confirmed(
ConfirmationLevel level,
RoutingOutcome routing,
Optional<BrokerPosition> position,
Duration elapsed) {
return new PublishResult(
PublishCompletion.CONFIRMED,
PublishEvidence.confirmed(level),
routing,
position,
1,
elapsed,
Optional.empty());
}
/**
* A publish refused before anything left the process.
*
* <p>Routing is {@link RoutingOutcome#NOT_APPLICABLE}: nothing reached a broker that could have
* routed it.
*
* @param elapsed wall-clock time spent
* @param failure why it was refused
* @return the rejected result
*/
public static PublishResult rejected(Duration elapsed, FailureDescriptor failure) {
return new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
elapsed,
Optional.of(failure));
}
/**
* A publish whose fate is unknown: the broker may or may not hold the message.
*
* @param elapsed wall-clock time spent
* @param failure what made the outcome unknowable
* @return the ambiguous result
*/
public static PublishResult ambiguous(Duration elapsed, FailureDescriptor failure) {
return new PublishResult(
PublishCompletion.AMBIGUOUS,
PublishEvidence.ambiguous(),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
elapsed,
Optional.of(failure));
}
/**
* Reports whether the broker may be holding this message.
*
@@ -1,25 +0,0 @@
package dev.caskeleton.messaging.api.settlement;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import java.util.concurrent.CompletionStage;
/**
* The M2 handler that settles its own deliveries.
*
* <p>Available only to modules granted the advanced capability. A handler that returns without
* calling a terminal settlement method is a defect the runtime detects and reports rather than
* silently leaving the message in flight.
*
* @param <T> the payload type
*/
public interface ManualMessageHandler<T> {
/**
* Handles one delivery, settling it through the supplied controller.
*
* @param delivery the decoded message and its metadata
* @param settlement the settlement handle for this delivery
* @return a stage completing when handling has finished
*/
CompletionStage<Void> handle(MessageDelivery<T> delivery, SettlementController settlement);
}
@@ -1,50 +0,0 @@
package dev.caskeleton.messaging.api.settlement;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import java.time.Duration;
import java.util.concurrent.CompletionStage;
/**
* The M2 manual settlement handle.
*
* <p>No method here accepts a broker channel, delivery tag, or offset. Manual settlement changes
* <em>when</em> the platform settles, never <em>who</em> settles, so the same DLQ-before-ack
* ordering and payload limits still apply.
*
* <p>Exactly one terminal call is permitted per delivery; a second call fails rather than racing
* the first.
*/
public interface SettlementController {
/**
* Acknowledges the message.
*
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> ack();
/**
* Schedules the message for another attempt.
*
* @param delay how long to wait before redelivery
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> retry(Duration delay);
/**
* Routes the message to the dead letter destination, settling the source only after that publish
* is confirmed.
*
* @param failure the sanitized failure description
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> deadLetter(FailureDescriptor failure);
/**
* Discards the message without dead lettering.
*
* @param failure the sanitized failure description
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> reject(FailureDescriptor failure);
}

Some files were not shown because too many files have changed in this diff Show More