refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환

설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(b5114b9b)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 12:49:07 +09:00
co-authored by Claude Opus 5.5
parent b5114b9bb4
commit 5e44be9ab4
122 changed files with 725 additions and 9914 deletions
+15 -42
View File
@@ -28,7 +28,7 @@ producing-service identity다.
`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`를 활성화하지 않는다.
publish path로 보내는 compatibility gate다. 기본값은 `false`이며 두 번째 relay를 만들지 않는다.
`true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다.
@@ -135,9 +135,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,30 +161,9 @@ 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이기 때문이며, 실 배포는 셋 다 참이다.
## 보안
@@ -211,20 +191,13 @@ app:
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
## Experimental / Optional
기본값은 전부 `false`다.
```yaml
app:
messaging:
experimental:
kafka-share: false
pulsar: false
nats: false
bridge:
spring-cloud-stream: false
```
Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
`sasl.jaas.config`, `ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로
조용히 넘어가지 않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나
`authentication-enabled`를 켰는데 `app.messaging.security.<broker>`가 없을 때, security 항목은
있는데 `CredentialProvider` bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때.
한계: truststore/keystore 설정 키가 없어 TLS는 JVM 기본 truststore를 쓰고, `MUTUAL_TLS`는 클라이언트
인증서를 제출할 수 없다(미지원).
## Backpressure
+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
```
+4 -6
View File
@@ -107,13 +107,11 @@ message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째
broker의 최대 redelivery window보다 **길어야** 한다.
row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
## Debezium CDC 대안
## CDC 대안
polling relay 대신 WAL을 읽는다. polling interval과 lease 경합이 사라지지만
인프라와 그 자체의 실패 모드가 추가된다.
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
+25 -47
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이었다 — 표와
@@ -29,10 +31,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 +39,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 +65,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 +72,7 @@ Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMat
### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개)
Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다.
### 2. 실 브로커 인증 (Testcontainers)
@@ -92,7 +82,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 +126,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 +143,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다.
+14 -12
View File
@@ -17,9 +17,9 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
| `*-api` (`core-api`, `schema-api`, `policy`, `reliability-api`, `admin-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
| `runtime-core`, `security`, `observability`, `admin-runtime` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `kafka`, `rabbit`, `pulsar-experimental`, `nats-experimental`, `kafka-share-experimental` | broker adapter | 해당 broker client. Spring은 `rabbit`의 `spring-rabbit`처럼 client가 곧 Spring인 경우만 |
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
| `outbox-jdbc-postgresql`, `inbox-jdbc-postgresql` | 관계형 신뢰성 adapter | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
| `spring-boot-starter`, `spring-cloud-stream-bridge` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
`outbox`/`inbox` leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring JDBC이고 SQL은
@@ -31,7 +31,7 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `spring-rabbit`, `cloudevents-api`, `micrometer-core`, `avro`,
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
@@ -45,12 +45,15 @@ 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 상태를 함께 변경한다.
@@ -79,10 +82,9 @@ canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시
`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 중 하나라도
`IntegrationEventEncoderPort`를 명시적으로 제공해야 한다. 템플릿은 구현체를 주지 않는다(후보였던
R1 JSON Schema encoder는 2026-09-25에 삭제). `OutboxCanonicalTransportRequirementValidator`는
publisher 또는 encoder 중 하나라도
없으면 startup을 거부한다. 즉 canonical flag가 켜졌는데 정본 encoder가 없는 상태로 성공 기동하는
경로는 없다.
@@ -1,11 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-kafka')
}
@@ -1,93 +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.
at.yawk.lz4:lz4-java:1.10.1=runtimeClasspath,testRuntimeClasspath
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.luben:zstd-jni:1.5.6-10=runtimeClasspath,testRuntimeClasspath
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
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
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.kafka:kafka-clients:4.1.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
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.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
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.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
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=runtimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xerial.snappy:snappy-java:1.1.10.7=runtimeClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
@@ -1,48 +0,0 @@
package dev.caskeleton.messaging.kafka.share;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.transport.TransportConsumerRegistration;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import java.util.Objects;
/**
* Registers a share group consumer, once the experimental guard has passed.
*
* <p>Pause and resume are refused rather than silently ignored. A share group has no partition
* assignment to pause, so accepting the call would let a retry policy that depends on pausing
* appear to work while doing nothing.
*/
public final class KafkaShareGroupRegistrar {
private final KafkaShareProfileValidator validator;
/** Creates a registrar with the default validator. */
public KafkaShareGroupRegistrar() {
this(new KafkaShareProfileValidator());
}
/**
* Creates a registrar with an explicit validator.
*
* @param validator the share profile validator
*/
public KafkaShareGroupRegistrar(KafkaShareProfileValidator validator) {
this.validator = Objects.requireNonNull(validator, "validator must not be null");
}
/**
* Registers a share group consumer.
*
* @param profile the share group profile
* @param spec what to consume and where to deliver it
* @return the registration
*/
public TransportConsumerRegistration register(
KafkaShareProfile profile, TransportConsumerSpec spec) {
Objects.requireNonNull(spec, "spec must not be null");
validator.validate(profile);
throw new MessagingCapabilityUnavailableException(
"KAFKA_SHARE_CONSUMER_NOT_IMPLEMENTED",
"Kafka Share registration is not implemented; refusing to advertise an active consumer");
}
}
@@ -1,33 +0,0 @@
package dev.caskeleton.messaging.kafka.share;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.util.Objects;
/**
* Settings for a Kafka Share Group work queue.
*
* @param destination the logical destination
* @param shareGroup the share group name
* @param orderingScope the ordering the destination declares
* @param enabled whether the experimental adapter is switched on
* @param maxDeliveryCount how many times a record may be re-acquired before it is released
*/
public record KafkaShareProfile(
DestinationName destination,
String shareGroup,
OrderingScope orderingScope,
boolean enabled,
int maxDeliveryCount) {
public KafkaShareProfile {
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(orderingScope, "orderingScope must not be null");
if (shareGroup == null || shareGroup.isBlank()) {
throw new IllegalArgumentException("shareGroup must not be blank");
}
if (maxDeliveryCount < 1) {
throw new IllegalArgumentException("maxDeliveryCount must be at least 1");
}
}
}
@@ -1,42 +0,0 @@
package dev.caskeleton.messaging.kafka.share;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import java.util.Objects;
/**
* Guards the Kafka Share Group experimental adapter.
*
* <p>A share group hands individual records to competing consumers and acknowledges them
* individually. That is a work queue, and it is fundamentally incompatible with partition ordering:
* two consumers in the same share group can process records from one partition concurrently and
* finish in either order. Configuring an ordered destination on a share group would therefore
* advertise a guarantee the broker is not providing, so it is refused rather than degraded.
*
* <p>The adapter is also off unless explicitly enabled, so an Experimental capability cannot drift
* into a Stable deployment by default.
*/
public final class KafkaShareProfileValidator {
/**
* Validates a share group profile.
*
* @param profile the profile to validate
* @throws IllegalArgumentException when the destination requires ordering
* @throws MessagingCapabilityUnavailableException when the experimental adapter is disabled
*/
public void validate(KafkaShareProfile profile) {
Objects.requireNonNull(profile, "profile must not be null");
if (!profile.enabled()) {
throw new MessagingCapabilityUnavailableException(
"KAFKA_SHARE_DISABLED",
"the Kafka Share Group adapter is experimental and disabled unless "
+ "backend.messaging.experimental.kafka-share=true");
}
if (profile.orderingScope() != OrderingScope.NONE) {
throw new IllegalArgumentException(
"a Kafka share group cannot provide ordered delivery: " + profile.destination().value());
}
}
}
@@ -1,27 +0,0 @@
package dev.caskeleton.messaging.kafka.share;
import dev.caskeleton.messaging.api.destination.MessagingCapabilities;
/**
* What a Kafka Share Group can and cannot do.
*
* <p>Declared as a capability rather than assumed, so that the shared validators refuse an ordered
* or replayed destination on this adapter before a message is ever produced.
*/
public final class KafkaShareWorkQueueCapability {
private KafkaShareWorkQueueCapability() {}
/**
* Returns the share group capability set.
*
* <p>Per-record settlement, yes. Ordering, replay, and transactions, no — a share group gives up
* exactly those to gain competing-consumer throughput.
*
* @return the capabilities
*/
public static MessagingCapabilities capabilities() {
return new MessagingCapabilities(
true, true, true, false, false, false, false, false, false, false, false, false);
}
}
@@ -1,113 +0,0 @@
package dev.caskeleton.messaging.kafka.share;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import org.junit.jupiter.api.Test;
class KafkaShareProfileValidatorTest {
private final KafkaShareProfileValidator validator = new KafkaShareProfileValidator();
@Test
void rejectsOrderedStreamUse() {
KafkaShareProfile profile = KafkaShareProfileFixtures.profile(OrderingScope.KEY);
assertThatThrownBy(() -> validator.validate(profile))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("ordered");
}
@Test
void rejectsPartitionOrderingToo() {
KafkaShareProfile profile = KafkaShareProfileFixtures.profile(OrderingScope.PARTITION);
assertThatThrownBy(() -> validator.validate(profile))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void staysDisabledUnlessExplicitlyEnabled() {
KafkaShareProfile profile = KafkaShareProfileFixtures.disabled();
assertThatThrownBy(() -> validator.validate(profile))
.isInstanceOf(MessagingCapabilityUnavailableException.class)
.hasMessageContaining("experimental");
}
@Test
void acceptsAnUnorderedWorkQueue() {
assertThatCode(() -> validator.validate(KafkaShareProfileFixtures.profile(OrderingScope.NONE)))
.doesNotThrowAnyException();
}
@Test
void doesNotAdvertiseOrderingReplayOrTransactions() {
var capabilities = KafkaShareWorkQueueCapability.capabilities();
assertThat(capabilities.perMessageSettlement()).isTrue();
assertThat(capabilities.orderedStream()).isFalse();
assertThat(capabilities.keyedOrdering()).isFalse();
assertThat(capabilities.replay()).isFalse();
assertThat(capabilities.brokerTransaction()).isFalse();
}
@Test
void registerFailsClosedUntilAShareConsumerActuallyExists() {
assertThatThrownBy(
() ->
new KafkaShareGroupRegistrar()
.register(
KafkaShareProfileFixtures.profile(OrderingScope.NONE),
new dev.caskeleton.messaging.transport.TransportConsumerSpec(
KafkaShareProfileFixtures.destinationProfile(),
delivery ->
java.util.concurrent.CompletableFuture.completedFuture(null))))
.isInstanceOf(MessagingCapabilityUnavailableException.class)
.hasMessageContaining("not implemented");
}
}
/** Builds Kafka share group fixtures. */
final class KafkaShareProfileFixtures {
private KafkaShareProfileFixtures() {}
static KafkaShareProfile profile(OrderingScope orderingScope) {
return new KafkaShareProfile(
new DestinationName("email-work"), "email-share", orderingScope, true, 5);
}
static KafkaShareProfile disabled() {
return new KafkaShareProfile(
new DestinationName("email-work"), "email-share", OrderingScope.NONE, false, 5);
}
static dev.caskeleton.messaging.policy.DestinationProfile destinationProfile() {
return new dev.caskeleton.messaging.policy.DestinationProfile(
new DestinationName("email-work"),
"kafka-primary",
dev.caskeleton.messaging.api.destination.DestinationKind.WORK_QUEUE,
dev.caskeleton.messaging.policy.PhysicalDestination.kafkaTopic("email.work.v1"),
new dev.caskeleton.messaging.policy.SchemaPolicy(
dev.caskeleton.messaging.api.ContentType.JSON,
dev.caskeleton.messaging.schema.SchemaCompatibility.BACKWARD,
java.util.Set.of(new dev.caskeleton.messaging.api.MessageType("email.requested"))),
dev.caskeleton.messaging.api.delivery.DeliveryGuarantee.AT_LEAST_ONCE,
OrderingScope.NONE,
dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED,
dev.caskeleton.messaging.policy.ProducerPolicy.defaults(),
dev.caskeleton.messaging.policy.ConsumerPolicy.defaults("email-share"),
dev.caskeleton.messaging.policy.RetryPolicy.none(),
dev.caskeleton.messaging.policy.DeadLetterPolicy.disabled(),
dev.caskeleton.messaging.policy.PayloadPolicy.defaults(),
dev.caskeleton.messaging.policy.CapabilityTier.M2,
false,
false,
false);
}
}
+34 -2
View File
@@ -1,8 +1,13 @@
plugins {
id 'java-test-fixtures'
id 'ca.auxiliary-source-set'
id 'ca.jmh-benchmarks'
id 'ca.messaging-certification'
id 'ca.platform-module'
id 'me.champeau.jmh'
}
jmh {
jmhVersion = libs.versions.jmh.get()
includeTests = true
}
auxiliarySourceSets {
@@ -82,3 +87,30 @@ strictTestLanes {
.toString()
}
}
// The certification lane writes the scenarios it proved; the committed manifest in messaging-testkit
// may claim no more and no fewer. gitCommit and observedAt are provenance, not claim identity.
tasks.register('verifyMessagingCertificationEvidence') {
group = 'verification'
description = 'Fails when the committed broker certification manifest claims a scenario the certification lane did not produce.'
dependsOn 'messagingCertificationTest'
def produced = layout.buildDirectory.file('messaging-certification/broker-certification-evidence.jsonl')
def committed = rootProject.file('messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl')
inputs.file(produced)
inputs.file(committed)
doLast {
def claims = { File file ->
file.readLines('UTF-8').findAll { !it.trim().isEmpty() }.collect {
it.replaceAll(/,"gitCommit":"[^"]*"/, '').replaceAll(/,"observedAt":"[^"]*"/, '')
} as Set
}
def ran = claims(produced.get().asFile)
def shipped = claims(committed)
if (ran != shipped) {
throw new GradleException("the committed certification manifest does not match this run.\n" +
" claimed but not produced: ${shipped - ran}\n produced but not claimed: ${ran - shipped}\n" +
"Copy ${produced.get().asFile} over ${committed} — the manifest is a record of a run.")
}
}
}
+16 -13
View File
@@ -46,15 +46,15 @@ io.micrometer:micrometer-core:1.16.7=compileClasspath,integrationTestCompileClas
io.micrometer:micrometer-observation:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
net.sf.jopt-simple:jopt-simple:5.0.4=jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath
net.sf.jopt-simple:jopt-simple:5.0.4=jmh,jmhCompileClasspath,jmhRuntimeClasspath
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-compress:1.28.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.apache.commons:commons-lang3:3.20.0=checkstyle,integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs
org.apache.commons:commons-math3:3.6.1=jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath
org.apache.commons:commons-math3:3.6.1=jmh,jmhCompileClasspath,jmhRuntimeClasspath
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
@@ -67,8 +67,8 @@ 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=integrationTestCompileClasspath,jmhCompileClasspath,testCompileClasspath,testFixturesCompileClasspath
org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.apiguardian:apiguardian-api:1.1.2=integrationTestCompileClasspath,testCompileClasspath,testFixturesCompileClasspath
org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,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
@@ -78,24 +78,27 @@ org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,jmhRuntimeCl
org.javassist:javassist:3.28.0-GA=checkstyle
org.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testFixturesAnnotationProcessor,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testRuntimeClasspath
org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.mockito:mockito-core:5.20.0=mockitoAgent
org.openjdk.jmh:jmh-core:1.37=jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath
org.openjdk.jmh:jmh-generator-annprocess:1.37=jmhAnnotationProcessor
org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.openjdk.jmh:jmh-core:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath
org.openjdk.jmh:jmh-generator-asm:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath
org.openjdk.jmh:jmh-generator-bytecode:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath
org.openjdk.jmh:jmh-generator-reflection:1.37=jmh,jmhCompileClasspath,jmhRuntimeClasspath
org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,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.0=jmh,jmhCompileClasspath,jmhRuntimeClasspath
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
@@ -1,14 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-observability')
api project(':messaging:messaging-security')
api project(':messaging:messaging-admin-api')
}
@@ -1,89 +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
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
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.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
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.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
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=
@@ -1,57 +0,0 @@
package dev.caskeleton.messaging.nats;
/**
* How a JetStream consumer acknowledges what it has handled.
*
* <p>Only {@link #EXPLICIT} is usable by the platform, and the other two are modelled anyway so the
* refusal can name what was configured instead of failing with a generic message.
*
* <p>{@link #NONE} and {@link #ALL} both break at-least-once in ways that look like success. {@code
* AckNone} never acknowledges, so JetStream considers every message delivered the moment it is sent
* — a handler that throws has already had its message forgotten. {@code AckAll} acknowledges every
* message up to the one being acknowledged, so a consumer processing messages concurrently silently
* acknowledges work that is still in flight.
*/
public enum NatsAckMode {
/** Every message is acknowledged individually. The only mode the platform supports. */
EXPLICIT(true),
/** Acknowledging one message acknowledges every earlier one. */
ALL(false),
/** No acknowledgement at all; JetStream treats delivery as completion. */
NONE(false);
private final boolean supportsAtLeastOnce;
NatsAckMode(boolean supportsAtLeastOnce) {
this.supportsAtLeastOnce = supportsAtLeastOnce;
}
/**
* Reports whether this mode can carry at-least-once delivery.
*
* @return true only for {@link #EXPLICIT}
*/
public boolean supportsAtLeastOnce() {
return supportsAtLeastOnce;
}
/**
* Returns why a mode cannot be used, for the refusal message.
*
* @return the sanitized reason, empty for {@link #EXPLICIT}
*/
public String rejectionReason() {
return switch (this) {
case EXPLICIT -> "";
case ALL ->
"AckAll acknowledges every earlier message, so concurrent handling silently settles work "
+ "that is still in flight";
case NONE ->
"AckNone treats delivery as completion, so a message whose handler throws has already "
+ "been forgotten by the broker";
};
}
}
@@ -1,103 +0,0 @@
package dev.caskeleton.messaging.nats;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
/**
* The JetStream settings for one destination.
*
* <p>{@code maxDeliver} is the setting that makes the platform's dead-lettering necessary. When a
* message reaches it, JetStream <em>terminates</em> the message — it stops redelivering and routes
* it nowhere. Without the platform parking it first, the message is simply gone, which is why
* {@link NatsMaxDeliverParkingWorkflow} has to run strictly before the limit is reached rather than
* in response to it.
*
* <p>{@code ackWait} is the redelivery trigger. A handler slower than {@code ackWait} gets its
* message redelivered while it is still working on it, so this is the one JetStream number that has
* to be set from the handler's real latency rather than from a default.
*
* @param subject the JetStream subject
* @param stream the stream capturing that subject
* @param durableName the durable consumer name
* @param ackMode how the consumer acknowledges
* @param ackWait how long JetStream waits before redelivering
* @param maxDeliver how many deliveries before JetStream terminates the message
* @param deduplicationWindow the publish deduplication window, when enabled
*/
public record NatsJetStreamProfile(
String subject,
String stream,
String durableName,
NatsAckMode ackMode,
Duration ackWait,
int maxDeliver,
Optional<Duration> deduplicationWindow) {
/** How many deliveries the platform leaves as headroom before JetStream's terminate. */
public static final int PARKING_HEADROOM = 1;
public NatsJetStreamProfile {
Objects.requireNonNull(ackMode, "ackMode must not be null");
Objects.requireNonNull(ackWait, "ackWait must not be null");
Objects.requireNonNull(deduplicationWindow, "deduplicationWindow must not be null");
requireText(subject, "subject");
requireText(stream, "stream");
requireText(durableName, "durableName");
if (!ackMode.supportsAtLeastOnce()) {
throw new IllegalArgumentException(
"%s cannot carry at-least-once delivery: %s"
.formatted(ackMode, ackMode.rejectionReason()));
}
if (ackWait.isNegative() || ackWait.isZero()) {
throw new IllegalArgumentException("ackWait must be positive");
}
if (maxDeliver < 2) {
throw new IllegalArgumentException(
"maxDeliver must leave at least one delivery of headroom for the platform to park the "
+ "message before JetStream terminates it");
}
if (deduplicationWindow.isPresent()
&& (deduplicationWindow.get().isNegative() || deduplicationWindow.get().isZero())) {
throw new IllegalArgumentException("deduplicationWindow must be positive when set");
}
}
/**
* Returns the delivery count at which the platform must park the message.
*
* <p>Strictly before {@code maxDeliver}: acting on the limit itself is too late, because the
* delivery that reaches it is the one JetStream terminates.
*
* @return the parking threshold
*/
public int parkAtDelivery() {
return maxDeliver - PARKING_HEADROOM;
}
/**
* Returns a profile with the platform defaults.
*
* @param subject the JetStream subject
* @param stream the stream name
* @param durableName the durable consumer name
* @return the profile
*/
public static NatsJetStreamProfile durable(String subject, String stream, String durableName) {
return new NatsJetStreamProfile(
subject,
stream,
durableName,
NatsAckMode.EXPLICIT,
Duration.ofSeconds(30),
5,
Optional.of(Duration.ofMinutes(2)));
}
private static void requireText(String value, String field) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(field + " must not be blank");
}
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.messaging.nats;
import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.MessagingCapabilities;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.policy.DestinationProfile;
import java.util.Objects;
/**
* Guards the NATS JetStream Experimental adapter.
*
* <p>Core NATS is refused for any at-least-once destination. Core NATS is fire-and-forget with no
* persistence and no acknowledgement, so a durable destination configured against it would report
* success for messages that were never stored anywhere — the failure mode is total and silent.
*
* <p>An ordered JetStream consumer and a competing work queue are mutually exclusive: the ordered
* consumer is a single-reader construct, and pointing several workers at it does not distribute the
* load, it breaks the ordering the consumer exists to provide.
*/
public final class NatsJetStreamProfileValidator {
/**
* Validates a destination against a JetStream consumer configuration.
*
* @param profile the destination profile
* @param jetStreamEnabled whether JetStream persistence is in use
* @param orderedConsumer whether an ordered consumer is configured
* @param competingWorkers how many workers share the consumer
* @param enabled whether the experimental adapter is switched on
*/
public void validate(
DestinationProfile profile,
boolean jetStreamEnabled,
boolean orderedConsumer,
int competingWorkers,
boolean enabled) {
Objects.requireNonNull(profile, "profile must not be null");
if (!enabled) {
throw new MessagingCapabilityUnavailableException(
"NATS_DISABLED",
"the NATS JetStream adapter is experimental and disabled unless "
+ "app.messaging.experimental.nats=true");
}
if (profile.deliveryGuarantee() == DeliveryGuarantee.AT_LEAST_ONCE && !jetStreamEnabled) {
throw new IllegalArgumentException(
"core NATS cannot provide at-least-once delivery; JetStream is required: "
+ profile.name().value());
}
if (orderedConsumer && competingWorkers > 1) {
throw new IllegalArgumentException(
"an ordered JetStream consumer cannot be shared by competing workers: "
+ profile.name().value());
}
if (profile.orderingScope() == OrderingScope.KEY) {
throw new IllegalArgumentException(
"the NATS adapter does not offer per-key ordering: " + profile.name().value());
}
}
/**
* Returns what the JetStream adapter can prove.
*
* <p>Native dead lettering is reported as unavailable. JetStream terminates a message after its
* delivery limit rather than routing it anywhere, so the platform supplies dead lettering itself;
* claiming a native one would leave operators looking for a queue that does not exist.
*
* @return the capabilities
*/
public MessagingCapabilities capabilities() {
return new MessagingCapabilities(
true, true, true, true, true, false, true, false, false, true, false, true);
}
}
@@ -1,295 +0,0 @@
package dev.caskeleton.messaging.nats;
import dev.caskeleton.messaging.api.destination.DestinationCapabilities;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessagingCapabilities;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import dev.caskeleton.messaging.transport.MessagingTransport;
import dev.caskeleton.messaging.transport.TransportConsumerRegistration;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import dev.caskeleton.messaging.transport.TransportPublishResult;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.Function;
/**
* The Experimental NATS JetStream adapter.
*
* <p>Publishes go through JetStream, never core NATS. A core publish returns as soon as the bytes
* are written to the socket, with no persistence and no acknowledgement, so an adapter using it
* would report success for messages that were never stored — the failure is total and silent, which
* is why {@link NatsJetStreamProfileValidator} refuses the combination at startup.
*
* <p>A JetStream publish acknowledgement names the stream and sequence the message landed in, which
* is real persistence evidence. A publish that times out is {@code AMBIGUOUS}: JetStream may have
* stored it and lost only the acknowledgement, and the deduplication window is what makes retrying
* it safe when the profile enables one.
*
* <p>This is an Experimental contract seam, not a Stable adapter. It exercises the transport SPI
* against a publish operation the application supplies; it does not ship a NATS client bridge,
* connection management, or reconnection. Only a failure the operation reports as a {@link
* NatsPreSendRejection} is treated as definitely not transmitted — every other failure, recognised
* or not, is ambiguous, because a caller that reads {@code REJECTED} may republish under a new
* identity and duplicate a message the server already stored.
*
* <p>The adapter reports {@code nativeDeadLetter} as false. JetStream terminates a message at its
* delivery limit rather than routing it anywhere, so the platform parks it via {@link
* NatsMaxDeliverParkingWorkflow}; claiming a native dead-letter would send operators looking for a
* queue that does not exist.
*/
public final class NatsJetStreamTransport implements MessagingTransport {
private static final MessagingCapabilities CAPABILITIES =
new MessagingCapabilities(
true, true, true, true, true, false, true, false, false, true, false, true);
private final String brokerName;
private final long generation;
private final NatsJetStreamProfile profile;
private final JetStreamPublishOperation publish;
private final Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory;
private final AtomicBoolean closed = new AtomicBoolean();
/**
* Creates a publish-only transport.
*
* @param brokerName the logical broker name
* @param generation the runtime generation
* @param profile the JetStream settings
* @param publish the JetStream publish operation
*/
public NatsJetStreamTransport(
String brokerName,
long generation,
NatsJetStreamProfile profile,
JetStreamPublishOperation publish) {
this(
brokerName,
generation,
profile,
publish,
spec -> {
throw new MessagingCapabilityUnavailableException(
"NATS_CONSUMER_NOT_CONFIGURED",
"this NATS transport was created without a consumer factory");
});
}
/**
* Creates a transport with a consumer factory.
*
* @param brokerName the logical broker name
* @param generation the runtime generation
* @param profile the JetStream settings
* @param publish the JetStream publish operation
* @param consumerFactory builds a consumer registration for a spec
*/
public NatsJetStreamTransport(
String brokerName,
long generation,
NatsJetStreamProfile profile,
JetStreamPublishOperation publish,
Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory) {
this.brokerName = Objects.requireNonNull(brokerName, "brokerName must not be null");
this.generation = generation;
this.profile = Objects.requireNonNull(profile, "profile must not be null");
this.publish = Objects.requireNonNull(publish, "publish must not be null");
this.consumerFactory = Objects.requireNonNull(consumerFactory, "consumerFactory is required");
}
@Override
public CompletionStage<TransportPublishResult> publish(TransportPublishRequest request) {
Objects.requireNonNull(request, "request must not be null");
if (closed.get()) {
return completed(rejectedLocally("NATS_TRANSPORT_CLOSED", "the transport is shutting down"));
}
int size = request.envelope().payload().size();
int limit = request.profile().payload().maxBytes();
if (size > limit) {
return completed(
rejectedLocally(
"PAYLOAD_TOO_LARGE", "encoded payload is " + size + " bytes, limit is " + limit));
}
// The caller's own deadline, honoured rather than ignored. Without it a stalled JetStream
// publish holds the caller for as long as the SDK's default takes, and the timeout the caller
// set to bound its own latency budget means nothing.
long startedAt = System.nanoTime();
return publish
.publish(profile.subject(), deduplicationId(request), request)
.toCompletableFuture()
.orTimeout(
request.options().timeout().toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS)
.handle(
(position, failure) ->
failure == null
? confirmed(position, elapsedSince(startedAt))
: classify(failure, elapsedSince(startedAt)))
.thenApply(TransportPublishResult::new);
}
@Override
public TransportConsumerRegistration register(TransportConsumerSpec spec) {
Objects.requireNonNull(spec, "spec must not be null");
if (closed.get()) {
throw new MessagingCapabilityUnavailableException(
"NATS_TRANSPORT_CLOSED", "the transport is shutting down");
}
return consumerFactory.apply(spec);
}
@Override
public DestinationCapabilities capabilities(DestinationName destination) {
return new DestinationCapabilities(destination, brokerName, CAPABILITIES);
}
@Override
public String brokerName() {
return brokerName;
}
@Override
public long generation() {
return generation;
}
@Override
public void close() {
closed.set(true);
}
/**
* Reports whether the transport is still accepting work.
*
* @return true until close
*/
public boolean isAcceptingWork() {
return !closed.get();
}
/**
* Returns the deduplication id for a publish, when the profile enables deduplication.
*
* <p>The logical message id, so a retry of an ambiguous publish is recognised as the same message
* rather than accepted as a new one. Minting a fresh id per attempt would make the deduplication
* window useless in exactly the situation it exists for.
*
* @param request the publish request
* @return the deduplication id, or empty when the profile has no window
*/
private Optional<String> deduplicationId(TransportPublishRequest request) {
return profile
.deduplicationWindow()
.map(window -> request.envelope().messageId().value().toString());
}
private static Duration elapsedSince(long startedAtNanos) {
return Duration.ofNanos(System.nanoTime() - startedAtNanos);
}
private static PublishResult confirmed(NatsStreamPosition position, Duration elapsed) {
return new PublishResult(
PublishCompletion.CONFIRMED,
// The publish acknowledgement names the stream and sequence the message landed in, which is
// persistence evidence rather than a receipt for bytes on a socket.
new PublishEvidence(
true,
TransmissionEvidence.TRANSMITTED,
true,
ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK),
RoutingOutcome.ROUTED,
Optional.of(position),
1,
elapsed,
Optional.empty());
}
/**
* Decides what a publish failure means, from typed signals only.
*
* <p>Only {@link NatsPreSendRejection} — thrown by the publish operation when it knows the send
* never left the client — reports {@code REJECTED / NOT_TRANSMITTED}. Everything else is {@code
* AMBIGUOUS}, including failures this adapter does not recognise, because the alternative is
* telling a caller nothing was transmitted when the server may already hold the message.
*/
private static PublishResult classify(Throwable failure, Duration elapsed) {
Throwable cause = failure instanceof CompletionException ? failure.getCause() : failure;
if (cause instanceof NatsPreSendRejection rejection) {
return new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.CONFIGURATION, rejection.code(), rejection.getMessage())));
}
boolean timedOut = cause instanceof java.util.concurrent.TimeoutException;
return new PublishResult(
PublishCompletion.AMBIGUOUS,
new PublishEvidence(
true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.TRANSIENT_INFRASTRUCTURE,
timedOut ? "NATS_PUBLISH_TIMEOUT" : "NATS_PUBLISH_OUTCOME_UNKNOWN",
timedOut
? "the publish acknowledgement did not arrive; the stream may already hold it"
: "the publish failed in a way this adapter does not classify; the stream may"
+ " already hold the message")));
}
private static TransportPublishResult rejectedLocally(String code, String message) {
return new TransportPublishResult(
new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
// A local refusal: nothing was attempted, so no time was spent on the wire.
Duration.ZERO,
Optional.of(FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message))));
}
private static CompletionStage<TransportPublishResult> completed(TransportPublishResult result) {
return CompletableFuture.completedFuture(result);
}
/** The JetStream publish, isolated so the adapter is testable without a server. */
@FunctionalInterface
public interface JetStreamPublishOperation {
/**
* Publishes one encoded message to JetStream.
*
* @param subject the JetStream subject
* @param deduplicationId the {@code Nats-Msg-Id} value, when deduplication is enabled
* @param request the publish request
* @return a stage completing with the stream position the message landed at
*/
CompletionStage<NatsStreamPosition> publish(
String subject, Optional<String> deduplicationId, TransportPublishRequest request);
}
}
@@ -1,85 +0,0 @@
package dev.caskeleton.messaging.nats;
import java.util.Objects;
/**
* Decides what to do with a JetStream delivery before its {@code maxDeliver} limit destroys it.
*
* <p>JetStream has no dead-letter queue. When a message hits {@code maxDeliver} the server
* terminates it: no redelivery, no routing, no record beyond an advisory. Every other broker in
* this platform parks a poison message somewhere an operator can find it, and this workflow is what
* makes NATS behave the same way.
*
* <p>The parking therefore happens on the delivery <em>before</em> the limit, not on the limit
* itself. Acting at {@code maxDeliver} would mean acting on the delivery JetStream is about to
* discard, so any failure in the dead-letter publish would lose the message outright — precisely
* the case the DLQ-confirm-before-settle invariant exists to prevent.
*/
public final class NatsMaxDeliverParkingWorkflow {
/** What the platform should do with one delivery. */
public enum Action {
/** Hand the message to the handler as normal. */
DELIVER_TO_HANDLER,
/** Publish to the platform dead-letter destination, then terminate the source. */
PARK_TO_DEAD_LETTER,
/**
* The message has already passed the limit and JetStream has terminated it.
*
* <p>Reachable only if the profile changed under a live consumer. Nothing can be recovered
* here; the outcome exists so the situation is reported rather than mistaken for a redelivery.
*/
ALREADY_TERMINATED
}
private final NatsJetStreamProfile profile;
/**
* Creates a workflow for one destination.
*
* @param profile the JetStream settings
*/
public NatsMaxDeliverParkingWorkflow(NatsJetStreamProfile profile) {
this.profile = Objects.requireNonNull(profile, "profile must not be null");
}
/**
* Decides what to do with a delivery.
*
* @param deliveryCount how many times this message has been delivered, counting this one
* @return the action to take
*/
public Action decide(long deliveryCount) {
if (deliveryCount < 1) {
throw new IllegalArgumentException("the first delivery is delivery 1");
}
if (deliveryCount > profile.maxDeliver()) {
return Action.ALREADY_TERMINATED;
}
return deliveryCount >= profile.parkAtDelivery()
? Action.PARK_TO_DEAD_LETTER
: Action.DELIVER_TO_HANDLER;
}
/**
* Reports whether the source may be terminated after a dead-letter publish.
*
* <p>Only on a confirmed publish. Terminating first would discard the message on a broker that
* cannot redeliver it, which is the one irreversible mistake available here.
*
* @param deadLetterConfirmed whether the dead-letter publish was confirmed
* @return true when the source may be terminated
*/
public boolean maySettleSource(boolean deadLetterConfirmed) {
return deadLetterConfirmed;
}
/**
* Returns the delivery count at which parking begins.
*
* @return the parking threshold
*/
public int parkingThreshold() {
return profile.parkAtDelivery();
}
}
@@ -1,65 +0,0 @@
package dev.caskeleton.messaging.nats;
import java.util.Objects;
/**
* The one signal that lets this adapter report {@code REJECTED / NOT_TRANSMITTED}.
*
* <p>Classification used to work by reading the exception's class simple name and matching
* substrings — {@code "Timeout"} meant ambiguous, anything else meant rejected. Two things are
* wrong with that. A class name is not part of any SDK's contract: it changes between versions, and
* an unrelated exception whose name happens to contain the substring is misread. And defaulting the
* unknown case to {@code REJECTED} tells the caller nothing was transmitted, so a caller that
* republishes under a new identity duplicates a message the server may well have stored.
*
* <p>The publish operation throws this only when it knows the send never left the client: an
* argument the SDK refused, a connection that was already closed, a subject the client could not
* resolve. Everything else — including anything the adapter does not recognise — is ambiguous, and
* ambiguity is the honest answer when the write may have landed.
*/
public final class NatsPreSendRejection extends RuntimeException {
private static final long serialVersionUID = 1L;
private final String code;
/**
* Creates a pre-send rejection.
*
* @param code the sanitised platform code for the refusal
* @param message a sanitised description
*/
public NatsPreSendRejection(String code, String message) {
super(message);
this.code = requireCode(code);
}
/**
* Creates a pre-send rejection wrapping the SDK's own exception.
*
* @param code the sanitised platform code for the refusal
* @param message a sanitised description
* @param cause the SDK exception that proves the send never started
*/
public NatsPreSendRejection(String code, String message, Throwable cause) {
super(message, cause);
this.code = requireCode(code);
}
private static String requireCode(String code) {
Objects.requireNonNull(code, "code must not be null");
if (code.isBlank()) {
throw new IllegalArgumentException("code must not be blank");
}
return code;
}
/**
* The sanitised code reported to the caller.
*
* @return the code
*/
public String code() {
return code;
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.messaging.nats;
import dev.caskeleton.messaging.api.publish.BrokerPosition;
import java.util.Map;
import java.util.Objects;
/**
* A JetStream message's coordinate: its stream, its sequence in that stream, and the consumer's own
* sequence.
*
* <p>Two sequences, because they answer different questions. The stream sequence identifies the
* message and is what a replay seeks to. The consumer sequence counts <em>deliveries</em> to this
* consumer, so it advances on every redelivery while the stream sequence does not — comparing them
* is how a redelivery is recognised at all.
*
* @param stream the stream holding the message
* @param streamSequence the message's position in the stream
* @param consumerSequence how many messages this consumer has been delivered
* @param deliveryCount how many times this message has been delivered
*/
public record NatsStreamPosition(
String stream, long streamSequence, long consumerSequence, long deliveryCount)
implements BrokerPosition {
public NatsStreamPosition {
if (stream == null || stream.isBlank()) {
throw new IllegalArgumentException("stream must not be blank");
}
if (streamSequence < 1) {
throw new IllegalArgumentException("JetStream sequences start at 1");
}
if (deliveryCount < 1) {
throw new IllegalArgumentException("a delivered message has been delivered at least once");
}
}
@Override
public String broker() {
return "nats";
}
@Override
public Map<String, String> diagnosticAttributes() {
return Map.of(
"stream", stream,
"streamSequence", Long.toString(streamSequence),
"consumerSequence", Long.toString(consumerSequence),
"deliveryCount", Long.toString(deliveryCount));
}
/**
* Reports whether this delivery is a redelivery.
*
* @return true when the message has been delivered before
*/
public boolean isRedelivery() {
return deliveryCount > 1;
}
/**
* Returns the stream sequence a replay should resume from to re-read this message.
*
* @return the resume sequence
*/
public long replayFrom() {
return streamSequence;
}
@Override
public String toString() {
return Objects.toString(
"NatsStreamPosition[stream=%s, streamSequence=%d, deliveryCount=%d]"
.formatted(stream, streamSequence, deliveryCount));
}
}
@@ -1,337 +0,0 @@
package dev.caskeleton.messaging.nats;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee;
import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.schema.EncodedMessage;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import dev.caskeleton.messaging.transport.TransportPublishResult;
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeoutException;
import org.junit.jupiter.api.Test;
class NatsAdapterContractTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final NatsStreamPosition POSITION = new NatsStreamPosition("ORDERS", 42, 42, 1);
private final List<Optional<String>> capturedDeduplicationIds = new ArrayList<>();
private NatsJetStreamTransport confirming(Optional<Duration> deduplicationWindow) {
return new NatsJetStreamTransport(
"nats-primary",
1,
profile(deduplicationWindow),
(subject, deduplicationId, request) -> {
capturedDeduplicationIds.add(deduplicationId);
return CompletableFuture.completedFuture(POSITION);
});
}
private NatsJetStreamTransport failingWith(Throwable failure) {
return new NatsJetStreamTransport(
"nats-primary",
1,
profile(Optional.of(Duration.ofMinutes(2))),
(subject, deduplicationId, request) -> CompletableFuture.failedFuture(failure));
}
private static PublishResult await(CompletionStage<TransportPublishResult> stage) {
return stage.toCompletableFuture().join().result();
}
@Test
void aStoredMessageReportsPersistenceEvidence() {
PublishResult result = await(confirming(Optional.empty()).publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED);
assertThat(result.evidence().confirmationLevel())
.as("the acknowledgement names the stream and sequence, not just bytes on a socket")
.isEqualTo(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK);
}
@Test
void theStreamPositionIsCarriedBack() {
assertThat(await(confirming(Optional.empty()).publish(request(64))).position())
.hasValue(POSITION);
}
@Test
void aPublishTimeoutIsAmbiguousBecauseTheStreamMayHoldIt() {
PublishResult result = await(failingWith(new TimeoutException("no ack")).publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.evidence().transmission())
.isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED);
}
@Test
void aFailureNamedLikeAKnownOneIsStillAmbiguous() {
// The class name used to be the classifier: an exception whose simple name contained
// "NoRespond" was reported REJECTED / NOT_TRANSMITTED. A name is not an SDK contract, and a
// caller that reads NOT_TRANSMITTED republishes under a new identity.
PublishResult result =
await(failingWith(new IllegalStateException("NoRespondersException")).publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.failure())
.hasValueSatisfying(
failure -> assertThat(failure.code()).isEqualTo("NATS_PUBLISH_OUTCOME_UNKNOWN"));
}
@Test
void onlyATypedPreSendRejectionReportsNothingTransmitted() {
PublishResult result =
await(
failingWith(
new NatsPreSendRejection(
"NATS_CONNECTION_CLOSED", "the client was closed before the send"))
.publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence().transmission())
.isEqualTo(dev.caskeleton.messaging.api.publish.TransmissionEvidence.NOT_TRANSMITTED);
assertThat(result.failure())
.hasValueSatisfying(
failure -> assertThat(failure.code()).isEqualTo("NATS_CONNECTION_CLOSED"));
}
@Test
void aWrappedUnknownFailureIsAmbiguousRatherThanRejected() {
PublishResult result =
await(
failingWith(
new java.util.concurrent.CompletionException(
new RuntimeException("something the adapter has never seen")))
.publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
}
@Test
void aPublishThatNeverCompletesIsBoundedByTheCallersTimeout() {
try (NatsJetStreamTransport transport =
new NatsJetStreamTransport(
"nats-primary",
1L,
profile(Optional.empty()),
(subject, deduplicationId, request) ->
new java.util.concurrent.CompletableFuture<>())) {
PublishResult result = await(transport.publish(requestWithTimeout(Duration.ofMillis(50))));
assertThat(result.completion())
.as("the caller's deadline used to be ignored entirely")
.isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.failure())
.hasValueSatisfying(
failure -> assertThat(failure.code()).isEqualTo("NATS_PUBLISH_TIMEOUT"));
}
}
@Test
void theReportedElapsedTimeIsMeasuredRatherThanZero() {
PublishResult result =
await(
failingWith(new java.util.concurrent.TimeoutException("no ack")).publish(request(64)));
assertThat(result.elapsed())
.as("every outcome reported Duration.ZERO, so latency evidence was fiction")
.isGreaterThanOrEqualTo(Duration.ZERO);
}
@Test
void aDeduplicationWindowSendsTheLogicalMessageIdSoARetryIsRecognised() {
confirming(Optional.of(Duration.ofMinutes(2)))
.publish(request(64))
.toCompletableFuture()
.join();
assertThat(capturedDeduplicationIds)
.as("a fresh id per attempt would make the window useless exactly when it is needed")
.singleElement()
.satisfies(id -> assertThat(id).isPresent());
}
@Test
void noDeduplicationWindowSendsNoDeduplicationId() {
confirming(Optional.empty()).publish(request(64)).toCompletableFuture().join();
assertThat(capturedDeduplicationIds).singleElement().satisfies(id -> assertThat(id).isEmpty());
}
@Test
void anOversizedPayloadIsRejectedBeforeTheStream() {
PublishResult result =
await(confirming(Optional.empty()).publish(request(PayloadPolicy.DEFAULT_MAX_BYTES + 1)));
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED);
}
@Test
void theAdapterDoesNotClaimANativeDeadLetter() {
assertThat(
confirming(Optional.empty())
.capabilities(new DestinationName("orders.v1"))
.capabilities()
.nativeDeadLetter())
.as("JetStream terminates at the delivery limit; it routes nowhere")
.isFalse();
}
@Test
void theAdapterAdvertisesDeduplicatedPublish() {
assertThat(
confirming(Optional.empty())
.capabilities(new DestinationName("orders.v1"))
.capabilities()
.deduplicatedPublish())
.isTrue();
}
@Test
void aClosedTransportStopsAcceptingWork() {
NatsJetStreamTransport transport = confirming(Optional.empty());
transport.close();
assertThat(transport.isAcceptingWork()).isFalse();
assertThat(await(transport.publish(request(64))).completion())
.isEqualTo(PublishCompletion.REJECTED);
}
@Test
void aRedeliveryIsRecognisedFromTheDeliveryCountNotTheSequence() {
NatsStreamPosition redelivered = new NatsStreamPosition("ORDERS", 42, 43, 2);
assertThat(POSITION.isRedelivery()).isFalse();
assertThat(redelivered.isRedelivery()).isTrue();
assertThat(redelivered.replayFrom())
.as("the stream sequence does not advance on a redelivery; the consumer sequence does")
.isEqualTo(POSITION.replayFrom());
}
@Test
void aSequenceBelowOneIsRejectedBecauseJetStreamCountsFromOne() {
assertThatThrownBy(() -> new NatsStreamPosition("ORDERS", 0, 1, 1))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aFailureCategoryIsAlwaysAttachedToAFailure() {
PublishResult result =
await(failingWith(new IllegalStateException("boom")).publish(request(64)));
assertThat(result.failure())
.hasValueSatisfying(
failure ->
assertThat(failure.category())
.as("an unclassified failure is transient, not a permanent business rejection")
.isEqualTo(FailureCategory.TRANSIENT_INFRASTRUCTURE));
}
private static NatsJetStreamProfile profile(Optional<Duration> deduplicationWindow) {
return new NatsJetStreamProfile(
"orders.created",
"ORDERS",
"orders-worker",
NatsAckMode.EXPLICIT,
Duration.ofSeconds(30),
5,
deduplicationWindow);
}
private static TransportPublishRequest request(int payloadBytes) {
return new TransportPublishRequest(
destinationProfile(), envelope(payloadBytes), PublishOptions.defaults());
}
private static TransportPublishRequest requestWithTimeout(Duration timeout) {
PublishOptions defaults = PublishOptions.defaults();
return new TransportPublishRequest(
destinationProfile(),
envelope(64),
new PublishOptions(timeout, defaults.confirmation(), defaults.deduplication()));
}
private static DestinationProfile destinationProfile() {
return new DestinationProfile(
new DestinationName("orders.v1"),
"nats-primary",
DestinationKind.EVENT_STREAM,
PhysicalDestination.natsStream("orders.created", "ORDERS"),
new SchemaPolicy(
ContentType.JSON,
SchemaCompatibility.BACKWARD,
Set.of(new MessageType("order.created"))),
DeliveryGuarantee.AT_LEAST_ONCE,
OrderingScope.NONE,
ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED,
ProducerPolicy.defaults(),
ConsumerPolicy.defaults("orders"),
RetryPolicy.none(),
DeadLetterPolicy.to(new DestinationName("orders.v1.dlq")),
PayloadPolicy.defaults(),
CapabilityTier.M1,
false,
false,
false);
}
private static MessageEnvelope<EncodedMessage> envelope(int payloadBytes) {
byte[] payload = new byte[payloadBytes];
java.util.Arrays.fill(payload, (byte) 'x');
return new MessageEnvelope<>(
MessageId.newId(),
new MessageType("order.created"),
new SchemaVersion(1),
NOW,
Optional.of(NOW),
new ProducerId("order-api"),
Optional.empty(),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
new EncodedMessage(payload, ContentType.JSON, Optional.empty()));
}
}
@@ -1,123 +0,0 @@
package dev.caskeleton.messaging.nats;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.nats.NatsMaxDeliverParkingWorkflow.Action;
import java.time.Duration;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class NatsMaxDeliverParkingTest {
private static NatsJetStreamProfile profile(int maxDeliver) {
return new NatsJetStreamProfile(
"orders.created",
"ORDERS",
"orders-worker",
NatsAckMode.EXPLICIT,
Duration.ofSeconds(30),
maxDeliver,
Optional.of(Duration.ofMinutes(2)));
}
private static NatsMaxDeliverParkingWorkflow workflow(int maxDeliver) {
return new NatsMaxDeliverParkingWorkflow(profile(maxDeliver));
}
@Test
void earlyDeliveriesGoToTheHandler() {
NatsMaxDeliverParkingWorkflow workflow = workflow(5);
assertThat(workflow.decide(1)).isEqualTo(Action.DELIVER_TO_HANDLER);
assertThat(workflow.decide(3)).isEqualTo(Action.DELIVER_TO_HANDLER);
}
@Test
void parkingHappensBeforeTheLimitNotAtIt() {
NatsMaxDeliverParkingWorkflow workflow = workflow(5);
assertThat(workflow.decide(4))
.as("the delivery that reaches maxDeliver is the one JetStream discards")
.isEqualTo(Action.PARK_TO_DEAD_LETTER);
}
@Test
void theLimitDeliveryItselfStillParksRatherThanBeingHandled() {
assertThat(workflow(5).decide(5)).isEqualTo(Action.PARK_TO_DEAD_LETTER);
}
@Test
void aDeliveryPastTheLimitIsReportedRatherThanMistakenForARedelivery() {
assertThat(workflow(5).decide(6))
.as("only reachable if the profile changed under a live consumer; nothing is recoverable")
.isEqualTo(Action.ALREADY_TERMINATED);
}
@Test
void theSourceIsOnlyTerminatedAfterTheDeadLetterPublishConfirms() {
NatsMaxDeliverParkingWorkflow workflow = workflow(5);
assertThat(workflow.maySettleSource(true)).isTrue();
assertThat(workflow.maySettleSource(false))
.as("terminating first discards the message on a broker that cannot redeliver it")
.isFalse();
}
@Test
void aProfileWithNoParkingHeadroomIsRefused() {
assertThatThrownBy(() -> profile(1))
.as("maxDeliver=1 leaves no delivery on which the platform could park the message")
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("headroom");
}
@Test
void aDeliveryCountBelowOneIsRejected() {
assertThatThrownBy(() -> workflow(5).decide(0)).isInstanceOf(IllegalArgumentException.class);
}
@Test
void theParkingThresholdIsOneBelowTheLimit() {
assertThat(workflow(7).parkingThreshold()).isEqualTo(6);
}
@Test
void ackNoneIsRefusedBecauseDeliveryIsTreatedAsCompletion() {
assertThatThrownBy(
() ->
new NatsJetStreamProfile(
"orders.created",
"ORDERS",
"orders-worker",
NatsAckMode.NONE,
Duration.ofSeconds(30),
5,
Optional.empty()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("forgotten");
}
@Test
void ackAllIsRefusedBecauseItSettlesWorkStillInFlight() {
assertThatThrownBy(
() ->
new NatsJetStreamProfile(
"orders.created",
"ORDERS",
"orders-worker",
NatsAckMode.ALL,
Duration.ofSeconds(30),
5,
Optional.empty()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("still in flight");
}
@Test
void onlyExplicitAcknowledgementCarriesAtLeastOnce() {
assertThat(NatsAckMode.EXPLICIT.supportsAtLeastOnce()).isTrue();
assertThat(NatsAckMode.ALL.supportsAtLeastOnce()).isFalse();
assertThat(NatsAckMode.NONE.supportsAtLeastOnce()).isFalse();
}
}
@@ -26,6 +26,9 @@ dependencies {
// Live-database certification. The reliability patterns are claims about transaction
// boundaries and uniqueness constraints, and only a real database can settle them.
testImplementation project(':messaging:messaging-testkit')
// Test-only. The relay is also driven through the real DefaultMessagePublisher: a fake publisher
// accepted the pre-encoded rows the real one re-encoded and rejected.
testImplementation project(':messaging:messaging-runtime-core')
integrationTestImplementation 'org.testcontainers:testcontainers-postgresql'
integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter'
integrationTestImplementation 'org.postgresql:postgresql'
@@ -506,22 +506,16 @@ class OutboxPostgresIT {
}
@Test
void theStoredRoutingKeyIsTheOneBothRelaysWouldUse() {
void theStoredRoutingKeyFallsBackToTheMessageId() {
OutboxRecord keyed =
record(OutboxCanonicalMetadata.none().withRoutingKeys("customer-42", "customer-42"));
OutboxRecord unkeyed = record(OutboxCanonicalMetadata.none());
appendInTransaction(keyed);
appendInTransaction(unkeyed);
DebeziumOutboxEventRouter router = new DebeziumOutboxEventRouter();
assertThat(routingKeyOf(keyed.messageId()))
.as("the CDC key used to be the destination, so every message on a topic shared a key")
.isEqualTo(router.routingKey(keyed))
.isEqualTo("customer-42");
assertThat(routingKeyOf(unkeyed.messageId()))
.as("the fallback is stated once, in the column, and the Java agrees with it")
.isEqualTo(router.routingKey(unkeyed))
.isEqualTo(unkeyed.messageId().value().toString());
assertThat(List.of(routingKeyOf(keyed.messageId()), routingKeyOf(unkeyed.messageId())))
.as("the fallback is stated once, in the column")
.containsExactly("customer-42", unkeyed.messageId().value().toString());
}
@Test
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.outbox;
import java.util.Arrays;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* What one outbox row looks like after Debezium's Event Router has transformed it.
*
* <p>Modelled explicitly so the CDC path can be tested without running Debezium. The property that
* matters is not that the transform is invoked but that its output carries the same identity,
* destination, and reserved headers the polling relay would have produced — and that is asserted by
* comparing this record against one built from the same row.
*
* @param topic the topic the row was routed to
* @param key the broker partition key, absent when the row is unkeyed
* @param payload the encoded payload
* @param headers the reserved headers carried alongside
*/
@SuppressWarnings("ArrayRecordComponent")
public record DebeziumMappedRecord(
String topic, Optional<String> key, byte[] payload, Map<String, String> headers) {
public DebeziumMappedRecord {
Objects.requireNonNull(key, "key must not be null");
Objects.requireNonNull(payload, "payload must not be null");
Objects.requireNonNull(headers, "headers must not be null");
if (topic == null || topic.isBlank()) {
throw new IllegalArgumentException("topic must not be blank");
}
payload = payload.clone();
headers = Map.copyOf(headers);
}
@Override
public byte[] payload() {
return payload.clone();
}
@Override
public boolean equals(Object other) {
return other instanceof DebeziumMappedRecord record
&& topic.equals(record.topic)
&& key.equals(record.key)
&& headers.equals(record.headers)
&& Arrays.equals(payload, record.payload);
}
@Override
public int hashCode() {
return Objects.hash(topic, key, headers, Arrays.hashCode(payload));
}
}
@@ -1,151 +0,0 @@
package dev.caskeleton.messaging.outbox;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
/**
* Maps outbox columns onto the headers Debezium's Outbox Event Router expects.
*
* <p>An optional alternative to the polling relay. CDC reads the database's write-ahead log instead
* of querying the table, which removes the polling interval and the lease contention — at the cost
* of an extra piece of infrastructure and its own failure modes.
*
* <p>The platform contract does not change with the transport. The router emits the same reserved
* headers the polling relay does, so a consumer cannot tell which one published a message, and
* switching between them is a deployment decision rather than a contract change.
*
* <p>The message key and the topic are two different questions and used to be answered by one
* column. {@code destination} routed the topic <em>and</em> became the key, so every message on a
* topic carried the same key, landed on one partition, and made keyed ordering a claim with no
* mechanism behind it. The key now comes from {@code routing_key}, the stored column that states
* the partition-key-or-message-id fallback once for both relays, and {@code destination} stays what
* it always was: routing metadata.
*
* <p>One canonical field has no header here: the schema subject. There is no reserved header name
* for it, and inventing one that only this path wrote would replace a symmetric gap with an
* asymmetric one — the polling relay would carry a schema reference on the envelope and the CDC
* relay a header no adapter reads. It stays a column that the polling relay resolves, and closing
* it means adding the name to {@code ReservedHeaders} and teaching both broker header mappers to
* write and read it.
*/
public final class DebeziumOutboxEventRouter {
/** The outbox column Debezium routes the topic by. */
public static final String ROUTE_BY_COLUMN = "destination";
/** The outbox column Debezium uses as the message key. */
public static final String KEY_COLUMN = "routing_key";
/** The outbox column carrying the logical message id. */
public static final String ID_COLUMN = "message_id";
/** The outbox column carrying the payload. */
public static final String PAYLOAD_COLUMN = "payload";
/**
* Returns the router configuration for a Debezium connector.
*
* @param topicPrefix the prefix routed topics are created under
* @return the connector properties
*/
public Map<String, String> connectorConfiguration(String topicPrefix) {
Objects.requireNonNull(topicPrefix, "topicPrefix must not be null");
Map<String, String> configuration = new LinkedHashMap<>();
configuration.put("transforms.outbox.type", "io.debezium.transforms.outbox.EventRouter");
configuration.put("transforms.outbox.table.field.event.id", ID_COLUMN);
configuration.put("transforms.outbox.table.field.event.key", KEY_COLUMN);
configuration.put("transforms.outbox.table.field.event.payload", PAYLOAD_COLUMN);
configuration.put("transforms.outbox.route.by.field", ROUTE_BY_COLUMN);
configuration.put(
"transforms.outbox.route.topic.replacement", topicPrefix + "${routedByValue}");
configuration.put(
"transforms.outbox.table.fields.additional.placement",
String.join(
",",
"message_type:header:" + ReservedHeaders.MESSAGE_TYPE,
"schema_version:header:" + ReservedHeaders.SCHEMA_VERSION,
"content_type:header:" + ReservedHeaders.CONTENT_TYPE,
"created_at:header:" + ReservedHeaders.PRODUCED_AT,
"destination:header:" + ReservedHeaders.ORIGIN_DESTINATION,
"producer:header:" + ReservedHeaders.PRODUCER,
"occurred_at:header:" + ReservedHeaders.OCCURRED_AT,
"correlation_id:header:" + ReservedHeaders.CORRELATION_ID,
"causation_id:header:" + ReservedHeaders.CAUSATION_ID,
"tenant:header:" + ReservedHeaders.TENANT,
"partition_key:header:" + ReservedHeaders.PARTITION_KEY,
"ordering_key:header:" + ReservedHeaders.ORDERING_KEY,
"traceparent:header:" + ReservedHeaders.TRACEPARENT,
"tracestate:header:" + ReservedHeaders.TRACESTATE,
"baggage:header:" + ReservedHeaders.BAGGAGE));
return Map.copyOf(configuration);
}
/**
* Returns the reserved headers a routed record must carry.
*
* <p>Used to assert that the CDC path and the polling path produce the same wire contract.
*
* @param record the outbox row
* @return the reserved headers
*/
public Map<String, String> reservedHeaders(OutboxRecord record) {
Objects.requireNonNull(record, "record must not be null");
Map<String, String> headers = new LinkedHashMap<>();
headers.put(ReservedHeaders.MESSAGE_ID, record.messageId().value().toString());
headers.put(ReservedHeaders.MESSAGE_TYPE, record.messageType().value());
headers.put(ReservedHeaders.SCHEMA_VERSION, Integer.toString(record.schemaVersion().value()));
headers.put(ReservedHeaders.CONTENT_TYPE, record.contentType().value());
headers.put(ReservedHeaders.PRODUCED_AT, record.createdAt().toString());
headers.put(ReservedHeaders.ORIGIN_DESTINATION, record.destination().value());
// Absent stays absent. Writing an empty string for a column the row does not have would make a
// message that carries no tenant indistinguishable from one whose tenant is the empty string,
// and the consumer would have to know which of the two this platform meant.
OutboxCanonicalMetadata metadata = record.metadata();
metadata.producer().ifPresent(value -> headers.put(ReservedHeaders.PRODUCER, value.value()));
metadata
.occurredAt()
.ifPresent(value -> headers.put(ReservedHeaders.OCCURRED_AT, value.toString()));
metadata
.correlationId()
.ifPresent(value -> headers.put(ReservedHeaders.CORRELATION_ID, value.value()));
metadata
.causationId()
.ifPresent(
value -> headers.put(ReservedHeaders.CAUSATION_ID, value.value().value().toString()));
metadata.tenant().ifPresent(value -> headers.put(ReservedHeaders.TENANT, value.tenantId()));
metadata.partitionKey().ifPresent(value -> headers.put(ReservedHeaders.PARTITION_KEY, value));
metadata.orderingKey().ifPresent(value -> headers.put(ReservedHeaders.ORDERING_KEY, value));
metadata
.traceContext()
.traceparent()
.ifPresent(value -> headers.put(ReservedHeaders.TRACEPARENT, value));
metadata
.traceContext()
.tracestate()
.ifPresent(value -> headers.put(ReservedHeaders.TRACESTATE, value));
metadata
.traceContext()
.baggage()
.ifPresent(value -> headers.put(ReservedHeaders.BAGGAGE, value));
return Map.copyOf(headers);
}
/**
* Returns the key a routed record carries.
*
* <p>The same value the {@code routing_key} column computes, stated here so a test can compare
* the two rather than trusting that the SQL and the Java agree.
*
* @param record the outbox row
* @return the broker message key
*/
public String routingKey(OutboxRecord record) {
Objects.requireNonNull(record, "record must not be null");
return record.metadata().partitionKey().orElseGet(() -> record.messageId().value().toString());
}
}
@@ -1,67 +0,0 @@
package dev.caskeleton.messaging.outbox;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.util.Objects;
/**
* Which relay a deployment uses, and the rule that only one of them may be active.
*
* <p>Running the polling relay and the CDC relay together publishes every row twice. Both are
* correct in isolation and neither can see the other: the poller leases and marks rows, while
* Debezium reads the write-ahead log and never observes the lease at all. The duplicate is
* therefore invisible in the outbox table and only shows up downstream, which is why the
* incompatibility is enforced at startup instead of documented.
*
* @param mode which relay publishes outbox rows
* @param topicPrefix the prefix CDC-routed topics are created under
* @param aggregateIdAsPartitionKey whether the aggregate id becomes the broker partition key
*/
public record DebeziumOutboxProfile(
RelayMode mode, String topicPrefix, boolean aggregateIdAsPartitionKey) {
/** How outbox rows reach the broker. */
public enum RelayMode {
/** The in-process relay leases and publishes rows. */
POLLING,
/** Debezium reads the write-ahead log and routes rows. */
CHANGE_DATA_CAPTURE
}
public DebeziumOutboxProfile {
Objects.requireNonNull(mode, "mode must not be null");
Objects.requireNonNull(topicPrefix, "topicPrefix must not be null");
if (mode == RelayMode.CHANGE_DATA_CAPTURE && topicPrefix.isBlank()) {
throw new IllegalArgumentException("a CDC profile must name a topic prefix");
}
}
/**
* Returns the default polling profile.
*
* @return the polling profile
*/
public static DebeziumOutboxProfile polling() {
return new DebeziumOutboxProfile(RelayMode.POLLING, "", false);
}
/**
* Refuses a configuration that would run both relays at once.
*
* @param pollingRelayEnabled whether the in-process relay bean is active
* @throws MessagingConfigurationException when both relays would run
*/
public void requireExactlyOneRelay(boolean pollingRelayEnabled) {
if (mode == RelayMode.CHANGE_DATA_CAPTURE && pollingRelayEnabled) {
throw new MessagingConfigurationException(
"DUPLICATE_OUTBOX_RELAY",
"the CDC relay and the polling relay are both enabled; Debezium never observes the "
+ "polling lease, so every row would be published twice");
}
if (mode == RelayMode.POLLING && !pollingRelayEnabled) {
throw new MessagingConfigurationException(
"NO_OUTBOX_RELAY",
"the profile selects the polling relay but no relay is enabled, so outbox rows would "
+ "accumulate without ever being published");
}
}
}
@@ -1,79 +0,0 @@
package dev.caskeleton.messaging.outbox;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* Produces what Debezium's Event Router will emit for an outbox row.
*
* <p>Exists so the CDC path is testable without Debezium running. The property worth proving is
* that a consumer cannot tell which relay published a message: same logical id, same destination,
* same reserved headers. Building the expected record here and comparing it against the polling
* relay's output is what makes "switching relays is a deployment decision, not a contract change"
* an assertion rather than a claim.
*
* <p>The message id comes from the row's {@code message_id} column, never from Debezium's own event
* id. Debezium mints a fresh event id per change record, so using it would break identity across a
* CDC re-snapshot — exactly the scenario where identity matters most.
*
* <p>The reserved headers come from {@link DebeziumOutboxEventRouter} rather than being rebuilt
* here. Two lists of the same headers is how the connector's configuration and the expectation this
* class encodes come to disagree, and the disagreement would be invisible: the test compares this
* output against the polling relay's, so it would pass while the connector emitted something else.
*/
public final class DebeziumOutboxRecordMapper {
private final String topicPrefix;
private final boolean aggregateIdAsPartitionKey;
private final DebeziumOutboxEventRouter router = new DebeziumOutboxEventRouter();
/**
* Creates a mapper from a CDC profile.
*
* @param profile the outbox relay profile
*/
public DebeziumOutboxRecordMapper(DebeziumOutboxProfile profile) {
Objects.requireNonNull(profile, "profile must not be null");
this.topicPrefix = profile.topicPrefix();
this.aggregateIdAsPartitionKey = profile.aggregateIdAsPartitionKey();
}
/**
* Maps one outbox row to its routed record.
*
* @param record the outbox row
* @return the record a CDC relay would emit
*/
public DebeziumMappedRecord map(OutboxRecord record) {
Objects.requireNonNull(record, "record must not be null");
// Application headers first, canonical headers second, and the canonical ones win. The row's
// header map is application data; a row that wrote `msg.id` into it would otherwise overwrite
// the identity the platform put there, and the consumer trusts the last such header it sees.
// The write path refuses reserved names outright — this order is the second lock on the same
// door, because a CDC connector reading the table directly never passes through that check.
Map<String, String> headers = new LinkedHashMap<>(record.headers());
headers.keySet().removeIf(ReservedHeaders::isReserved);
headers.putAll(router.reservedHeaders(record));
return new DebeziumMappedRecord(
topicPrefix + record.destination().value(),
partitionKey(record),
record.payload(),
headers);
}
private Optional<String> partitionKey(OutboxRecord record) {
if (!aggregateIdAsPartitionKey) {
return Optional.empty();
}
// The same value the polling relay would use and the same value the `routing_key` column
// computes, so both relays land the same message on the same partition and neither reorders a
// keyed stream.
return Optional.of(router.routingKey(record));
}
}
@@ -1,43 +0,0 @@
# Debezium Outbox Event Router configuration for the messaging_outbox table.
#
# Optional. Enable this OR the in-process polling relay, never both: Debezium reads the
# write-ahead log and never observes the polling lease, so with both running every row is
# published twice and the duplicate is invisible in the outbox table itself.
#
# Operating the Debezium connector — its offsets, its snapshots, its slot — is out of scope for
# this module. What is in scope is that a message routed by CDC is indistinguishable from one
# published by the polling relay: same logical id, same destination, same reserved headers.
name=messaging-outbox-connector
connector.class=io.debezium.connector.postgresql.PostgresConnector
# Only the outbox table. A wider include list turns every business table change into a message.
table.include.list=public.messaging_outbox
# The row is deleted or marked after routing; the tombstone would otherwise reach the topic as a
# null-payload record that consumers must special-case.
tombstones.on.delete=false
transforms=outbox
transforms.outbox.type=io.debezium.transforms.outbox.EventRouter
# Identity comes from the row's own message_id, not from Debezium's per-change event id. A CDC
# re-snapshot mints new event ids for rows that already published, which would break identity in
# exactly the situation where it matters most.
transforms.outbox.table.field.event.id=message_id
transforms.outbox.table.field.event.key=destination
transforms.outbox.table.field.event.payload=payload
transforms.outbox.table.field.event.timestamp=created_at
transforms.outbox.route.by.field=destination
transforms.outbox.route.topic.replacement=${routedByValue}
# The reserved headers a consumer relies on, carried through the transform so the CDC path emits
# the same envelope the polling relay does.
transforms.outbox.table.fields.additional.placement=message_type:header:msg.type,schema_version:header:msg.schema-version,content_type:header:msg.content-type,message_id:header:msg.id
# Publisher idempotence and full acknowledgement: a CDC relay that loses a record cannot replay it
# without re-reading the log from an earlier offset, which would republish everything after it.
producer.override.enable.idempotence=true
producer.override.acks=all
producer.override.max.in.flight.requests.per.connection=5
@@ -1,199 +0,0 @@
package dev.caskeleton.messaging.outbox;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.outbox.DebeziumOutboxProfile.RelayMode;
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxStatus;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class DebeziumOutboxRecordMapperTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final MessageId MESSAGE_ID = MessageId.newId();
private static OutboxRecord record(Map<String, String> headers) {
return record(headers, OutboxCanonicalMetadata.none());
}
private static OutboxRecord record(
Map<String, String> headers, OutboxCanonicalMetadata metadata) {
return new OutboxRecord(
MESSAGE_ID,
new DestinationName("orders.v1"),
new MessageType("order.created"),
new SchemaVersion(1),
ContentType.JSON,
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
headers,
metadata,
NOW,
OutboxStatus.PENDING,
0,
Optional.empty(),
Optional.empty());
}
private static DebeziumOutboxRecordMapper mapper(boolean aggregateIdAsPartitionKey) {
return new DebeziumOutboxRecordMapper(
new DebeziumOutboxProfile(
RelayMode.CHANGE_DATA_CAPTURE, "prod.", aggregateIdAsPartitionKey));
}
@Test
void theRoutedTopicIsThePrefixedDestination() {
assertThat(mapper(false).map(record(Map.of())).topic()).isEqualTo("prod.orders.v1");
}
@Test
void theLogicalMessageIdSurvivesTheCdcPath() {
DebeziumMappedRecord mapped = mapper(false).map(record(Map.of()));
assertThat(mapped.headers().get(ReservedHeaders.MESSAGE_ID))
.as("Debezium mints a fresh event id per change record; using it would break identity")
.isEqualTo(MESSAGE_ID.value().toString());
}
@Test
void everyReservedHeaderAConsumerNeedsIsCarried() {
Map<String, String> headers = mapper(false).map(record(Map.of())).headers();
assertThat(headers)
.containsKeys(
ReservedHeaders.MESSAGE_ID,
ReservedHeaders.MESSAGE_TYPE,
ReservedHeaders.SCHEMA_VERSION,
ReservedHeaders.CONTENT_TYPE,
ReservedHeaders.PRODUCED_AT);
}
@Test
void applicationHeadersOnTheRowArePreserved() {
DebeziumMappedRecord mapped = mapper(false).map(record(Map.of("x-tenant-tier", "gold")));
assertThat(mapped.headers()).containsEntry("x-tenant-tier", "gold");
}
@Test
void anUnkeyedProfileEmitsNoPartitionKey() {
assertThat(mapper(false).map(record(Map.of())).key()).isEmpty();
}
@Test
void aKeyedProfileUsesTheSamePartitionKeyThePollingRelayWouldHave() {
DebeziumMappedRecord mapped =
mapper(true)
.map(
record(
Map.of(),
OutboxCanonicalMetadata.none().withRoutingKeys("customer-42", "customer-42")));
assertThat(mapped.key())
.as("a different key would send the two relays' messages to different partitions")
.hasValue("customer-42");
}
@Test
void aKeyedProfileFallsBackToTheMessageIdWhenTheRowHasNoPartitionKey() {
assertThat(mapper(true).map(record(Map.of())).key())
.as("the fallback the routing_key column computes, stated in one place for both relays")
.hasValue(MESSAGE_ID.value().toString());
}
@Test
void theCanonicalColumnsBecomeReservedHeaders() {
OutboxCanonicalMetadata metadata =
OutboxCanonicalMetadata.none()
.withProducer(new dev.caskeleton.messaging.api.ProducerId("order-api"))
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"))
.withRoutingKeys("customer-42", "customer-42");
Map<String, String> headers = mapper(false).map(record(Map.of(), metadata)).headers();
assertThat(headers)
.as("a relay that drops these makes the publish path part of the message's meaning")
.containsEntry(ReservedHeaders.PRODUCER, "order-api")
.containsEntry(ReservedHeaders.TENANT, "acme")
.containsEntry(ReservedHeaders.PARTITION_KEY, "customer-42")
.containsEntry(ReservedHeaders.ORDERING_KEY, "customer-42")
.containsEntry(ReservedHeaders.ORIGIN_DESTINATION, "orders.v1");
}
@Test
void aColumnTheRowDoesNotCarryProducesNoHeaderAtAll() {
assertThat(mapper(false).map(record(Map.of())).headers())
.as("an empty string would be indistinguishable from a tenant literally named ''")
.doesNotContainKeys(
ReservedHeaders.TENANT, ReservedHeaders.CORRELATION_ID, ReservedHeaders.TRACEPARENT);
}
@Test
void aForgedReservedHeaderOnTheRowCannotOverwriteTheCanonicalOne() {
Map<String, String> forged =
Map.of(ReservedHeaders.MESSAGE_ID, "00000000-0000-7000-8000-000000000000");
assertThat(mapper(false).map(record(forged)).headers())
.as("a CDC connector reads the table directly and never passes the write-path check")
.containsEntry(ReservedHeaders.MESSAGE_ID, MESSAGE_ID.value().toString());
}
@Test
void theRoutedKeyIsNotTheTopicName() {
// Literals, not the class's own constants: comparing a configuration value against the constant
// that produced it asserts that the router agrees with itself, which it always will.
assertThat(new DebeziumOutboxEventRouter().connectorConfiguration("prod."))
.as("keying by destination puts every message on a topic onto one partition")
.containsEntry("transforms.outbox.table.field.event.key", "routing_key")
.containsEntry("transforms.outbox.route.by.field", "destination");
}
@Test
void thePayloadIsUnchangedByTheTransform() {
assertThat(mapper(false).map(record(Map.of())).payload())
.isEqualTo("{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8));
}
@Test
void runningBothRelaysAtOnceIsRefused() {
DebeziumOutboxProfile cdc =
new DebeziumOutboxProfile(RelayMode.CHANGE_DATA_CAPTURE, "p.", false);
assertThatThrownBy(() -> cdc.requireExactlyOneRelay(true))
.as("Debezium never sees the polling lease, so every row would publish twice")
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("twice");
}
@Test
void runningNoRelayAtAllIsAlsoRefused() {
assertThatThrownBy(() -> DebeziumOutboxProfile.polling().requireExactlyOneRelay(false))
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("accumulate");
}
@Test
void exactlyOneRelayIsAccepted() {
assertThatCode(() -> DebeziumOutboxProfile.polling().requireExactlyOneRelay(true))
.doesNotThrowAnyException();
}
@Test
void aCdcProfileMustNameATopicPrefix() {
assertThatThrownBy(() -> new DebeziumOutboxProfile(RelayMode.CHANGE_DATA_CAPTURE, " ", false))
.isInstanceOf(IllegalArgumentException.class);
}
}
@@ -8,6 +8,11 @@ import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee;
import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationCapabilities;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.messaging.api.error.FailureCategory;
@@ -19,11 +24,37 @@ import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.InFlightLimiter;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import dev.caskeleton.messaging.policy.PayloadLimitGuard;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.reliability.OutboxLease;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxRepository;
import dev.caskeleton.messaging.reliability.OutboxStatus;
import dev.caskeleton.messaging.reliability.OutboxTransitionResult;
import dev.caskeleton.messaging.runtime.DefaultMessagePublisher;
import dev.caskeleton.messaging.runtime.DestinationProfileRegistry;
import dev.caskeleton.messaging.runtime.TransportMessagingRuntime;
import dev.caskeleton.messaging.schema.MessageCodec;
import dev.caskeleton.messaging.schema.MessageCodecRegistry;
import dev.caskeleton.messaging.schema.RawBytesMessageCodec;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import dev.caskeleton.messaging.security.DestinationAccessPolicy;
import dev.caskeleton.messaging.transport.DefaultMessagingRuntimeRegistry;
import dev.caskeleton.messaging.transport.MessagingTransport;
import dev.caskeleton.messaging.transport.TransportConsumerRegistration;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import dev.caskeleton.messaging.transport.TransportPublishResult;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.Instant;
@@ -32,6 +63,7 @@ import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import org.junit.jupiter.api.Test;
@@ -162,6 +194,35 @@ class OutboxRelayTest {
assertThat(envelope.schemaVersion()).isEqualTo(new SchemaVersion(1));
}
@Test
void aRowRelayedThroughTheRealPublisherIsMarkedPublished() {
// given
OutboxRecord record = OutboxFixtures.pending();
repository.append(record);
// when
relay(RealPublisher.over(new CapturingTransport())).runOnce(NOW);
// then
assertThat(repository.find(record.messageId()).orElseThrow().status())
.as("re-encoding the stored bytes made the codec refuse them and ended every row FAILED")
.isEqualTo(OutboxStatus.PUBLISHED);
}
@Test
void aRowRelayedThroughTheRealPublisherReachesTheTransportWithItsStoredBytes() {
// given
OutboxRecord record = OutboxFixtures.pending();
repository.append(record);
CapturingTransport transport = new CapturingTransport();
// when
relay(RealPublisher.over(transport)).runOnce(NOW);
// then
assertThat(transport.payloads()).containsExactly(record.payload());
}
private OutboxRelay relay(MessagePublisher publisher) {
return new OutboxRelay(
repository,
@@ -480,3 +541,110 @@ final class RecordingOutboxPublisher implements MessagePublisher {
};
}
}
/** The platform's own publisher over a stub transport, registered for the fixture's destination. */
final class RealPublisher {
private static final DestinationName ORDERS = new DestinationName("order-events");
private RealPublisher() {}
static DefaultMessagePublisher over(MessagingTransport transport) {
DefaultMessagingRuntimeRegistry runtimes = new DefaultMessagingRuntimeRegistry();
runtimes.install(new TransportMessagingRuntime("fake", 1, transport));
// A real codec. Like every codec it refuses a payload that is not its own type, which is what
// an already-encoded row is to it.
MessageCodec raw = new RawBytesMessageCodec();
return new DefaultMessagePublisher(
DestinationProfileRegistry.of(Map.of(ORDERS, profile())),
new DestinationAccessPolicy(Set.of(ORDERS), Set.of(), Set.of()),
new MessageCodecRegistry() {
@Override
public Optional<MessageCodec> find(ContentType contentType) {
return Optional.of(raw);
}
@Override
public MessageCodec defaultCodec() {
return raw;
}
},
new MessagingAdmissionController(
new PayloadLimitGuard(PayloadPolicy.defaults()),
new InFlightLimiter(4, Duration.ofSeconds(1))),
runtimes,
transport);
}
private static DestinationProfile profile() {
return new DestinationProfile(
ORDERS,
"fake",
DestinationKind.EVENT_STREAM,
PhysicalDestination.kafkaTopic("order.events.v1"),
new SchemaPolicy(
ContentType.JSON,
SchemaCompatibility.BACKWARD_TRANSITIVE,
Set.of(new MessageType("order.created"))),
DeliveryGuarantee.AT_LEAST_ONCE,
OrderingScope.NONE,
ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED,
ProducerPolicy.defaults(),
ConsumerPolicy.defaults("order-projection"),
RetryPolicy.none(),
DeadLetterPolicy.disabled(),
PayloadPolicy.defaults(),
CapabilityTier.M1,
false,
false,
false);
}
}
/** A transport that confirms every publish and keeps the bytes it was handed. */
final class CapturingTransport implements MessagingTransport {
private final List<byte[]> payloads = new ArrayList<>();
List<byte[]> payloads() {
return List.copyOf(payloads);
}
@Override
public CompletionStage<TransportPublishResult> publish(TransportPublishRequest request) {
payloads.add(request.envelope().payload().bytes());
return CompletableFuture.completedFuture(
new TransportPublishResult(
new PublishResult(
PublishCompletion.CONFIRMED,
PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK),
RoutingOutcome.ROUTED,
Optional.empty(),
1,
Duration.ZERO,
Optional.empty())));
}
@Override
public TransportConsumerRegistration register(TransportConsumerSpec spec) {
throw new UnsupportedOperationException("the relay only publishes");
}
@Override
public DestinationCapabilities capabilities(DestinationName destination) {
throw new UnsupportedOperationException("the relay asks for no publish option");
}
@Override
public String brokerName() {
return "fake";
}
@Override
public long generation() {
return 1;
}
@Override
public void close() {}
}
@@ -1,14 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-observability')
api project(':messaging:messaging-security')
api project(':messaging:messaging-admin-api')
}
@@ -1,89 +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
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
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.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
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.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
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=
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import dev.caskeleton.messaging.api.publish.BrokerPosition;
import java.util.Map;
/**
* A Pulsar message id, decomposed into its parts.
*
* <p>Kept as four fields rather than the opaque {@code MessageId} string so a diagnostic can be
* read without a Pulsar client to parse it. {@code batchIndex} is the part that surprises people: a
* batched message's id is shared by every message in the batch, so the index is what makes an
* individual message addressable at all.
*
* @param ledgerId the ledger holding the entry
* @param entryId the entry within the ledger
* @param partition the partition index, or -1 for a non-partitioned topic
* @param batchIndex the index within a batch, or -1 when the message was not batched
*/
public record PulsarMessagePosition(long ledgerId, long entryId, int partition, int batchIndex)
implements BrokerPosition {
/** The value used where a topic is not partitioned or a message is not batched. */
public static final int NOT_APPLICABLE = -1;
@Override
public String broker() {
return "pulsar";
}
@Override
public Map<String, String> diagnosticAttributes() {
return Map.of(
"ledgerId", Long.toString(ledgerId),
"entryId", Long.toString(entryId),
"partition", Integer.toString(partition),
"batchIndex", Integer.toString(batchIndex));
}
/**
* Returns the canonical Pulsar message id rendering.
*
* @return the message id as Pulsar prints it
*/
public String toMessageId() {
return batchIndex == NOT_APPLICABLE
? "%d:%d:%d".formatted(ledgerId, entryId, partition)
: "%d:%d:%d:%d".formatted(ledgerId, entryId, partition, batchIndex);
}
}
@@ -1,275 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import dev.caskeleton.messaging.api.destination.DestinationCapabilities;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessagingCapabilities;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import dev.caskeleton.messaging.transport.MessagingTransport;
import dev.caskeleton.messaging.transport.TransportConsumerRegistration;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import dev.caskeleton.messaging.transport.TransportPublishResult;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.Function;
/**
* The Experimental Pulsar adapter.
*
* <p>This is an Experimental contract seam, not a Stable adapter. It exercises the transport SPI
* against a send operation the application supplies; it does not ship a Pulsar client bridge,
* producer lifecycle, or reconnection. Only a failure the operation reports as a {@link
* PulsarPreSendRejection} is treated as definitely not transmitted — every other failure,
* recognised or not, is ambiguous.
*
* <p>Disabled unless explicitly enabled. Experimental means the contract suite has been run but the
* live-broker certification has not, so the adapter must never become load-bearing because a
* default switched it on.
*
* <p>Pulsar's send future resolves with a {@code MessageId} once the broker has persisted the
* message to its configured number of bookies, which is genuine replication evidence rather than a
* receipt. A send that fails with a timeout is reported {@code AMBIGUOUS}: the write may have
* reached the bookies and only the acknowledgement been lost, and treating that as a rejection is
* how a message gets published twice.
*/
public final class PulsarMessagingTransport implements MessagingTransport {
/** What this adapter can prove today. Transactions stay false while Experimental. */
private static final MessagingCapabilities SHARED_CAPABILITIES =
new MessagingCapabilities(
true, true, true, true, false, false, true, true, false, false, true, true);
private static final MessagingCapabilities KEY_SHARED_CAPABILITIES =
new MessagingCapabilities(
true, true, true, true, false, true, true, true, false, false, true, true);
private final String brokerName;
private final long generation;
private final PulsarProfile profile;
private final PulsarSendOperation send;
private final Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory;
private final AtomicBoolean closed = new AtomicBoolean();
/**
* Creates a publish-only transport.
*
* @param brokerName the logical broker name
* @param generation the runtime generation
* @param profile the Pulsar destination settings
* @param send the producer send operation
*/
public PulsarMessagingTransport(
String brokerName, long generation, PulsarProfile profile, PulsarSendOperation send) {
this(
brokerName,
generation,
profile,
send,
spec -> {
throw new MessagingCapabilityUnavailableException(
"PULSAR_CONSUMER_NOT_CONFIGURED",
"this Pulsar transport was created without a consumer factory");
});
}
/**
* Creates a transport with a consumer factory.
*
* @param brokerName the logical broker name
* @param generation the runtime generation
* @param profile the Pulsar destination settings
* @param send the producer send operation
* @param consumerFactory builds a consumer registration for a spec
*/
public PulsarMessagingTransport(
String brokerName,
long generation,
PulsarProfile profile,
PulsarSendOperation send,
Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory) {
this.brokerName = Objects.requireNonNull(brokerName, "brokerName must not be null");
this.generation = generation;
this.profile = Objects.requireNonNull(profile, "profile must not be null");
this.send = Objects.requireNonNull(send, "send must not be null");
this.consumerFactory = Objects.requireNonNull(consumerFactory, "consumerFactory is required");
}
@Override
public CompletionStage<TransportPublishResult> publish(TransportPublishRequest request) {
Objects.requireNonNull(request, "request must not be null");
if (closed.get()) {
return completed(
rejectedLocally("PULSAR_TRANSPORT_CLOSED", "the transport is shutting down"));
}
int size = request.envelope().payload().size();
int limit = request.profile().payload().maxBytes();
if (size > limit) {
return completed(
rejectedLocally(
"PAYLOAD_TOO_LARGE", "encoded payload is " + size + " bytes, limit is " + limit));
}
// The caller's own deadline, honoured rather than ignored: a stalled send used to hold the
// caller for whatever the SDK's default was, whatever the caller had asked for.
long startedAt = System.nanoTime();
return send.send(profile.topic(), request)
.toCompletableFuture()
.orTimeout(
request.options().timeout().toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS)
.handle(
(position, failure) ->
failure == null
? confirmed(position, elapsedSince(startedAt))
: classify(failure, elapsedSince(startedAt)))
.thenApply(TransportPublishResult::new);
}
@Override
public TransportConsumerRegistration register(TransportConsumerSpec spec) {
Objects.requireNonNull(spec, "spec must not be null");
if (closed.get()) {
throw new MessagingCapabilityUnavailableException(
"PULSAR_TRANSPORT_CLOSED", "the transport is shutting down");
}
return consumerFactory.apply(spec);
}
@Override
public DestinationCapabilities capabilities(DestinationName destination) {
MessagingCapabilities capabilities =
profile.mode().subscriptionType() == PulsarSubscriptionType.KEY_SHARED
? KEY_SHARED_CAPABILITIES
: SHARED_CAPABILITIES;
return new DestinationCapabilities(destination, brokerName, capabilities);
}
@Override
public String brokerName() {
return brokerName;
}
@Override
public long generation() {
return generation;
}
@Override
public void close() {
closed.set(true);
}
/**
* Reports whether the transport is still accepting work.
*
* @return true until close
*/
public boolean isAcceptingWork() {
return !closed.get();
}
private static Duration elapsedSince(long startedAtNanos) {
return Duration.ofNanos(System.nanoTime() - startedAtNanos);
}
private static PublishResult confirmed(PulsarMessagePosition position, Duration elapsed) {
return new PublishResult(
PublishCompletion.CONFIRMED,
// The send future resolves only after the entry is persisted to the configured bookies, so
// this is replication evidence rather than a broker receipt.
new PublishEvidence(
true,
TransmissionEvidence.TRANSMITTED,
true,
ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK),
RoutingOutcome.ROUTED,
Optional.of(position),
1,
elapsed,
Optional.empty());
}
/**
* Decides what a send failure means, from typed signals only.
*
* <p>Classification used to read the exception's class simple name: {@code "Timeout"} meant
* ambiguous, anything else meant rejected. A class name is not part of Pulsar's contract — it
* changes between client versions — and defaulting the unknown case to {@code REJECTED} tells the
* caller nothing was transmitted, which is how the same entry is published to the bookies twice.
*/
private static PublishResult classify(Throwable failure, Duration elapsed) {
Throwable cause =
failure instanceof java.util.concurrent.CompletionException ? failure.getCause() : failure;
if (cause instanceof PulsarPreSendRejection rejection) {
return new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.CONFIGURATION, rejection.code(), rejection.getMessage())));
}
boolean timedOut = cause instanceof java.util.concurrent.TimeoutException;
return new PublishResult(
PublishCompletion.AMBIGUOUS,
new PublishEvidence(
true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.TRANSIENT_INFRASTRUCTURE,
timedOut ? "PULSAR_SEND_TIMEOUT" : "PULSAR_SEND_OUTCOME_UNKNOWN",
timedOut
? "the send timed out; the broker may already hold the message"
: "the send failed in a way this adapter does not classify; the broker may"
+ " already hold the message")));
}
private static TransportPublishResult rejectedLocally(String code, String message) {
return new TransportPublishResult(
new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
Duration.ZERO,
Optional.of(FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message))));
}
private static CompletionStage<TransportPublishResult> completed(TransportPublishResult result) {
return CompletableFuture.completedFuture(result);
}
/** The producer send, isolated so the adapter is testable without a broker. */
@FunctionalInterface
public interface PulsarSendOperation {
/**
* Sends one encoded message.
*
* @param topic the Pulsar topic
* @param request the publish request
* @return a stage completing with the broker position
*/
CompletionStage<PulsarMessagePosition> send(String topic, TransportPublishRequest request);
}
}
@@ -1,65 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import java.util.Objects;
/**
* The one signal that lets this adapter report {@code REJECTED / NOT_TRANSMITTED}.
*
* <p>Classification used to work by reading the exception's class simple name and matching
* substrings — {@code "Timeout"} meant ambiguous, anything else meant rejected. Two things are
* wrong with that. A class name is not part of any SDK's contract: it changes between versions, and
* an unrelated exception whose name happens to contain the substring is misread. And defaulting the
* unknown case to {@code REJECTED} tells the caller nothing was transmitted, so a caller that
* republishes under a new identity duplicates a message the server may well have stored.
*
* <p>The send operation throws this only when it knows the send never left the client: an argument
* the SDK refused, a producer that was already closed, a topic the client could not resolve.
* Everything else — including anything the adapter does not recognise — is ambiguous, and ambiguity
* is the honest answer when the write may have landed.
*/
public final class PulsarPreSendRejection extends RuntimeException {
private static final long serialVersionUID = 1L;
private final String code;
/**
* Creates a pre-send rejection.
*
* @param code the sanitised platform code for the refusal
* @param message a sanitised description
*/
public PulsarPreSendRejection(String code, String message) {
super(message);
this.code = requireCode(code);
}
/**
* Creates a pre-send rejection wrapping the SDK's own exception.
*
* @param code the sanitised platform code for the refusal
* @param message a sanitised description
* @param cause the SDK exception that proves the send never started
*/
public PulsarPreSendRejection(String code, String message, Throwable cause) {
super(message, cause);
this.code = requireCode(code);
}
private static String requireCode(String code) {
Objects.requireNonNull(code, "code must not be null");
if (code.isBlank()) {
throw new IllegalArgumentException("code must not be blank");
}
return code;
}
/**
* The sanitised code reported to the caller.
*
* @return the code
*/
public String code() {
return code;
}
}
@@ -1,80 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
/**
* The Pulsar-side settings for one destination.
*
* <p>{@code negativeAckRedeliveryDelay} is the platform's retry hook on Pulsar. Pulsar has no retry
* topic of its own in this adapter, so a failed handler negatively acknowledges and the broker
* redelivers after this delay — which means the delay <em>is</em> the backoff, and setting it to
* zero converts a failing handler into a spin loop against the broker.
*
* <p>{@code ackTimeout} is deliberately optional and off by default. It redelivers any message the
* consumer has not acknowledged in time, which looks like a safety net and behaves like a duplicate
* generator for handlers that are simply slow.
*
* @param topic the fully-qualified Pulsar topic
* @param subscription the durable subscription name
* @param mode the subscription type and acknowledgement style
* @param negativeAckRedeliveryDelay how long the broker waits after a negative acknowledgement
* @param ackTimeout redelivers unacknowledged messages after this long, when set
* @param maxRedeliverCount how many redeliveries before the message is parked
*/
public record PulsarProfile(
String topic,
String subscription,
PulsarSubscriptionMode mode,
Duration negativeAckRedeliveryDelay,
Optional<Duration> ackTimeout,
int maxRedeliverCount) {
/** Pulsar's own floor for an acknowledgement timeout. */
public static final Duration MINIMUM_ACK_TIMEOUT = Duration.ofSeconds(10);
public PulsarProfile {
Objects.requireNonNull(mode, "mode must not be null");
Objects.requireNonNull(negativeAckRedeliveryDelay, "negativeAckRedeliveryDelay is required");
Objects.requireNonNull(ackTimeout, "ackTimeout must not be null");
requireText(topic, "topic");
requireText(subscription, "subscription");
if (negativeAckRedeliveryDelay.isNegative() || negativeAckRedeliveryDelay.isZero()) {
throw new IllegalArgumentException(
"negativeAckRedeliveryDelay must be positive; zero turns a failing handler into a spin "
+ "loop against the broker");
}
if (maxRedeliverCount < 1) {
throw new IllegalArgumentException("maxRedeliverCount must be at least 1");
}
if (ackTimeout.isPresent() && ackTimeout.get().compareTo(MINIMUM_ACK_TIMEOUT) < 0) {
throw new IllegalArgumentException(
"ackTimeout below %s is rejected by Pulsar itself".formatted(MINIMUM_ACK_TIMEOUT));
}
}
/**
* Returns a shared-subscription profile with the platform defaults.
*
* @param topic the Pulsar topic
* @param subscription the subscription name
* @return the profile
*/
public static PulsarProfile shared(String topic, String subscription) {
return new PulsarProfile(
topic,
subscription,
PulsarSubscriptionMode.shared(),
Duration.ofSeconds(30),
Optional.empty(),
5);
}
private static void requireText(String value, String field) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(field + " must not be blank");
}
}
}
@@ -1,66 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.MessagingCapabilities;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.policy.DestinationProfile;
import java.util.Objects;
/**
* Guards the Pulsar Experimental adapter.
*
* <p>The subscription type and the destination's ordering scope have to agree, and the platform
* checks rather than assumes. A {@code Shared} subscription distributes messages round-robin across
* consumers, so a destination that declares key ordering on one is advertising a guarantee Pulsar
* is not providing — the messages arrive, in an order nobody promised.
*
* <p>Experimental means off by default. An adapter whose contract suite is still being proven must
* not become load-bearing because someone's configuration defaulted it on.
*/
public final class PulsarProfileValidator {
/**
* Validates a destination against a Pulsar subscription.
*
* @param profile the destination profile
* @param subscriptionType the Pulsar subscription type
* @param enabled whether the experimental adapter is switched on
*/
public void validate(
DestinationProfile profile, PulsarSubscriptionType subscriptionType, boolean enabled) {
Objects.requireNonNull(profile, "profile must not be null");
Objects.requireNonNull(subscriptionType, "subscriptionType must not be null");
if (!enabled) {
throw new MessagingCapabilityUnavailableException(
"PULSAR_DISABLED",
"the Pulsar adapter is experimental and disabled unless "
+ "app.messaging.experimental.pulsar=true");
}
if (profile.orderingScope() == OrderingScope.KEY
&& subscriptionType != PulsarSubscriptionType.KEY_SHARED) {
throw new IllegalArgumentException(
"keyed ordering requires a Key_Shared subscription: " + profile.name().value());
}
if (profile.orderingScope() == OrderingScope.DESTINATION) {
throw new IllegalArgumentException(
"the Pulsar adapter does not offer destination-wide ordering: " + profile.name().value());
}
}
/**
* Returns what the Pulsar adapter can prove for a subscription type.
*
* <p>Transactions are reported as unavailable while the adapter is Experimental: Pulsar has them,
* but the platform has not yet proven them against its own contract suite, and advertising an
* unverified guarantee is exactly what the Experimental tier exists to prevent.
*
* @param subscriptionType the subscription type
* @return the capabilities
*/
public MessagingCapabilities capabilities(PulsarSubscriptionType subscriptionType) {
boolean keyed = subscriptionType == PulsarSubscriptionType.KEY_SHARED;
return new MessagingCapabilities(
true, true, true, true, keyed, keyed, true, true, false, false, true, true);
}
}
@@ -1,62 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import java.util.Objects;
/**
* How a Pulsar subscription is configured, and what ordering it can actually deliver.
*
* <p>Pairs the subscription type with its acknowledgement style because the two together determine
* the guarantee. A {@code Key_Shared} subscription with cumulative acknowledgement is not keyed
* ordering with a faster ack — cumulative ack over interleaved keys acknowledges messages from keys
* the consumer has not finished, so the combination silently loses the property the subscription
* type was chosen for.
*
* @param subscriptionType the Pulsar subscription type
* @param cumulativeAcknowledgement whether acknowledgements are cumulative rather than individual
*/
public record PulsarSubscriptionMode(
PulsarSubscriptionType subscriptionType, boolean cumulativeAcknowledgement) {
public PulsarSubscriptionMode {
Objects.requireNonNull(subscriptionType, "subscriptionType must not be null");
if (cumulativeAcknowledgement && subscriptionType == PulsarSubscriptionType.KEY_SHARED) {
throw new IllegalArgumentException(
"Key_Shared with cumulative acknowledgement acknowledges keys the consumer has not "
+ "finished, which discards the per-key ordering the subscription type provides");
}
if (cumulativeAcknowledgement && subscriptionType == PulsarSubscriptionType.SHARED) {
throw new IllegalArgumentException(
"Shared subscriptions do not support cumulative acknowledgement");
}
}
/**
* Returns a shared subscription with individual acknowledgement.
*
* @return the shared mode
*/
public static PulsarSubscriptionMode shared() {
return new PulsarSubscriptionMode(PulsarSubscriptionType.SHARED, false);
}
/**
* Returns a key-shared subscription with individual acknowledgement.
*
* @return the key-shared mode
*/
public static PulsarSubscriptionMode keyShared() {
return new PulsarSubscriptionMode(PulsarSubscriptionType.KEY_SHARED, false);
}
/**
* Returns the strongest ordering this mode can deliver.
*
* @return the ordering scope
*/
public OrderingScope orderingScope() {
return subscriptionType == PulsarSubscriptionType.KEY_SHARED
? OrderingScope.KEY
: OrderingScope.NONE;
}
}
@@ -1,17 +0,0 @@
package dev.caskeleton.messaging.pulsar;
/**
* The Pulsar subscription types the Experimental adapter exposes.
*
* <p>Only the two that map cleanly onto the platform's ordering model. {@code Exclusive} and {@code
* Failover} are omitted deliberately: they encode a topology decision the destination profile
* already owns, and exposing them would give an application two places to configure the same thing.
*/
public enum PulsarSubscriptionType {
/** Competing consumers, no ordering. */
SHARED,
/** Competing consumers with per-key ordering. */
KEY_SHARED
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
/**
* States, in code, that Pulsar transactions are not promoted.
*
* <p>Pulsar has transactions. The platform does not offer them, and the distinction matters enough
* to be a class rather than a comment: an operator reading the capability matrix needs to know the
* answer is "not proven here", not "the broker cannot do it".
*
* <p>What is missing is the proof. The platform's contract suite has not been run against Pulsar
* transactions across broker restart, client fencing, and partial-commit recovery, and the
* Experimental tier exists precisely so that an unproven guarantee is never advertised as one. A
* capability that reports {@code true} on the strength of the broker's documentation is the failure
* mode this class prevents.
*/
public final class PulsarTransactionCapability {
private PulsarTransactionCapability() {}
/** Whether the adapter advertises broker transactions. */
public static final boolean PROMOTED = false;
/**
* Reports whether transactions may be used.
*
* @return false while the adapter is Experimental
*/
public static boolean isAvailable() {
return PROMOTED;
}
/**
* Returns the refusal for a transactional request, for the caller to throw.
*
* <p>Returned rather than thrown so the refusal reads as a value at the call site: {@code throw
* PulsarTransactionCapability.rejection();} makes it obvious that control leaves there, which a
* method that throws on the caller's behalf hides.
*
* @return the exception explaining why transactions are unavailable
*/
public static MessagingCapabilityUnavailableException rejection() {
return new MessagingCapabilityUnavailableException(
"PULSAR_TRANSACTION_NOT_PROMOTED",
"Pulsar supports transactions but this adapter has not certified them against the "
+ "platform contract suite, so the capability is not advertised");
}
}
@@ -1,289 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee;
import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.schema.EncodedMessage;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import java.time.Instant;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeoutException;
import org.junit.jupiter.api.Test;
class PulsarAdapterContractTest {
private static final String TOPIC = "persistent://public/default/orders";
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final PulsarMessagePosition POSITION = new PulsarMessagePosition(5, 9, 0, -1);
private static PulsarMessagingTransport transport(
PulsarMessagingTransport.PulsarSendOperation send, PulsarSubscriptionMode mode) {
PulsarProfile profile =
new PulsarProfile(
TOPIC, "orders-sub", mode, java.time.Duration.ofSeconds(30), Optional.empty(), 5);
return new PulsarMessagingTransport("pulsar-primary", 1, profile, send);
}
private static PulsarMessagingTransport confirming() {
return transport(
(topic, request) -> CompletableFuture.completedFuture(POSITION),
PulsarSubscriptionMode.shared());
}
private static PulsarMessagingTransport failingWith(Throwable failure) {
return transport(
(topic, request) -> CompletableFuture.failedFuture(failure),
PulsarSubscriptionMode.shared());
}
private static PublishResult await(CompletionStage<?> stage) {
Object value = stage.toCompletableFuture().join();
return ((dev.caskeleton.messaging.transport.TransportPublishResult) value).result();
}
@Test
void aSuccessfulSendReportsReplicationEvidenceNotAMereReceipt() {
PublishResult result = await(confirming().publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED);
assertThat(result.evidence().confirmationLevel())
.as("the send future resolves only once the entry is persisted to the bookies")
.isEqualTo(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.ROUTED);
}
@Test
void theBrokerPositionIsCarriedBackForDiagnostics() {
assertThat(await(confirming().publish(request(64))).position()).hasValue(POSITION);
}
@Test
void aSendTimeoutIsAmbiguousRatherThanRejected() {
PublishResult result =
await(failingWith(new TimeoutException("send timed out")).publish(request(64)));
assertThat(result.completion())
.as("the entry may be on the bookies with only the acknowledgement lost")
.isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.evidence().transmission())
.isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED);
assertThat(result.evidence().brokerAccepted()).isFalse();
}
@Test
void onlyATypedPreSendRejectionIsReportedAsNotTransmitted() {
PublishResult result =
await(
failingWith(
new PulsarPreSendRejection(
"PULSAR_PRODUCER_FENCED", "the producer was fenced before the send"))
.publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED);
assertThat(result.failure())
.hasValueSatisfying(
failure -> assertThat(failure.code()).isEqualTo("PULSAR_PRODUCER_FENCED"));
}
@Test
void anUnrecognisedFailureIsAmbiguousRatherThanRejected() {
// Any exception the adapter cannot type is a send whose outcome it does not know. Reporting
// REJECTED invites the caller to republish an entry the bookies may already hold.
PublishResult result =
await(failingWith(new IllegalStateException("producer is fenced")).publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.evidence().transmission())
.isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED);
assertThat(result.failure())
.hasValueSatisfying(
failure -> assertThat(failure.code()).isEqualTo("PULSAR_SEND_OUTCOME_UNKNOWN"));
}
@Test
void aWrappedUnknownFailureIsAlsoAmbiguous() {
PublishResult result =
await(
failingWith(
new java.util.concurrent.CompletionException(
new RuntimeException("something the adapter has never seen")))
.publish(request(64)));
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
}
@Test
void aSendThatNeverCompletesIsBoundedByTheCallersTimeout() {
PulsarMessagingTransport stalled =
transport((topic, request) -> new CompletableFuture<>(), PulsarSubscriptionMode.shared());
PublishResult result =
await(stalled.publish(requestWithTimeout(java.time.Duration.ofMillis(50))));
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.failure())
.hasValueSatisfying(failure -> assertThat(failure.code()).isEqualTo("PULSAR_SEND_TIMEOUT"));
}
@Test
void anOversizedPayloadIsRejectedBeforeItReachesTheBroker() {
PublishResult result =
await(confirming().publish(request(PayloadPolicy.DEFAULT_MAX_BYTES + 1)));
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED);
assertThat(result.failure())
.hasValueSatisfying(failure -> assertThat(failure.code()).isEqualTo("PAYLOAD_TOO_LARGE"));
}
@Test
void aClosedTransportStopsAcceptingNewWork() {
PulsarMessagingTransport transport = confirming();
transport.close();
assertThat(transport.isAcceptingWork()).isFalse();
assertThat(await(transport.publish(request(64))).completion())
.isEqualTo(PublishCompletion.REJECTED);
}
@Test
void aTransportWithoutAConsumerFactoryRefusesToRegisterRatherThanReturningNothing() {
assertThatThrownBy(() -> confirming().register(null)).isInstanceOf(NullPointerException.class);
}
@Test
void aSharedSubscriptionAdvertisesNoKeyedOrdering() {
var capabilities =
transport(
(topic, request) -> CompletableFuture.completedFuture(POSITION),
PulsarSubscriptionMode.shared())
.capabilities(new DestinationName("orders.v1"))
.capabilities();
assertThat(capabilities.keyedOrdering()).isFalse();
}
@Test
void aKeySharedSubscriptionAdvertisesKeyedOrdering() {
var capabilities =
transport(
(topic, request) -> CompletableFuture.completedFuture(POSITION),
PulsarSubscriptionMode.keyShared())
.capabilities(new DestinationName("orders.v1"))
.capabilities();
assertThat(capabilities.keyedOrdering()).isTrue();
}
@Test
void noSubscriptionModeAdvertisesBrokerTransactions() {
assertThat(
transport(
(topic, request) -> CompletableFuture.completedFuture(POSITION),
PulsarSubscriptionMode.keyShared())
.capabilities(new DestinationName("orders.v1"))
.capabilities()
.brokerTransaction())
.as("Pulsar has transactions; this adapter has not certified them")
.isFalse();
}
@Test
void requestingATransactionFailsWithAnExplanation() {
assertThat(PulsarTransactionCapability.rejection())
.isInstanceOf(MessagingCapabilityUnavailableException.class)
.hasMessageContaining("not advertised");
}
private static TransportPublishRequest requestWithTimeout(java.time.Duration timeout) {
PublishOptions defaults = PublishOptions.defaults();
return new TransportPublishRequest(
profile(),
envelope(64),
new PublishOptions(timeout, defaults.confirmation(), defaults.deduplication()));
}
private static TransportPublishRequest request(int payloadBytes) {
return new TransportPublishRequest(
profile(), envelope(payloadBytes), PublishOptions.defaults());
}
private static DestinationProfile profile() {
return new DestinationProfile(
new DestinationName("orders.v1"),
"pulsar-primary",
DestinationKind.EVENT_STREAM,
PhysicalDestination.pulsarTopic(TOPIC, "orders-sub"),
new SchemaPolicy(
ContentType.JSON,
SchemaCompatibility.BACKWARD,
Set.of(new MessageType("order.created"))),
DeliveryGuarantee.AT_LEAST_ONCE,
OrderingScope.NONE,
ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED,
ProducerPolicy.defaults(),
ConsumerPolicy.defaults("orders"),
RetryPolicy.none(),
DeadLetterPolicy.to(new DestinationName("orders.v1.dlq")),
PayloadPolicy.defaults(),
CapabilityTier.M1,
false,
false,
false);
}
private static MessageEnvelope<EncodedMessage> envelope(int payloadBytes) {
byte[] payload = new byte[payloadBytes];
java.util.Arrays.fill(payload, (byte) 'x');
return new MessageEnvelope<>(
MessageId.newId(),
new MessageType("order.created"),
new SchemaVersion(1),
NOW,
Optional.of(NOW),
new ProducerId("order-api"),
Optional.empty(),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
new EncodedMessage(payload, ContentType.JSON, Optional.empty()));
}
}
@@ -1,125 +0,0 @@
package dev.caskeleton.messaging.pulsar;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import java.time.Duration;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class PulsarSubscriptionGuardTest {
@Test
void keySharedWithCumulativeAcknowledgementIsRefused() {
assertThatThrownBy(() -> new PulsarSubscriptionMode(PulsarSubscriptionType.KEY_SHARED, true))
.as("cumulative ack over interleaved keys discards the ordering the type provides")
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("ordering");
}
@Test
void sharedWithCumulativeAcknowledgementIsRefused() {
assertThatThrownBy(() -> new PulsarSubscriptionMode(PulsarSubscriptionType.SHARED, true))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aSharedSubscriptionPromisesNoOrdering() {
assertThat(PulsarSubscriptionMode.shared().orderingScope()).isEqualTo(OrderingScope.NONE);
}
@Test
void aKeySharedSubscriptionPromisesKeyOrdering() {
assertThat(PulsarSubscriptionMode.keyShared().orderingScope()).isEqualTo(OrderingScope.KEY);
}
@Test
void aZeroNegativeAckDelayIsRefused() {
assertThatThrownBy(
() ->
new PulsarProfile(
"persistent://public/default/orders",
"orders-sub",
PulsarSubscriptionMode.shared(),
Duration.ZERO,
Optional.empty(),
5))
.as("a zero redelivery delay turns a failing handler into a spin loop")
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("spin loop");
}
@Test
void anAckTimeoutBelowPulsarsOwnFloorIsRefused() {
assertThatThrownBy(
() ->
new PulsarProfile(
"persistent://public/default/orders",
"orders-sub",
PulsarSubscriptionMode.shared(),
Duration.ofSeconds(30),
Optional.of(Duration.ofSeconds(1)),
5))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void theDefaultProfileLeavesAckTimeoutOff() {
assertThat(
PulsarProfile.shared("persistent://public/default/orders", "orders-sub").ackTimeout())
.as("an ack timeout redelivers messages from handlers that are merely slow")
.isEmpty();
}
@Test
void transactionsAreNotAdvertisedWhileTheAdapterIsExperimental() {
assertThat(PulsarTransactionCapability.isAvailable()).isFalse();
assertThat(PulsarTransactionCapability.rejection())
.isInstanceOf(MessagingCapabilityUnavailableException.class);
}
@Test
void theRefusalExplainsThatTheGapIsProofNotBrokerSupport() {
assertThat(PulsarTransactionCapability.rejection())
.hasMessageContaining("certified")
.hasMessageContaining("contract suite");
}
@Test
void aNonBatchedPositionRendersWithoutABatchIndex() {
PulsarMessagePosition position =
new PulsarMessagePosition(12, 34, 2, PulsarMessagePosition.NOT_APPLICABLE);
assertThat(position.toMessageId()).isEqualTo("12:34:2");
assertThat(position.broker()).isEqualTo("pulsar");
}
@Test
void aBatchedPositionKeepsItsIndexBecauseTheIdAloneIsShared() {
assertThat(new PulsarMessagePosition(12, 34, 2, 7).toMessageId()).isEqualTo("12:34:2:7");
}
@Test
void thePositionIsReadableAsDiagnosticAttributes() {
assertThat(new PulsarMessagePosition(12, 34, 2, 7).diagnosticAttributes())
.containsEntry("ledgerId", "12")
.containsEntry("batchIndex", "7");
}
@Test
void theValidatorAcceptsAKeyedProfileOnKeyShared() {
assertThatCode(
() ->
new PulsarProfile(
"persistent://public/default/orders",
"orders-sub",
PulsarSubscriptionMode.keyShared(),
Duration.ofSeconds(30),
Optional.empty(),
5))
.doesNotThrowAnyException();
}
}
-43
View File
@@ -1,43 +0,0 @@
plugins {
id 'java-test-fixtures'
id 'ca.auxiliary-source-set'
id 'ca.jmh-benchmarks'
}
auxiliarySourceSets {
sourceSet('integrationTest') {
compilesAgainst 'main', 'testFixtures'
}
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-observability')
api project(':messaging:messaging-security')
api project(':messaging:messaging-admin-api')
// api: RabbitChannelPublisher and the mappers expose Spring AMQP's Message on public
// signatures, so a consumer implementing the seam needs the type on its compile classpath.
api 'org.springframework.amqp:spring-rabbit'
implementation 'org.springframework:spring-context'
// Test-only. The same adapter contract Kafka runs, so a guarantee can only be weakened by
// editing the contract rather than by an adapter quietly not implementing it.
testImplementation project(':messaging:messaging-testkit')
// Live-broker certification. The confirm-and-return ordering the adapter depends on is a
// property of AMQP, and only a real broker exhibits it.
integrationTestImplementation 'org.testcontainers:testcontainers-rabbitmq'
integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter'
}
strictTestLanes {
lane('integrationTest') {
integration()
sourceSet = 'integrationTest'
description = 'Runs RabbitMQ broker integration contracts against a real container.'
}
}
-128
View File
@@ -1,128 +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.fasterxml.jackson.core:jackson-annotations:2.21=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.github.docker-java:docker-java-api:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.docker-java:docker-java-transport-zerodep:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.docker-java:docker-java-transport:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
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,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
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,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
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,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
com.rabbitmq:amqp-client:5.27.1=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-codec:commons-codec:1.19.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
io.micrometer:micrometer-commons:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-buffer:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-codec-base:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-codec-compression:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-codec-marshalling:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-codec-protobuf:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-codec:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-common:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-handler:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-resolver:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-transport-native-unix-common:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
io.netty:netty-transport:4.2.17.Final=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
net.sf.jopt-simple:jopt-simple:5.0.4=jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath
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-compress:1.28.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.apache.commons:commons-lang3:3.20.0=checkstyle,integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs
org.apache.commons:commons-math3:3.6.1=jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath
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=integrationTestCompileClasspath,jmhCompileClasspath,testCompileClasspath
org.assertj:assertj-core:3.27.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,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.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.jetbrains:annotations:17.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,integrationTestAnnotationProcessor,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testFixturesAnnotationProcessor,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,testRuntimeClasspath
org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,jmhRuntimeClasspath,runtimeClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.mockito:mockito-core:5.20.0=mockitoAgent
org.openjdk.jmh:jmh-core:1.37=jmhAnnotationProcessor,jmhCompileClasspath,jmhRuntimeClasspath
org.openjdk.jmh:jmh-generator-annprocess:1.37=jmhAnnotationProcessor
org.opentest4j:opentest4j:1.3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,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,integrationTestAnnotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.slf4j:slf4j-api:2.0.18=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springframework.amqp:spring-amqp:4.0.5=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework.amqp:spring-rabbit:4.0.5=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-context:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-core:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-messaging:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-rabbitmq:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
@@ -1,232 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThat;
import com.rabbitmq.client.AMQP;
import com.rabbitmq.client.Channel;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.ConnectionFactory;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.schema.EncodedMessage;
import dev.caskeleton.messaging.testkit.DockerAvailability;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeoutException;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIf;
import org.springframework.amqp.core.MessageProperties;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.rabbitmq.RabbitMQContainer;
/**
* Certifies the RabbitMQ adapter against a live broker.
*
* <p>The test that matters is the unroutable one. AMQP delivers a {@code basic.return}
* <em>before</em> the confirm for a message no queue was bound to receive, and an adapter that
* completes on the confirm alone reports success for a message the broker threw away. No mock
* proves the ordering is handled correctly, because the ordering is the broker's behaviour.
*/
@Testcontainers
@EnabledIf("dockerAvailable")
class RabbitBrokerIT {
private static final String EXCHANGE = "notification.work";
private static final String BOUND_KEY = "email";
private static final String UNBOUND_KEY = "nothing.is.bound.here";
private static final String QUEUE = "notification.email.q";
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
@Container
private static final RabbitMQContainer RABBIT = new RabbitMQContainer("rabbitmq:4.3-management");
private Connection connection;
private Channel channel;
private RabbitMessagingTransport transport;
static boolean dockerAvailable() {
return DockerAvailability.isAvailable();
}
@BeforeEach
void declareTopology() throws IOException, TimeoutException {
ConnectionFactory factory = new ConnectionFactory();
factory.setHost(RABBIT.getHost());
factory.setPort(RABBIT.getAmqpPort());
factory.setUsername(RABBIT.getAdminUsername());
factory.setPassword(RABBIT.getAdminPassword());
connection = factory.newConnection();
channel = connection.createChannel();
channel.exchangeDeclare(EXCHANGE, "direct", true);
channel.queueDeclare(QUEUE, true, false, false, Map.of("x-queue-type", "quorum"));
channel.queueBind(QUEUE, EXCHANGE, BOUND_KEY);
// The container is shared across the class, so a message left by an earlier test would make a
// later queue-depth assertion pass or fail for the wrong reason.
channel.queuePurge(QUEUE);
channel.confirmSelect();
transport =
new RabbitMessagingTransport(
"rabbit-primary",
1,
new RabbitChannelPublisher() {
@Override
public long nextPublishSequence() {
return channel.getNextPublishSeqNo();
}
@Override
public void publish(
long sequence,
String exchange,
String routingKey,
org.springframework.amqp.core.Message message,
boolean mandatory) {
RabbitBrokerIT.this.publish(sequence, exchange, routingKey, message, mandatory);
}
});
channel.addConfirmListener(
(deliveryTag, multiple) -> transport.onConfirm(deliveryTag, true, Duration.ofMillis(1)),
(deliveryTag, multiple) -> transport.onConfirm(deliveryTag, false, Duration.ofMillis(1)));
channel.addReturnListener(
returned ->
transport.onReturn(
Long.parseLong(returned.getProperties().getHeaders().get("x-seq").toString())));
}
@AfterEach
void close() throws IOException, TimeoutException {
if (channel != null && channel.isOpen()) {
channel.close();
}
if (connection != null && connection.isOpen()) {
connection.close();
}
}
@Test
void aRoutablePublishConfirmsWithReplicationEvidence() {
PublishResult result = await(transport.publish(request(BOUND_KEY)));
assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.ROUTED);
assertThat(result.evidence().confirmationLevel())
.isEqualTo(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK);
}
@Test
void anUnroutablePublishIsRejectedEvenThoughTheExchangeConfirmedIt() {
PublishResult result = await(transport.publish(request(UNBOUND_KEY)));
assertThat(result.completion())
.as("the exchange accepted it and the broker threw it away; that is not success")
.isEqualTo(PublishCompletion.REJECTED);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.UNROUTABLE);
assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE);
}
@Test
void aRoutablePublishReachesTheQueue() throws IOException {
await(transport.publish(request(BOUND_KEY)));
assertThat(channel.messageCount(QUEUE)).isEqualTo(1);
}
@Test
void anUnroutablePublishReachesNoQueue() throws IOException {
await(transport.publish(request(UNBOUND_KEY)));
assertThat(channel.messageCount(QUEUE)).isZero();
}
/**
* Publishes and records the sequence number in a header.
*
* <p>A returned message arrives without its publish sequence number, so the adapter has to carry
* one itself to correlate the return with the pending publish.
*/
private void publish(
long sequence,
String exchange,
String routingKey,
org.springframework.amqp.core.Message message,
boolean mandatory) {
try {
MessageProperties source = message.getMessageProperties();
AMQP.BasicProperties properties =
new AMQP.BasicProperties.Builder()
.messageId(source.getMessageId())
.contentType(source.getContentType())
.deliveryMode(2)
.headers(withSequence(source, sequence))
.build();
// No waitForConfirms: the coordinator completes the publish from the confirm listener, and
// blocking here would hold the calling thread through the round trip for no benefit.
channel.basicPublish(exchange, routingKey, mandatory, properties, message.getBody());
} catch (IOException exception) {
throw new IllegalStateException("rabbit publish failed", exception);
}
}
private static Map<String, Object> withSequence(MessageProperties source, long sequence) {
java.util.Map<String, Object> headers = new java.util.LinkedHashMap<>(source.getHeaders());
headers.put("x-seq", Long.toString(sequence));
return headers;
}
private static PublishResult await(
CompletionStage<dev.caskeleton.messaging.transport.TransportPublishResult> stage) {
return stage.toCompletableFuture().join().result();
}
private TransportPublishRequest request(String routingKey) {
return new TransportPublishRequest(
RabbitFixtureProfiles.routingTo(EXCHANGE, routingKey, QUEUE),
envelope(),
PublishOptions.defaults());
}
private static MessageEnvelope<EncodedMessage> envelope() {
return new MessageEnvelope<>(
MessageId.newId(),
new MessageType("order.created"),
new SchemaVersion(1),
NOW,
Optional.of(NOW),
new ProducerId("order-api"),
Optional.empty(),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
new EncodedMessage(
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
ContentType.JSON,
Optional.empty()));
}
}
@@ -1,32 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.PhysicalDestination;
/** Builds destination profiles that vary only in their physical mapping. */
final class RabbitFixtureProfiles {
private RabbitFixtureProfiles() {}
static DestinationProfile routingTo(String exchange, String routingKey, String queue) {
DestinationProfile base = RabbitProfileFixtures.workQueueDestination();
return new DestinationProfile(
base.name(),
base.broker(),
base.kind(),
PhysicalDestination.rabbitQueue(exchange, routingKey, queue),
base.schema(),
base.deliveryGuarantee(),
base.orderingScope(),
base.externalSideEffectGuarantee(),
base.producer(),
base.consumer(),
base.retry(),
base.deadLetter(),
base.payload(),
base.tier(),
base.production(),
base.keyResolverConfigured(),
base.topologyAutoCreate());
}
}
@@ -1,156 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
import java.util.concurrent.TimeUnit;
import org.openjdk.jmh.annotations.Benchmark;
import org.openjdk.jmh.annotations.BenchmarkMode;
import org.openjdk.jmh.annotations.Fork;
import org.openjdk.jmh.annotations.Level;
import org.openjdk.jmh.annotations.Measurement;
import org.openjdk.jmh.annotations.Mode;
import org.openjdk.jmh.annotations.OutputTimeUnit;
import org.openjdk.jmh.annotations.Param;
import org.openjdk.jmh.annotations.Scope;
import org.openjdk.jmh.annotations.Setup;
import org.openjdk.jmh.annotations.State;
import org.openjdk.jmh.annotations.Warmup;
import org.openjdk.jmh.infra.Blackhole;
/**
* Measures the RabbitMQ adapter's own cost per publish, with no broker in the loop.
*
* <p>The confirm coordinator is the interesting one here. Every publish registers a pending entry
* and every confirm resolves it, so its map operations run twice per message on the hot path — and
* because a confirm arrives on the connection thread while publishes arrive on caller threads, a
* regression there shows up as contention rather than as a slower method.
*
* <p>No channel and no network, for the same reason the Kafka benchmark has no producer: measuring
* the broker measures the environment.
*/
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.NANOSECONDS)
@Warmup(iterations = 3, time = 1)
@Measurement(iterations = 5, time = 1)
@Fork(1)
@State(Scope.Benchmark)
public class RabbitPublishBenchmark {
/** Payload sizes spanning the range a portable destination allows. */
@Param({"256", "4096", "65536"})
public int payloadBytes;
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final String EXCHANGE = "notification.work";
private static final String ROUTING_KEY = "email";
private RabbitHeaderMapper headerMapper;
private RabbitPublishFailureClassifier classifier;
private MessageEnvelope<EncodedMessage> envelope;
private RabbitConfirmCoordinator coordinator;
private long sequence;
/** Builds the fixtures once so the measured methods allocate only what a publish allocates. */
@Setup(Level.Trial)
public void setUp() {
headerMapper = new RabbitHeaderMapper();
classifier = new RabbitPublishFailureClassifier();
byte[] payload = new byte[payloadBytes];
java.util.Arrays.fill(payload, (byte) 'x');
envelope =
new MessageEnvelope<>(
MessageId.newId(),
new MessageType("email.requested"),
new SchemaVersion(1),
NOW,
Optional.of(NOW),
new ProducerId("notification-api"),
Optional.empty(),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
new EncodedMessage(payload, ContentType.JSON, Optional.empty()));
}
/** Resets the coordinator per iteration so pending entries do not accumulate across runs. */
@Setup(Level.Iteration)
public void resetCoordinator() {
coordinator = new RabbitConfirmCoordinator();
sequence = 0;
}
/**
* Measures mapping an envelope's reserved headers onto AMQP properties.
*
* @param blackhole consumes the result
*/
@Benchmark
public void mapHeaders(Blackhole blackhole) {
blackhole.consume(headerMapper.toProperties(envelope));
}
/**
* Measures one full register-then-confirm round trip through the coordinator.
*
* <p>Both halves together, because a benchmark of the registration alone would leave the pending
* map growing and report a cost that no real publish pays.
*
* @param blackhole consumes the result
*/
@Benchmark
public void registerAndConfirm(Blackhole blackhole) {
long current = ++sequence;
blackhole.consume(
coordinator.awaiting(
current,
EXCHANGE,
ROUTING_KEY,
ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK));
coordinator.confirmed(current, true, Duration.ofMillis(1));
}
/**
* Measures the unroutable path, which resolves through a return before the confirm.
*
* @param blackhole consumes the result
*/
@Benchmark
public void registerReturnAndConfirm(Blackhole blackhole) {
long current = ++sequence;
blackhole.consume(
coordinator.awaiting(
current,
EXCHANGE,
ROUTING_KEY,
ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK));
coordinator.returned(current);
coordinator.confirmed(current, true, Duration.ofMillis(1));
}
/**
* Measures classifying a lost confirm, which runs on every ambiguous publish.
*
* @param blackhole consumes the result
*/
@Benchmark
public void classifyLostConfirm(Blackhole blackhole) {
blackhole.consume(
classifier.classify(
new java.io.IOException("connection reset"), true, Duration.ofMillis(5)));
}
}
@@ -1,165 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.delivery.BatchDeliveryMetadata;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.policy.DestinationProfile;
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
/**
* Accumulates AMQP deliveries into batches, bounded by size and by age.
*
* <p>Unlike Kafka, RabbitMQ delivers one message at a time, so a batch here is built by the client
* rather than returned by a poll. That makes the age bound essential: without it, a queue that goes
* quiet leaves the last few messages sitting in the accumulator indefinitely, unacknowledged, until
* enough traffic arrives to fill a batch — which on a low-volume queue may be hours.
*
* <p>{@code settlableAsBatch} is reported false. AMQP's multiple-ack acknowledges every delivery up
* to a tag, which on a channel handling concurrent work settles messages the handler has not
* finished; the platform therefore acknowledges each delivery individually even when the handler
* saw them as a batch.
*
* <p>The accumulator is not thread-safe by design. It is driven from the single consumer callback
* thread for its channel, and adding synchronisation here would suggest it can be shared, which
* would interleave deliveries from different channels into one batch and lose their ordering.
*/
public final class RabbitBatchConsumerRegistrar {
private final DestinationProfile profile;
private final int maxBatchSize;
private final Duration maxBatchAge;
private final List<Long> deliveryTags = new ArrayList<>();
private Instant oldestArrival;
/**
* Creates a batch accumulator for a destination.
*
* @param profile the validated destination profile
* @param maxBatchSize the largest batch handed to a handler
* @param maxBatchAge how long the oldest delivery may wait before the batch is released
*/
public RabbitBatchConsumerRegistrar(
DestinationProfile profile, int maxBatchSize, Duration maxBatchAge) {
this.profile = Objects.requireNonNull(profile, "profile must not be null");
Objects.requireNonNull(maxBatchAge, "maxBatchAge must not be null");
if (maxBatchSize < 1) {
throw new IllegalArgumentException("maxBatchSize must be at least 1");
}
if (maxBatchAge.isNegative() || maxBatchAge.isZero()) {
throw new IllegalArgumentException(
"maxBatchAge must be positive; without it a quiet queue holds its last messages "
+ "unacknowledged indefinitely");
}
this.maxBatchSize = maxBatchSize;
this.maxBatchAge = maxBatchAge;
}
/**
* Adds one delivery to the current batch.
*
* @param deliveryTag the AMQP delivery tag
* @param now the current instant
* @return the batch when it is ready to release, otherwise empty
*/
public Optional<AmqpBatch> add(long deliveryTag, Instant now) {
Objects.requireNonNull(now, "now must not be null");
if (deliveryTags.isEmpty()) {
oldestArrival = now;
}
deliveryTags.add(deliveryTag);
return deliveryTags.size() >= maxBatchSize ? Optional.of(release(now)) : Optional.empty();
}
/**
* Releases the current batch if its oldest delivery has waited long enough.
*
* @param now the current instant
* @return the batch when the age bound was reached, otherwise empty
*/
public Optional<AmqpBatch> releaseIfStale(Instant now) {
Objects.requireNonNull(now, "now must not be null");
if (deliveryTags.isEmpty()) {
return Optional.empty();
}
return !now.isBefore(oldestArrival.plus(maxBatchAge))
? Optional.of(release(now))
: Optional.empty();
}
/**
* Releases whatever has accumulated, for shutdown.
*
* @param now the current instant
* @return the batch when anything was pending
*/
public Optional<AmqpBatch> drain(Instant now) {
Objects.requireNonNull(now, "now must not be null");
return deliveryTags.isEmpty() ? Optional.empty() : Optional.of(release(now));
}
/**
* Returns how many deliveries are waiting in the accumulator.
*
* @return the pending delivery count
*/
public int pending() {
return deliveryTags.size();
}
/**
* Refuses batch consumption where the prefetch cannot hold a whole batch.
*
* <p>A prefetch below the batch size deadlocks: the accumulator waits for more deliveries the
* broker will not send until something is acknowledged, and nothing is acknowledged until the
* batch is released.
*
* @param prefetch the channel prefetch count
* @throws MessagingConfigurationException when the prefetch is too small
*/
public void requirePrefetchFor(int prefetch) {
if (prefetch < maxBatchSize) {
throw new MessagingConfigurationException(
"PREFETCH_BELOW_BATCH_SIZE",
"destination %s batches %d deliveries but the channel prefetch is %d; the accumulator "
.formatted(profile.name().value(), maxBatchSize, prefetch)
+ "would wait for deliveries the broker will not send until something is acked");
}
}
private AmqpBatch release(Instant now) {
List<Long> released = List.copyOf(deliveryTags);
deliveryTags.clear();
oldestArrival = null;
return new AmqpBatch(
released,
new BatchDeliveryMetadata(
profile.name(),
released.size(),
// One queue is one ordering unit, so an accumulated batch never spans two.
Optional.of(profile.physical().queue().orElse(profile.name().value())),
// AMQP multiple-ack settles everything up to a tag, including work still in flight.
false,
now));
}
/**
* One accumulated batch of AMQP deliveries.
*
* @param deliveryTags the delivery tags, in arrival order
* @param metadata the batch-wide metadata handed to the handler
*/
public record AmqpBatch(List<Long> deliveryTags, BatchDeliveryMetadata metadata) {
public AmqpBatch {
Objects.requireNonNull(metadata, "metadata must not be null");
deliveryTags = List.copyOf(deliveryTags);
if (deliveryTags.isEmpty()) {
throw new IllegalArgumentException("a released batch is never empty");
}
}
}
}
@@ -1,50 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
/**
* The RabbitMQ client settings the platform is willing to run with.
*
* @param broker the logical broker name
* @param stable whether this profile claims the Stable guarantees
* @param production whether this profile is used in production
* @param addresses the broker addresses
* @param publisherConfirms whether correlated publisher confirms are on
* @param publisherReturns whether unroutable returns are delivered
* @param mandatory whether publishes are sent with the mandatory flag
* @param confirmTimeout how long to wait for a confirm
* @param autoAck whether the consumer acknowledges on delivery
* @param prefetch the consumer prefetch window
* @param quorumQueues whether durable work queues are declared as quorum queues
* @param tlsEnabled whether transport encryption is on
* @param authenticationEnabled whether broker authentication is on
*/
public record RabbitBrokerProfile(
String broker,
boolean stable,
boolean production,
List<String> addresses,
boolean publisherConfirms,
boolean publisherReturns,
boolean mandatory,
Duration confirmTimeout,
boolean autoAck,
int prefetch,
boolean quorumQueues,
boolean tlsEnabled,
boolean authenticationEnabled) {
public RabbitBrokerProfile {
Objects.requireNonNull(addresses, "addresses must not be null");
Objects.requireNonNull(confirmTimeout, "confirmTimeout must not be null");
if (broker == null || broker.isBlank()) {
throw new IllegalArgumentException("broker must not be blank");
}
if (addresses.isEmpty()) {
throw new IllegalArgumentException("addresses must not be empty");
}
addresses = List.copyOf(addresses);
}
}
@@ -1,42 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import org.springframework.amqp.core.Message;
/**
* The channel operations the transport needs, split so the confirm cannot outrun its registration.
*
* <p>Reserving the sequence number is a separate call from publishing on purpose. A confirm can
* arrive on the connection thread before {@code basicPublish} has even returned, so a transport
* that registered its pending publish afterwards would drop that confirm and wait forever for one
* that already came. Reserving first closes that race.
*/
public interface RabbitChannelPublisher {
/**
* Reserves the next publish sequence number without publishing.
*
* @return the sequence number the next publish will carry
*/
long nextPublishSequence();
/**
* Publishes a message under a previously reserved sequence number.
*
* @param sequence the reserved sequence number
* @param exchange the exchange to publish to
* @param routingKey the routing key
* @param message the AMQP message
* @param mandatory whether the broker must return an unroutable message
*/
void publish(
long sequence, String exchange, String routingKey, Message message, boolean mandatory);
/**
* Closes the underlying channel.
*
* <p>A default no-op so an existing publisher keeps compiling, but the transport calls it: a
* transport whose {@code close} only flipped a boolean left the native channel open and every
* pending stage waiting for a confirm that would never arrive.
*/
default void close() {}
}
@@ -1,279 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
/**
* Correlates a RabbitMQ publish with its confirm and its possible return.
*
* <p>This is the piece that makes the Rabbit adapter honest. AMQP delivers a return <em>before</em>
* the confirm for an unroutable message, so a naive adapter that completes on the confirm reports
* success for a message the broker threw away. The coordinator therefore keeps each publish pending
* until the confirm arrives, and remembers whether a return was seen first.
*
* <p>The resulting outcomes are: confirmed and not returned is {@code CONFIRMED}; confirmed and
* returned is {@code REJECTED} with {@code UNROUTABLE}; nacked is {@code REJECTED}; and a confirm
* that never arrives is {@code AMBIGUOUS}, because the broker may still have stored it.
*
* <p>Implemented as a pure state machine over sequence numbers so the whole ordering, including the
* return-before-confirm case, is testable without a broker.
*/
public final class RabbitConfirmCoordinator {
/**
* Pending publishes, ordered by sequence.
*
* <p>Ordered because a Rabbit confirm carries a {@code multiple} flag meaning "everything up to
* and including this tag". Resolving one sequence per confirm — which is what a hash map forces —
* leaves every earlier publish pending forever: the caller's stage never completes and the entry
* is never removed, so the map grows for the life of the connection.
*/
private final java.util.concurrent.ConcurrentSkipListMap<Long, PendingPublish> pending =
new java.util.concurrent.ConcurrentSkipListMap<>();
/**
* Registers a publish awaiting its confirm.
*
* @param sequence the channel publish sequence number
* @param exchange the exchange published to
* @param routingKey the routing key used
* @param requirement the confirmation the profile demanded
* @return a stage completing when the confirm, return, or timeout resolves it
*/
public CompletionStage<PublishResult> awaiting(
long sequence, String exchange, String routingKey, ConfirmationRequirement requirement) {
Objects.requireNonNull(exchange, "exchange must not be null");
Objects.requireNonNull(routingKey, "routingKey must not be null");
Objects.requireNonNull(requirement, "requirement must not be null");
PendingPublish publish = new PendingPublish(exchange, routingKey, requirement);
pending.put(sequence, publish);
return publish.completion;
}
/**
* Records that the broker returned a message as unroutable.
*
* <p>The return alone does not complete the publish: the confirm still follows, and only the pair
* establishes that the broker both accepted and discarded it.
*
* @param sequence the publish sequence number
*/
public void returned(long sequence) {
PendingPublish publish = pending.get(sequence);
if (publish != null) {
publish.returned = true;
}
}
/**
* Records a broker confirm.
*
* @param sequence the publish sequence number
* @param acknowledged true for an ack, false for a nack
* @param elapsed how long the publish took
*/
public void confirmed(long sequence, boolean acknowledged, Duration elapsed) {
confirmed(sequence, false, acknowledged, elapsed);
}
/**
* Records a broker confirm, honouring the {@code multiple} flag.
*
* @param multiple true when the broker is confirming every sequence up to and including this one
*/
public void confirmed(long sequence, boolean multiple, boolean acknowledged, Duration elapsed) {
if (!multiple) {
PendingPublish publish = pending.remove(sequence);
if (publish != null) {
publish.completion.complete(publish.resolve(sequence, acknowledged, elapsed));
}
return;
}
// headMap(tag, inclusive) is the whole point of the ordered map: the broker is confirming a
// range, and every entry in it must be resolved with the same verdict.
java.util.NavigableMap<Long, PendingPublish> confirmed = pending.headMap(sequence, true);
for (Long pendingSequence : java.util.List.copyOf(confirmed.keySet())) {
PendingPublish publish = pending.remove(pendingSequence);
if (publish != null) {
publish.completion.complete(publish.resolve(pendingSequence, acknowledged, elapsed));
}
}
}
/**
* Completes a publish whose send failed synchronously.
*
* <p>The classifier's verdict is used as-is: it is the only thing that knows whether the frame
* can have reached the broker, and guessing here would either invent a rejection for a message
* that was stored or an ambiguity for one that never left.
*
* @param sequence the publish sequence number
* @param result the classified outcome
*/
public void sendFailed(long sequence, PublishResult result) {
PendingPublish publish = pending.remove(sequence);
if (publish != null) {
publish.completion.complete(result);
}
}
/**
* Completes every pending publish because the channel is gone.
*
* <p>Ambiguous, not rejected: the frames were written, and a channel that closes afterwards says
* nothing about whether the broker stored them. Leaving them pending — which is what close used
* to do — hangs every caller holding a stage.
*
* @param elapsed how long the publishes had been waiting
* @return how many stages were completed
*/
public int channelClosed(Duration elapsed) {
int drained = 0;
for (Long sequence : java.util.List.copyOf(pending.keySet())) {
PendingPublish publish = pending.remove(sequence);
if (publish != null) {
publish.completion.complete(publish.resolveChannelClosed(sequence, elapsed));
drained++;
}
}
return drained;
}
/**
* Records that the confirm never arrived within the deadline.
*
* @param sequence the publish sequence number
* @param elapsed how long was waited
*/
public void timedOut(long sequence, Duration elapsed) {
PendingPublish publish = pending.remove(sequence);
if (publish == null) {
return;
}
publish.completion.complete(
new PublishResult(
PublishCompletion.AMBIGUOUS,
PublishEvidence.ambiguous(),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.AMBIGUOUS,
"RABBIT_CONFIRM_TIMEOUT",
"no publisher confirm arrived before the deadline"))));
}
/**
* Returns how many publishes are awaiting a confirm.
*
* @return the pending count
*/
public int pendingCount() {
return pending.size();
}
/** One publish waiting for its confirm, and whether a return arrived first. */
private static final class PendingPublish {
private final String exchange;
private final String routingKey;
private final ConfirmationRequirement requirement;
private final CompletableFuture<PublishResult> completion = new CompletableFuture<>();
private volatile boolean returned;
private PendingPublish(
String exchange, String routingKey, ConfirmationRequirement requirement) {
this.exchange = exchange;
this.routingKey = routingKey;
this.requirement = requirement;
}
/** The channel closed with this publish still awaiting its confirm. */
private PublishResult resolveChannelClosed(long sequence, Duration elapsed) {
return new PublishResult(
PublishCompletion.AMBIGUOUS,
PublishEvidence.ambiguous(),
RoutingOutcome.UNKNOWN,
Optional.of(new RabbitPublishReference(exchange, routingKey, sequence)),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.AMBIGUOUS,
"RABBIT_CHANNEL_CLOSED",
"the channel closed before the broker confirmed this publish")));
}
private PublishResult resolve(long sequence, boolean acknowledged, Duration elapsed) {
RabbitPublishReference position = new RabbitPublishReference(exchange, routingKey, sequence);
if (!acknowledged) {
return new PublishResult(
PublishCompletion.REJECTED,
// Transmitted, not "not transmitted": a NACK is the broker's answer to a frame it
// received. Recording it as never sent contradicts the very evidence that produced it,
// and a caller reading the evidence would conclude the message can be re-sent freely.
new PublishEvidence(
true,
dev.caskeleton.messaging.api.publish.TransmissionEvidence.TRANSMITTED,
false,
ConfirmationLevel.NONE),
RoutingOutcome.UNKNOWN,
Optional.of(position),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.PERMANENT_BUSINESS,
"RABBIT_NACK",
"the broker negatively acknowledged the publish")));
}
if (returned) {
return new PublishResult(
PublishCompletion.REJECTED,
new PublishEvidence(
true,
dev.caskeleton.messaging.api.publish.TransmissionEvidence.TRANSMITTED,
false,
ConfirmationLevel.NONE),
RoutingOutcome.UNROUTABLE,
Optional.of(position),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.PERMANENT_BUSINESS,
"RABBIT_UNROUTABLE",
"the exchange accepted the publish but no queue was bound")));
}
ConfirmationLevel level =
requirement == ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK
? ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK
: ConfirmationLevel.BROKER_ACK;
return new PublishResult(
PublishCompletion.CONFIRMED,
PublishEvidence.confirmed(level),
RoutingOutcome.ROUTED,
Optional.of(position),
1,
elapsed,
Optional.empty());
}
}
}
@@ -1,238 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.settlement.SettlementCompletion;
import dev.caskeleton.messaging.api.settlement.SettlementEvidence;
import dev.caskeleton.messaging.api.settlement.SettlementResult;
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
import dev.caskeleton.messaging.transport.TransportConsumerRegistration;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import dev.caskeleton.messaging.transport.TransportDelivery;
import dev.caskeleton.messaging.transport.TransportSettlement;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicBoolean;
import org.springframework.amqp.core.Message;
/**
* The RabbitMQ consumer runtime.
*
* <p>Deliveries arrive from the listener container and are handed to the platform with a settlement
* handle that is bound to one delivery tag and refuses a second terminal call. Duplicating a {@code
* basic.ack} on a reused tag acknowledges a <em>different</em> message, which shows up as
* unexplained loss under load, far from its cause.
*
* <p>Consumption stops the moment a drain begins, but deliveries already in flight are allowed to
* finish. Rejecting an in-flight delivery at shutdown would either lose it or duplicate its side
* effect, depending on where the handler had got to.
*/
public final class RabbitConsumerRegistrar implements TransportConsumerRegistration {
private final TransportConsumerSpec spec;
private final RabbitDeliveryMapper deliveryMapper;
private final RabbitSettlementOperations operations;
private final GracefulShutdownCoordinator shutdown;
private final Set<String> pausedScopes = ConcurrentHashMap.newKeySet();
private final AtomicBoolean active = new AtomicBoolean(true);
/**
* Creates a consumer runtime.
*
* @param spec what to consume and where to deliver it
* @param operations the channel operations a settlement drives
* @param shutdown the drain coordinator
*/
public RabbitConsumerRegistrar(
TransportConsumerSpec spec,
RabbitSettlementOperations operations,
GracefulShutdownCoordinator shutdown) {
this(spec, operations, shutdown, new RabbitDeliveryMapper());
}
/**
* Creates a consumer runtime with an explicit delivery mapper.
*
* @param spec what to consume and where to deliver it
* @param operations the channel operations a settlement drives
* @param shutdown the drain coordinator
* @param deliveryMapper rebuilds envelopes from AMQP messages
*/
public RabbitConsumerRegistrar(
TransportConsumerSpec spec,
RabbitSettlementOperations operations,
GracefulShutdownCoordinator shutdown,
RabbitDeliveryMapper deliveryMapper) {
this.spec = Objects.requireNonNull(spec, "spec must not be null");
this.operations = Objects.requireNonNull(operations, "operations must not be null");
this.shutdown = Objects.requireNonNull(shutdown, "shutdown must not be null");
this.deliveryMapper = Objects.requireNonNull(deliveryMapper, "deliveryMapper is required");
}
/**
* Handles one delivery pushed from the listener container.
*
* <p>Returns whether the delivery was accepted. A refusal means the runtime is draining or the
* queue is paused, and the caller must leave the message unacknowledged so the broker redelivers
* it.
*
* @param message the AMQP message
* @param now the current instant
* @return true when the delivery was dispatched
*/
public boolean onMessage(Message message, Instant now) {
Objects.requireNonNull(message, "message must not be null");
Objects.requireNonNull(now, "now must not be null");
String queue =
Optional.ofNullable(message.getMessageProperties().getConsumerQueue()).orElse("");
if (!active.get()) {
// close() only flipped a flag and onMessage never read it, so a delivery arriving after
// close was accepted, dispatched, and settled against a controller that was shutting down.
return false;
}
if (pausedScopes.contains(queue) || pausedScopes.contains("")) {
return false;
}
if (!shutdown.tryBeginWork()) {
return false;
}
long tag = message.getMessageProperties().getDeliveryTag();
try {
TransportDelivery delivery;
try {
// The narrow catch. One catch around decode, the handler and the settlement meant a
// business failure or an ACK that could not be written was recorded as an undecodable
// payload and discarded — a message that should have been retried, deleted instead.
delivery =
new TransportDelivery(
deliveryMapper.toEnvelope(message),
deliveryMapper.toMetadata(spec.profile().name(), message, now),
new ControllerBackedSettlement(tag));
} catch (RuntimeException undecodable) {
// Genuinely undecodable: it will fail the same way on every redelivery, so requeueing is a
// hot loop. Discarding is right here and only here.
operations
.discard(
tag,
FailureDescriptor.of(
FailureCategory.DESERIALIZATION,
"RABBIT_UNDECODABLE",
"the message could not be decoded into an envelope"))
.toCompletableFuture()
.join();
return true;
}
ControllerBackedSettlement settlement = (ControllerBackedSettlement) delivery.settlement();
try {
spec.sink().apply(delivery).toCompletableFuture().join();
} catch (RuntimeException handlerFailed) {
// A handler failure is a retry, not a discard.
requeueQuietly(settlement);
return true;
}
if (!settlement.wasSettled()) {
// A handler that completed without settling has not said what to do with the message.
// Acknowledging on its behalf would silently drop it; the contract violation is surfaced
// as a requeue so the message survives while somebody fixes the handler.
requeueQuietly(settlement);
}
return true;
} finally {
shutdown.endWork();
}
}
/** Requeues without letting a settlement failure become the caller's problem. */
private void requeueQuietly(ControllerBackedSettlement settlement) {
try {
settlement.requeue(Duration.ZERO).toCompletableFuture().join();
} catch (RuntimeException settlementFailed) {
// The broker connection is the thing that failed. There is nothing left to try here, and
// the delivery stays unsettled — which is what redelivery is for.
return;
}
}
@Override
public CompletionStage<Void> pause(String scope) {
pausedScopes.add(scope == null ? "" : scope);
return CompletableFuture.completedFuture(null);
}
@Override
public CompletionStage<Void> resume(String scope) {
pausedScopes.remove(scope == null ? "" : scope);
return CompletableFuture.completedFuture(null);
}
/**
* Reports whether a scope is currently paused.
*
* @param scope the queue, or an empty string for all
* @return true while paused
*/
public boolean isPaused(String scope) {
return pausedScopes.contains(scope == null ? "" : scope);
}
@Override
public boolean isActive() {
return active.get();
}
@Override
public void close() {
active.set(false);
}
/** Adapts the transport settlement SPI onto the one-terminal-call controller. */
private final class ControllerBackedSettlement implements TransportSettlement {
private final RabbitSettlementController controller;
private ControllerBackedSettlement(long deliveryTag) {
this.controller = new RabbitSettlementController(deliveryTag, operations);
}
private boolean wasSettled() {
return controller.isSettled();
}
@Override
public CompletionStage<SettlementResult> acknowledge() {
return controller.ack();
}
@Override
public CompletionStage<SettlementResult> requeue(Duration delay) {
if (!shutdown.mayCreateRetryAttempt()) {
return CompletableFuture.completedFuture(
new SettlementResult(
SettlementCompletion.UNKNOWN,
SettlementEvidence.unknown(),
Optional.of(
FailureDescriptor.of(
FailureCategory.AMBIGUOUS,
"RABBIT_DRAINING",
"no retry attempt is created while the consumer is draining"))));
}
return controller.retry(delay);
}
@Override
public CompletionStage<SettlementResult> discard() {
return controller.reject(
FailureDescriptor.of(
FailureCategory.PERMANENT_BUSINESS, "RABBIT_DISCARDED", "the message was discarded"));
}
}
}
@@ -1,130 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import dev.caskeleton.messaging.policy.DeadLetterOrchestrator;
import dev.caskeleton.messaging.policy.DeadLetterResult;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.SourceSettlement;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.CompletionStage;
/**
* The RabbitMQ entry point to dead lettering.
*
* <p>Delegates to the shared orchestrator, exactly as the Kafka adapter does, even though RabbitMQ
* has native dead-lettering available. The native path is only taken where {@link
* RabbitNativeDeadLetterCapability} has verified a queue is bound to the dead-letter exchange —
* everywhere else the broker would discard the message silently while the reject still succeeded,
* and the platform's publish-then-settle ordering is what prevents that.
*
* <p>Which path is taken is decided here rather than by each call site, so a handler cannot
* accidentally reject a message on a destination whose dead-letter exchange goes nowhere.
*/
public final class RabbitDeadLetterPublisher {
private final DeadLetterOrchestrator orchestrator;
private final RabbitNativeDeadLetterCapability nativeCapability;
private final NativeReject nativeReject;
/**
* Creates a Rabbit dead letter publisher.
*
* @param orchestrator the shared dead letter orchestrator
* @param nativeCapability decides whether the broker's own dead-lettering may be trusted
* @param nativeReject performs a broker-side reject
*/
public RabbitDeadLetterPublisher(
DeadLetterOrchestrator orchestrator,
RabbitNativeDeadLetterCapability nativeCapability,
NativeReject nativeReject) {
this.orchestrator = Objects.requireNonNull(orchestrator, "orchestrator must not be null");
this.nativeCapability = Objects.requireNonNull(nativeCapability, "nativeCapability required");
this.nativeReject = Objects.requireNonNull(nativeReject, "nativeReject must not be null");
}
/**
* Dead letters one delivery, by whichever path is safe for this destination.
*
* @param profile the source destination profile
* @param delivery the failed delivery
* @param failure the sanitized failure
* @param deliveryTag the AMQP delivery tag to reject, when taking the native path
* @param settlement the source settlement callback
* @return a stage completing with the dead letter outcome
*/
public CompletionStage<DeadLetterResult> deadLetter(
DestinationProfile profile,
MessageDelivery<EncodedMessage> delivery,
FailureDescriptor failure,
long deliveryTag,
SourceSettlement settlement) {
Objects.requireNonNull(profile, "profile must not be null");
Objects.requireNonNull(delivery, "delivery must not be null");
Objects.requireNonNull(failure, "failure must not be null");
if (nativeCapability.requiresPlatformPublish()) {
return orchestrator.deadLetter(profile, delivery, failure, settlement);
}
// The broker moves the message and settles the source in one operation. Safe only because the
// capability check confirmed a queue is bound to the dead letter exchange.
return nativeReject.reject(deliveryTag).thenApply(moved -> nativelyRouted());
}
/**
* Describes what a broker-side reject actually proves.
*
* <p>{@link ConfirmationLevel#BROKER_ACK}, not replication. RabbitMQ issues no publisher confirm
* for the internal hop to the dead-letter exchange, so the evidence available is that the broker
* accepted the reject — reporting it as a replication acknowledgement would claim a guarantee no
* part of this path provides.
*
* @return the dead letter outcome for the native path
*/
private static DeadLetterResult nativelyRouted() {
return new DeadLetterResult(
new PublishResult(
PublishCompletion.CONFIRMED,
new PublishEvidence(
true, TransmissionEvidence.TRANSMITTED, true, ConfirmationLevel.BROKER_ACK),
RoutingOutcome.ROUTED,
Optional.empty(),
1,
Duration.ZERO,
Optional.empty()),
// The reject settles the source as part of the same operation, so there is no window in
// which the message is neither parked nor deliverable.
true);
}
/**
* Returns why the platform is publishing rather than letting the broker route.
*
* @return the sanitized reason, empty when the native path is in use
*/
public String pathExplanation() {
return nativeCapability.reasonForPlatformPublish();
}
/** A broker-side reject that routes the message to the dead letter exchange. */
@FunctionalInterface
public interface NativeReject {
/**
* Rejects one delivery without requeueing it.
*
* @param deliveryTag the AMQP delivery tag
* @return a stage completing once the broker has taken the reject
*/
CompletionStage<Void> reject(long deliveryTag);
}
}
@@ -1,195 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.CausationId;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.CorrelationId;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TenantContext;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessageValidationException;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.UUID;
import org.springframework.amqp.core.Message;
import org.springframework.amqp.core.MessageProperties;
/**
* Rebuilds a platform envelope from an AMQP message.
*
* <p>The payload stays encoded so a codec failure is classified by the platform and parked, rather
* than surfacing as an AMQP listener exception the container would requeue in a hot loop.
*
* <p>The delivery attempt comes from the platform's own retry header rather than from AMQP's {@code
* redelivered} flag. That flag only says "this message was delivered before", not how many times,
* and it resets when a message travels through a retry queue.
*/
public final class RabbitDeliveryMapper {
private final RabbitHeaderMapper headerMapper;
/** Creates a mapper with the default header mapper. */
public RabbitDeliveryMapper() {
this(new RabbitHeaderMapper());
}
/**
* Creates a mapper with an explicit header mapper.
*
* @param headerMapper the header mapper
*/
public RabbitDeliveryMapper(RabbitHeaderMapper headerMapper) {
this.headerMapper = Objects.requireNonNull(headerMapper, "headerMapper must not be null");
}
/**
* Converts an AMQP message into an envelope.
*
* @param message the AMQP message
* @return the still-encoded envelope
*/
public MessageEnvelope<EncodedMessage> toEnvelope(Message message) {
Objects.requireNonNull(message, "message must not be null");
MessageProperties properties = message.getMessageProperties();
ContentType contentType =
new ContentType(
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.CONTENT_TYPE))
.or(() -> Optional.ofNullable(properties.getContentType()))
.orElse(ContentType.JSON.value()));
byte[] payload = message.getBody() == null ? new byte[0] : message.getBody();
Instant producedAt = instant(properties, ReservedHeaders.PRODUCED_AT);
return new MessageEnvelope<>(
new MessageId(uuid(properties, ReservedHeaders.MESSAGE_ID)),
new MessageType(required(properties, ReservedHeaders.MESSAGE_TYPE)),
new SchemaVersion(intValue(properties, ReservedHeaders.SCHEMA_VERSION)),
producedAt,
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.OCCURRED_AT))
.map(Instant::parse),
new ProducerId(
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.PRODUCER))
.orElse("unknown")),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.CORRELATION_ID))
.map(CorrelationId::new),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.CAUSATION_ID))
.map(value -> new CausationId(new MessageId(UUID.fromString(value)))),
contentType,
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.PARTITION_KEY)),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.ORDERING_KEY)),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TENANT))
.map(TenantContext::new),
new TraceContext(
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TRACEPARENT)),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.TRACESTATE)),
Optional.ofNullable(headerMapper.value(properties, ReservedHeaders.BAGGAGE))),
headerMapper.carriedForward(properties),
new EncodedMessage(payload, contentType, Optional.empty()));
}
/**
* Builds the delivery metadata for an AMQP message.
*
* @param destination the logical destination
* @param message the AMQP message
* @param receivedAt when the consumer received it
* @return the delivery metadata
*/
public DeliveryMetadata toMetadata(
DestinationName destination, Message message, Instant receivedAt) {
MessageProperties properties = message.getMessageProperties();
int attempt = attemptOf(properties);
return new DeliveryMetadata(
destination,
attempt,
attempt > 1,
Optional.of(
new RabbitPublishReference(
Optional.ofNullable(properties.getReceivedExchange()).orElse(""),
Optional.ofNullable(properties.getReceivedRoutingKey()).orElse(""),
Math.max(0, properties.getDeliveryTag()))),
Optional.ofNullable(properties.getConsumerQueue()),
Optional.ofNullable(properties.getConsumerTag()),
receivedAt);
}
/**
* Returns the attempt a message carries, counting the first delivery as one.
*
* @param properties the message properties
* @return the attempt number
*/
public int attemptOf(MessageProperties properties) {
String value = headerMapper.value(properties, ReservedHeaders.RETRY_ATTEMPT);
if (value == null) {
return 1;
}
try {
int attempt = Integer.parseInt(value);
if (attempt < 1) {
throw new NumberFormatException("attempt " + attempt);
}
return attempt;
} catch (NumberFormatException malformed) {
// Fail closed. Resetting to 1 restarts the retry budget on every redelivery, so a message
// that should have been dead-lettered is retried forever — and the header is
// caller-influenced, which turns "unreadable" into a way to defeat the cap.
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
"RETRY_ATTEMPT_MALFORMED",
"the retry attempt header is not a positive integer; the message is quarantined rather"
+ " than restarting its retry budget");
}
}
private String required(MessageProperties properties, String name) {
String value = headerMapper.value(properties, name);
if (value == null || value.isBlank()) {
throw new MessageValidationException(
"RABBIT_HEADER_MISSING", "message is missing the required header " + name);
}
return value;
}
private UUID uuid(MessageProperties properties, String name) {
try {
return UUID.fromString(required(properties, name));
} catch (IllegalArgumentException exception) {
throw new MessageValidationException(
"RABBIT_HEADER_MALFORMED", "header " + name + " is not a UUID", exception);
}
}
private int intValue(MessageProperties properties, String name) {
try {
return Integer.parseInt(required(properties, name));
} catch (NumberFormatException exception) {
throw new MessageValidationException(
"RABBIT_HEADER_MALFORMED", "header " + name + " is not an integer", exception);
}
}
private Instant instant(MessageProperties properties, String name) {
String value = headerMapper.value(properties, name);
if (value == null || value.isBlank()) {
return Optional.ofNullable(properties.getTimestamp())
.map(java.util.Date::toInstant)
.orElse(Instant.EPOCH);
}
try {
return Instant.parse(value);
} catch (java.time.format.DateTimeParseException exception) {
throw new MessageValidationException(
"RABBIT_HEADER_MALFORMED", "header " + name + " is not an instant", exception);
}
}
}
@@ -1,180 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.header.CanonicalEnvelopeHeaders;
import dev.caskeleton.messaging.api.header.HeaderName;
import dev.caskeleton.messaging.api.header.HeaderValue;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
import org.springframework.amqp.core.MessageProperties;
/**
* Maps envelope identity onto AMQP message properties and back.
*
* <p>Identity goes in headers, not in the payload, so a consumer can classify and park a message it
* cannot deserialize. The AMQP {@code message-id} and {@code correlation-id} properties are also
* populated, because management UIs and tracing tools read those and not the platform's headers —
* but the platform's own headers stay authoritative, since AMQP's properties have no schema version
* or producer field.
*/
public final class RabbitHeaderMapper {
/**
* Writes an envelope's identity into AMQP message properties.
*
* @param envelope the envelope being published
* @return the message properties
*/
public MessageProperties toProperties(MessageEnvelope<?> envelope) {
Objects.requireNonNull(envelope, "envelope must not be null");
MessageProperties properties = new MessageProperties();
properties.setMessageId(envelope.messageId().value().toString());
properties.setContentType(envelope.contentType().value());
properties.setTimestamp(java.util.Date.from(envelope.producedAt()));
properties.setDeliveryMode(org.springframework.amqp.core.MessageDeliveryMode.PERSISTENT);
setHeader(properties, ReservedHeaders.MESSAGE_ID, envelope.messageId().value().toString());
setHeader(properties, ReservedHeaders.MESSAGE_TYPE, envelope.messageType().value());
setHeader(
properties,
ReservedHeaders.SCHEMA_VERSION,
Integer.toString(envelope.schemaVersion().value()));
setHeader(properties, ReservedHeaders.PRODUCER, envelope.producer().value());
setHeader(properties, ReservedHeaders.PRODUCED_AT, envelope.producedAt().toString());
setHeader(properties, ReservedHeaders.CONTENT_TYPE, envelope.contentType().value());
envelope
.occurredAt()
.ifPresent(value -> setHeader(properties, ReservedHeaders.OCCURRED_AT, value.toString()));
envelope
.correlationId()
.ifPresent(
value -> {
properties.setCorrelationId(value.value());
setHeader(properties, ReservedHeaders.CORRELATION_ID, value.value());
});
envelope
.causationId()
.ifPresent(
value ->
setHeader(
properties, ReservedHeaders.CAUSATION_ID, value.value().value().toString()));
envelope
.partitionKey()
.ifPresent(value -> setHeader(properties, ReservedHeaders.PARTITION_KEY, value));
envelope
.orderingKey()
.ifPresent(value -> setHeader(properties, ReservedHeaders.ORDERING_KEY, value));
// Written for the same reason as on the other broker: an AMQP message carries no ambient
// tenant, so a tenant left off the wire is a tenant the consumed envelope does not have.
envelope
.tenantContext()
.ifPresent(value -> setHeader(properties, ReservedHeaders.TENANT, value.tenantId()));
envelope
.traceContext()
.traceparent()
.ifPresent(value -> setHeader(properties, ReservedHeaders.TRACEPARENT, value));
envelope
.traceContext()
.tracestate()
.ifPresent(value -> setHeader(properties, ReservedHeaders.TRACESTATE, value));
envelope
.traceContext()
.baggage()
.ifPresent(value -> setHeader(properties, ReservedHeaders.BAGGAGE, value));
// The envelope's header map is written last, so an unchecked name would overwrite the canonical
// reserved value the platform just wrote. A forged `msg.id` corrupts another message's inbox
// deduplication, not merely its own delivery.
//
// Only names that restate an envelope field are refused. Retry attempt, failure and redrive
// bookkeeping have no envelope field to be read back from, so refusing them would make every
// retry-queue and dead-letter re-publish fail on the guard meant to protect identity.
envelope
.headers()
.asMap()
.forEach(
(name, value) -> {
if (CanonicalEnvelopeHeaders.restatesEnvelopeField(name.value())) {
throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException(
"RESERVED_HEADER_FORGED",
"header '"
+ name.value()
+ "' restates a value the envelope already carries; the canonical value is"
+ " written by the platform and must not be overridable by message content");
}
setHeader(properties, name.value(), value.value());
});
return properties;
}
/**
* Reads AMQP headers back into a platform header map.
*
* @param properties the message properties
* @return the platform headers, including reserved names
*/
public MessageHeaders fromProperties(MessageProperties properties) {
Objects.requireNonNull(properties, "properties must not be null");
Map<HeaderName, HeaderValue> values = new LinkedHashMap<>();
properties
.getHeaders()
.forEach(
(name, value) -> {
if (value != null) {
values.put(new HeaderName(name), new HeaderValue(String.valueOf(value)));
}
});
return MessageHeaders.platform(values);
}
/**
* Reads back the headers a rebuilt envelope keeps.
*
* <p>Everything except the names that were hoisted into envelope fields: the application's own
* headers, which were dropped entirely and so never survived a broker hop, and the platform's
* retry and redrive bookkeeping, whose loss restarted the attempt counter at one on every
* redelivery and left the retry budget capping nothing.
*
* <p>The hoisted names are excluded rather than kept alongside their fields, because a duplicate
* that can drift from the field is how the same message ends up with two different ids depending
* on which one the reader trusts.
*
* @param properties the message properties
* @return the headers to carry on the rebuilt envelope
*/
public MessageHeaders carriedForward(MessageProperties properties) {
Objects.requireNonNull(properties, "properties must not be null");
Map<HeaderName, HeaderValue> values = new LinkedHashMap<>();
properties
.getHeaders()
.forEach(
(name, value) -> {
if (value != null && !CanonicalEnvelopeHeaders.restatesEnvelopeField(name)) {
values.put(new HeaderName(name), new HeaderValue(String.valueOf(value)));
}
});
return MessageHeaders.platform(values);
}
/**
* Reads one header value.
*
* @param properties the message properties
* @param name the header name
* @return the value, or null when absent
*/
public String value(MessageProperties properties, String name) {
Object value = properties.getHeaders().get(name);
return value == null ? null : String.valueOf(value);
}
private static void setHeader(MessageProperties properties, String name, String value) {
properties.setHeader(name, value);
}
}
@@ -1,286 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.destination.DestinationCapabilities;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessagingCapabilities;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.error.MessagingCapabilityUnavailableException;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.transport.MessagingTransport;
import dev.caskeleton.messaging.transport.TransportConsumerRegistration;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import dev.caskeleton.messaging.transport.TransportPublishResult;
import java.time.Duration;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.Function;
/**
* The Stable RabbitMQ adapter.
*
* <p>Publishes are always sent with {@code mandatory} set and correlated through {@link
* RabbitConfirmCoordinator}, because in AMQP a confirm and a return answer different questions. The
* confirm says the exchange accepted the message; the return says no queue was bound to receive it.
* An adapter that completed on the confirm alone would report success for a message the broker
* discarded, which is the single most damaging thing a Rabbit adapter can get wrong.
*
* <p>Payload size and shutdown state are checked before anything reaches the channel, so both fail
* with {@code NOT_TRANSMITTED} evidence rather than as a broker error whose ambiguity the caller
* then has to reason about.
*/
public final class RabbitMessagingTransport implements MessagingTransport {
private static final MessagingCapabilities CAPABILITIES =
new MessagingCapabilities(
true, true, true, false, false, false, false, true, false, false, true, true);
private final String brokerName;
private final long generation;
private final RabbitChannelPublisher channel;
private final RabbitPublishMapper mapper;
private final RabbitConfirmCoordinator coordinator;
private final Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory;
private final Duration confirmTimeout;
private final ScheduledExecutorService confirmTimeouts;
private final AtomicBoolean closed = new AtomicBoolean();
/**
* Creates a publish-only transport.
*
* @param brokerName the logical broker name
* @param generation the runtime generation
* @param channel the channel publish operation
*/
public RabbitMessagingTransport(
String brokerName, long generation, RabbitChannelPublisher channel) {
this(brokerName, generation, channel, Duration.ofSeconds(5));
}
/** Creates a publish-only transport with an explicit confirm timeout. */
public RabbitMessagingTransport(
String brokerName, long generation, RabbitChannelPublisher channel, Duration confirmTimeout) {
this(
brokerName,
generation,
channel,
spec -> {
throw new MessagingCapabilityUnavailableException(
"RABBIT_CONSUMER_NOT_CONFIGURED",
"this Rabbit transport was created without a consumer factory");
},
confirmTimeout);
}
/**
* Creates a transport with a consumer factory.
*
* @param brokerName the logical broker name
* @param generation the runtime generation
* @param channel the channel publish operation
* @param consumerFactory builds a consumer registration for a spec
*/
public RabbitMessagingTransport(
String brokerName,
long generation,
RabbitChannelPublisher channel,
Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory) {
this(brokerName, generation, channel, consumerFactory, Duration.ofSeconds(5));
}
/** Creates a transport with explicit consumer factory and confirm deadline. */
public RabbitMessagingTransport(
String brokerName,
long generation,
RabbitChannelPublisher channel,
Function<TransportConsumerSpec, TransportConsumerRegistration> consumerFactory,
Duration confirmTimeout) {
this.brokerName = Objects.requireNonNull(brokerName, "brokerName must not be null");
this.generation = generation;
this.channel = Objects.requireNonNull(channel, "channel must not be null");
this.consumerFactory = Objects.requireNonNull(consumerFactory, "consumerFactory is required");
this.confirmTimeout = Objects.requireNonNull(confirmTimeout, "confirmTimeout must not be null");
if (confirmTimeout.isNegative() || confirmTimeout.isZero()) {
throw new IllegalArgumentException("confirmTimeout must be positive");
}
this.mapper = new RabbitPublishMapper();
this.coordinator = new RabbitConfirmCoordinator();
this.confirmTimeouts =
Executors.newSingleThreadScheduledExecutor(
runnable -> {
Thread thread = new Thread(runnable, "messaging-rabbit-confirm-timeouts");
thread.setDaemon(true);
return thread;
});
}
@Override
public CompletionStage<TransportPublishResult> publish(TransportPublishRequest request) {
Objects.requireNonNull(request, "request must not be null");
if (closed.get()) {
return completed(
rejectedLocally("RABBIT_TRANSPORT_CLOSED", "the transport is shutting down"));
}
int size = request.envelope().payload().size();
int limit = request.profile().payload().maxBytes();
if (size > limit) {
return completed(
rejectedLocally(
"PAYLOAD_TOO_LARGE", "encoded payload is " + size + " bytes, limit is " + limit));
}
String exchange = mapper.exchange(request.profile());
String routingKey = mapper.routingKey(request.profile());
// Register before publishing. A confirm can land on the connection thread while basicPublish is
// still returning; registering afterwards would drop it and leave the caller waiting forever.
long sequence = channel.nextPublishSequence();
CompletionStage<TransportPublishResult> pending =
coordinator
.awaiting(sequence, exchange, routingKey, request.profile().producer().confirmation())
.thenApply(TransportPublishResult::new);
var timeout =
confirmTimeouts.schedule(
() -> coordinator.timedOut(sequence, confirmTimeout),
confirmTimeout.toNanos(),
TimeUnit.NANOSECONDS);
pending.whenComplete((result, failure) -> timeout.cancel(false));
try {
channel.publish(sequence, exchange, routingKey, mapper.toMessage(request), true);
} catch (RuntimeException sendFailed) {
// A synchronous failure from basicPublish used to propagate to the caller as a thrown
// exception while the pending entry stayed in the map: the caller got an exception instead
// of the stage the contract promises, and the entry waited for a confirm that could never
// arrive. The classifier decides whether the frame can have left; anything it cannot rule
// out is ambiguous rather than rejected.
coordinator.sendFailed(
sequence, new RabbitPublishFailureClassifier().classify(sendFailed, true, Duration.ZERO));
}
return pending;
}
/**
* Records a broker confirm. Called from the channel's confirm callback.
*
* @param sequence the publish sequence number
* @param acknowledged true for an ack, false for a nack
* @param elapsed how long the publish took
*/
public void onConfirm(long sequence, boolean acknowledged, Duration elapsed) {
onConfirm(sequence, false, acknowledged, elapsed);
}
/**
* Records a broker confirm carrying the {@code multiple} flag.
*
* <p>The flag was dropped, so a broker confirming a range resolved one publish and left every
* earlier one pending forever.
*
* @param multiple true when every sequence up to and including this one is confirmed
*/
public void onConfirm(long sequence, boolean multiple, boolean acknowledged, Duration elapsed) {
coordinator.confirmed(sequence, multiple, acknowledged, elapsed);
}
/**
* Records an unroutable return. Called from the channel's return callback.
*
* @param sequence the publish sequence number
*/
public void onReturn(long sequence) {
coordinator.returned(sequence);
}
/**
* Records that a confirm never arrived.
*
* @param sequence the publish sequence number
* @param elapsed how long was waited
*/
public void onConfirmTimeout(long sequence, Duration elapsed) {
coordinator.timedOut(sequence, elapsed);
}
/**
* Returns how many publishes are awaiting a confirm.
*
* @return the pending count
*/
public int pendingConfirms() {
return coordinator.pendingCount();
}
@Override
public TransportConsumerRegistration register(TransportConsumerSpec spec) {
Objects.requireNonNull(spec, "spec must not be null");
if (closed.get()) {
throw new MessagingCapabilityUnavailableException(
"RABBIT_TRANSPORT_CLOSED", "the transport is shutting down");
}
return consumerFactory.apply(spec);
}
@Override
public DestinationCapabilities capabilities(DestinationName destination) {
return new DestinationCapabilities(destination, brokerName, CAPABILITIES);
}
@Override
public String brokerName() {
return brokerName;
}
@Override
public long generation() {
return generation;
}
@Override
public void close() {
if (!closed.compareAndSet(false, true)) {
return;
}
// Drain what is still waiting. Leaving the stages pending hangs every caller holding one, and
// a closed channel will never deliver their confirms.
coordinator.channelClosed(Duration.ZERO);
confirmTimeouts.shutdownNow();
channel.close();
}
/**
* Reports whether the transport is still accepting work.
*
* @return true until close
*/
public boolean isAcceptingWork() {
return !closed.get();
}
private static TransportPublishResult rejectedLocally(String code, String message) {
return new TransportPublishResult(
new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
Duration.ZERO,
Optional.of(FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message))));
}
private static CompletionStage<TransportPublishResult> completed(TransportPublishResult result) {
return CompletableFuture.completedFuture(result);
}
}
@@ -1,70 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import java.util.Objects;
/**
* Decides whether the broker's own dead-lettering may be used, or the platform must publish.
*
* <p>RabbitMQ is the one Stable broker with native dead-lettering, and using it is tempting: a
* {@code basic.reject} with {@code requeue=false} moves the message with no publish at all. The
* catch is that the move is <em>not</em> confirmed to the publisher. If the dead-letter exchange is
* unroutable — nobody bound a queue to it, or the binding was removed — the broker discards the
* message silently and the reject still succeeds.
*
* <p>So native dead-lettering is only used where the dead-letter path has been verified to have a
* bound queue. Everywhere else the platform publishes and waits for its own confirm, which is the
* same invariant every other broker gets: <em>the source is settled only after the dead-letter
* publish is confirmed</em>.
*/
public final class RabbitNativeDeadLetterCapability {
private final RabbitTopologyProfile topology;
private final boolean deadLetterQueueBound;
/**
* Creates a capability check for one destination.
*
* @param topology the declared topology
* @param deadLetterQueueBound whether a queue is verified bound to the dead letter exchange
*/
public RabbitNativeDeadLetterCapability(
RabbitTopologyProfile topology, boolean deadLetterQueueBound) {
this.topology = Objects.requireNonNull(topology, "topology must not be null");
this.deadLetterQueueBound = deadLetterQueueBound;
}
/**
* Reports whether a rejected message may be left to the broker.
*
* @return true only when a dead letter exchange is declared and verified bound
*/
public boolean mayUseNativeDeadLetter() {
return topology.hasNativeDeadLetter() && deadLetterQueueBound;
}
/**
* Reports whether the platform must publish the dead letter itself.
*
* @return true when native dead-lettering cannot be trusted for this destination
*/
public boolean requiresPlatformPublish() {
return !mayUseNativeDeadLetter();
}
/**
* Returns why native dead-lettering is not being used, for a startup diagnostic.
*
* @return the sanitized reason, empty when native dead-lettering is in use
*/
public String reasonForPlatformPublish() {
if (mayUseNativeDeadLetter()) {
return "";
}
if (!topology.hasNativeDeadLetter()) {
return "queue %s was declared without a dead letter exchange".formatted(topology.queue());
}
return "no queue is bound to dead letter exchange %s, so a broker-side reject would discard "
.formatted(topology.deadLetterExchange().orElse("(none)"))
+ "the message silently while still reporting success";
}
}
@@ -1,83 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.policy.DestinationProfile;
import java.util.Objects;
/**
* Startup validation of the RabbitMQ Stable profile.
*
* <p>Confirms and returns are both required, and they answer different questions. A confirm says
* the exchange accepted the message; a return says no queue was bound to receive it. Enabling
* confirms without returns produces the worst possible outcome: a publish that reports success
* while the message was silently discarded.
*
* <p>Durable work queues default to quorum queues because classic mirrored queues can lose
* acknowledged messages during a partition — which is precisely the guarantee a durable work queue
* exists to provide.
*/
public final class RabbitProfileValidator {
/**
* Validates one RabbitMQ broker profile.
*
* @param profile the profile to validate
* @throws IllegalArgumentException when the profile cannot honour its declared guarantees
*/
public void validate(RabbitBrokerProfile profile) {
Objects.requireNonNull(profile, "profile must not be null");
if (profile.stable() && !profile.publisherConfirms()) {
throw new IllegalArgumentException(
"stable Rabbit producer requires publisher confirms: " + profile.broker());
}
if (profile.stable() && !profile.publisherReturns()) {
throw new IllegalArgumentException(
"stable Rabbit producer requires publisher returns: " + profile.broker());
}
if (profile.stable() && !profile.mandatory()) {
throw new IllegalArgumentException(
"stable Rabbit producer requires mandatory routing: " + profile.broker());
}
if (profile.autoAck()) {
throw new IllegalArgumentException(
"consumer auto ack is forbidden; the platform acknowledges after handler success: "
+ profile.broker());
}
if (profile.prefetch() < 1) {
throw new IllegalArgumentException("prefetch must be at least 1: " + profile.broker());
}
if (profile.confirmTimeout().isNegative() || profile.confirmTimeout().isZero()) {
throw new IllegalArgumentException("confirm timeout must be positive: " + profile.broker());
}
if (profile.production() && !profile.tlsEnabled()) {
throw new IllegalArgumentException(
"a production Rabbit connection requires TLS: " + profile.broker());
}
if (profile.production() && !profile.authenticationEnabled()) {
throw new IllegalArgumentException(
"a production Rabbit connection requires broker authentication: " + profile.broker());
}
}
/**
* Validates a destination against the broker profile.
*
* @param destination the destination profile
* @param broker the broker profile
* @throws IllegalArgumentException when the destination cannot be served safely
*/
public void validateDestination(DestinationProfile destination, RabbitBrokerProfile broker) {
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(broker, "broker must not be null");
if (destination.kind() == DestinationKind.WORK_QUEUE && !broker.quorumQueues()) {
throw new IllegalArgumentException(
"a durable Rabbit work queue must use a quorum queue: " + destination.name().value());
}
if (destination.physical().queue().isEmpty() && destination.physical().exchange().isEmpty()) {
throw new IllegalArgumentException(
"a Rabbit destination requires an exchange or a queue: " + destination.name().value());
}
}
}
@@ -1,133 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import java.io.IOException;
import java.time.Duration;
import java.util.Optional;
/**
* Turns an AMQP publish failure into a completion the caller can act on.
*
* <p>The distinction that matters is where the failure happened. A channel-level exception raised
* <em>before</em> {@code basicPublish} returned means nothing was written: rejected, with no
* ambiguity. A connection that drops <em>after</em> the frame was written proves nothing — the
* broker may have the message and only the confirm was lost.
*
* <p>Unknown failures default to ambiguous. Guessing "rejected" on an unrecognised error is what
* turns one lost confirm into two of the same order, and the cost of an unnecessary ambiguous is a
* retry the inbox absorbs.
*/
public final class RabbitPublishFailureClassifier {
/**
* Classifies a failure raised while publishing.
*
* @param error the throwable the channel reported
* @param framePossiblyWritten whether the publish frame may already have reached the broker
* @param elapsed how long the attempt took
* @return the publish outcome with its evidence
*/
public PublishResult classify(Throwable error, boolean framePossiblyWritten, Duration elapsed) {
Throwable cause = unwrap(error);
if (!framePossiblyWritten) {
return new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
categoryOf(cause),
"RABBIT_PUBLISH_REJECTED",
"the channel refused the publish before writing it: " + name(cause))));
}
return new PublishResult(
PublishCompletion.AMBIGUOUS,
new PublishEvidence(
true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.AMBIGUOUS,
"RABBIT_CONFIRM_LOST",
"the frame was written but no confirm arrived: " + name(cause))));
}
/**
* Classifies a broker nack, which is always a definitive rejection.
*
* @param elapsed how long the attempt took
* @return the publish outcome
*/
public PublishResult nacked(Duration elapsed) {
return new PublishResult(
PublishCompletion.REJECTED,
// A nack means the broker took the frame and decided against it, so the bytes were
// transmitted even though nothing was stored.
new PublishEvidence(true, TransmissionEvidence.TRANSMITTED, false, ConfirmationLevel.NONE),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
elapsed,
Optional.of(
FailureDescriptor.of(
FailureCategory.TRANSIENT_INFRASTRUCTURE,
"RABBIT_NACKED",
"the broker negatively acknowledged the publish")));
}
private static FailureCategory categoryOf(Throwable cause) {
if (cause instanceof com.rabbitmq.client.PossibleAuthenticationFailureException) {
return FailureCategory.AUTHENTICATION;
}
if (cause instanceof com.rabbitmq.client.ShutdownSignalException shutdown) {
int replyCode = replyCode(shutdown.getReason());
if (replyCode == 403) {
return FailureCategory.AUTHORIZATION;
}
if (replyCode >= 500) {
return FailureCategory.TRANSIENT_INFRASTRUCTURE;
}
return FailureCategory.PERMANENT_BUSINESS;
}
if (cause instanceof IOException) {
return FailureCategory.TRANSIENT_INFRASTRUCTURE;
}
return FailureCategory.PERMANENT_BUSINESS;
}
private static int replyCode(com.rabbitmq.client.Method reason) {
if (reason instanceof com.rabbitmq.client.AMQP.Channel.Close close) {
return close.getReplyCode();
}
if (reason instanceof com.rabbitmq.client.AMQP.Connection.Close close) {
return close.getReplyCode();
}
return -1;
}
private static Throwable unwrap(Throwable error) {
if (error instanceof java.util.concurrent.CompletionException && error.getCause() != null) {
return error.getCause();
}
return error;
}
private static String name(Throwable cause) {
return cause == null ? "unknown" : cause.getClass().getSimpleName();
}
}
@@ -1,72 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import java.util.Objects;
import org.springframework.amqp.core.Message;
/**
* Builds AMQP messages from platform publish requests.
*
* <p>The exchange and routing key come from the destination profile, never from the caller. A
* publisher that could choose its own routing key would be able to reach queues the destination's
* access policy never granted.
*/
public final class RabbitPublishMapper {
private final RabbitHeaderMapper headerMapper;
/** Creates a mapper with the default header mapper. */
public RabbitPublishMapper() {
this(new RabbitHeaderMapper());
}
/**
* Creates a mapper with an explicit header mapper.
*
* @param headerMapper the header mapper
*/
public RabbitPublishMapper(RabbitHeaderMapper headerMapper) {
this.headerMapper = Objects.requireNonNull(headerMapper, "headerMapper must not be null");
}
/**
* Converts a publish request into an AMQP message.
*
* @param request the publish request
* @return the AMQP message
*/
public Message toMessage(TransportPublishRequest request) {
Objects.requireNonNull(request, "request must not be null");
return new Message(
request.envelope().payload().bytes(), headerMapper.toProperties(request.envelope()));
}
/**
* Returns the exchange a destination publishes to.
*
* @param profile the destination profile
* @return the exchange name
*/
public String exchange(DestinationProfile profile) {
return profile
.physical()
.exchange()
.orElseThrow(
() ->
new MessagingConfigurationException(
"RABBIT_EXCHANGE_MISSING",
"destination has no Rabbit exchange: " + profile.name().value()));
}
/**
* Returns the routing key a destination publishes with.
*
* @param profile the destination profile
* @return the routing key
*/
public String routingKey(DestinationProfile profile) {
return profile.physical().routingKey().orElse("");
}
}
@@ -1,37 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.publish.BrokerPosition;
import java.util.Map;
import java.util.Objects;
/**
* A RabbitMQ exchange, routing key, and publish sequence coordinate.
*
* @param exchange the exchange published to
* @param routingKey the routing key used
* @param sequence the channel publish sequence number
*/
public record RabbitPublishReference(String exchange, String routingKey, long sequence)
implements BrokerPosition {
public RabbitPublishReference {
Objects.requireNonNull(exchange, "exchange must not be null");
Objects.requireNonNull(routingKey, "routingKey must not be null");
if (sequence < 0) {
throw new IllegalArgumentException("sequence must not be negative");
}
}
@Override
public String broker() {
return "rabbitmq";
}
@Override
public Map<String, String> diagnosticAttributes() {
return Map.of(
"exchange", exchange,
"routingKey", routingKey,
"sequence", Long.toString(sequence));
}
}
@@ -1,32 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.time.Duration;
import java.util.concurrent.CompletionStage;
/**
* The M2 request-reply capability.
*
* <p>Deliberately limited. Request-reply over a broker is a synchronous call wearing an
* asynchronous costume: it holds a correlation entry and a caller for the whole round trip, and it
* fails in ways a plain publish does not — a lost reply is indistinguishable from a slow one. It is
* offered with a mandatory deadline and no automatic retry, because retrying a request whose reply
* was merely late duplicates the work on the other side.
*/
public interface RabbitRequestReply {
/**
* Sends a request and awaits its correlated reply.
*
* @param destination the request destination
* @param request the encoded request envelope
* @param timeout how long to wait for the reply
* @return a stage completing with the reply, or failing on timeout
*/
CompletionStage<MessageEnvelope<EncodedMessage>> request(
MessageDestination<EncodedMessage> destination,
MessageEnvelope<EncodedMessage> request,
Duration timeout);
}
@@ -1,57 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
/**
* Describes the delayed retry queue a destination uses.
*
* <p>RabbitMQ has no native per-message delay in the core broker, so a retry queue is a queue with
* a message TTL whose dead letter exchange points back at the work queue: the message sits until
* the TTL expires and is then re-routed. Modelling this explicitly, rather than hiding it behind a
* plugin, keeps the behaviour reviewable — including its main caveat, that TTL expiry is evaluated
* at the head of the queue, so mixed delays in one retry queue do not expire independently.
*
* @param retryQueue the queue messages wait in
* @param deadLetterExchange the exchange expired messages are routed back through
* @param deadLetterRoutingKey the routing key expired messages are re-published with
* @param messageTtl how long messages wait
*/
public record RabbitRetryQueueTopology(
String retryQueue,
String deadLetterExchange,
String deadLetterRoutingKey,
Duration messageTtl) {
public RabbitRetryQueueTopology {
Objects.requireNonNull(messageTtl, "messageTtl must not be null");
if (retryQueue == null || retryQueue.isBlank()) {
throw new IllegalArgumentException("retryQueue must not be blank");
}
if (deadLetterExchange == null) {
throw new IllegalArgumentException("deadLetterExchange must not be null");
}
if (deadLetterRoutingKey == null) {
throw new IllegalArgumentException("deadLetterRoutingKey must not be null");
}
if (messageTtl.isNegative() || messageTtl.isZero()) {
throw new IllegalArgumentException("messageTtl must be positive");
}
}
/**
* Returns the queue arguments this topology requires.
*
* @return the AMQP queue arguments
*/
public Map<String, Object> queueArguments() {
Map<String, Object> arguments = new LinkedHashMap<>();
arguments.put("x-queue-type", "quorum");
arguments.put("x-message-ttl", messageTtl.toMillis());
arguments.put("x-dead-letter-exchange", deadLetterExchange);
arguments.put("x-dead-letter-routing-key", deadLetterRoutingKey);
return Map.copyOf(arguments);
}
}
@@ -1,179 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.security.BrokerCredentialProfile;
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
import dev.caskeleton.messaging.security.BrokerTlsPolicy;
import dev.caskeleton.messaging.security.CredentialRuntime;
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
import java.time.Instant;
import java.util.List;
import java.util.Objects;
/**
* Builds the AMQP connection settings from a validated security profile.
*
* <p>Credentials are resolved per connection attempt rather than cached in the factory. RabbitMQ
* client connections are long-lived and reconnect on their own, so a factory holding a credential
* from startup will happily reconnect with a revoked one for as long as the process runs — the
* reconnect is exactly the moment a rotated credential should take effect.
*
* <p>The password is returned inside a short-lived {@link AmqpCredentials} rather than assigned to
* a connection factory field, so the caller controls when it is cleared.
*/
public final class RabbitSecurityConfigurer {
private final CredentialRuntimeRegistry credentials;
private final BrokerTlsPolicy tlsPolicy;
/**
* Creates a configurer.
*
* @param credentials resolves and rotates credential material
* @param tlsPolicy validates the transport security posture
*/
public RabbitSecurityConfigurer(
CredentialRuntimeRegistry credentials, BrokerTlsPolicy tlsPolicy) {
this.credentials = Objects.requireNonNull(credentials, "credentials must not be null");
this.tlsPolicy = Objects.requireNonNull(tlsPolicy, "tlsPolicy must not be null");
}
/**
* Resolves the connection credentials for one role.
*
* @param profile the broker security profile
* @param credential the role credential to configure
* @param enabledProtocols the TLS protocol versions to enable
* @param now the current instant
* @return the AMQP connection credentials
*/
public AmqpCredentials configure(
BrokerSecurityProfile profile,
BrokerCredentialProfile credential,
List<String> enabledProtocols,
Instant now) {
Objects.requireNonNull(profile, "profile must not be null");
Objects.requireNonNull(credential, "credential must not be null");
Objects.requireNonNull(enabledProtocols, "enabledProtocols must not be null");
tlsPolicy.validate(profile, enabledProtocols);
return switch (credential) {
case BrokerCredentialProfile.UsernamePassword plain -> {
CredentialRuntime resolved = credentials.resolve(plain.credentialId(), now);
yield new AmqpCredentials(
"PLAIN", plain.credentialId(), resolved.material(), profile.tlsEnabled());
}
case BrokerCredentialProfile.MutualTls mutual -> {
// The certificate is the credential; there is no password to carry.
credentials.resolve(mutual.credentialId(), now);
yield new AmqpCredentials("EXTERNAL", mutual.credentialId(), new char[0], true);
}
case BrokerCredentialProfile.OAuth2 oauth -> {
CredentialRuntime resolved = credentials.resolve(oauth.credentialId(), now);
// RabbitMQ's OAuth 2 plugin takes the token in the password field of a PLAIN exchange.
yield new AmqpCredentials(
"PLAIN", oauth.credentialId(), resolved.material(), profile.tlsEnabled());
}
case BrokerCredentialProfile.SaslScram scram -> {
CredentialRuntime resolved = credentials.resolve(scram.credentialId(), now);
yield new AmqpCredentials(
"RABBIT-CR-DEMO", scram.credentialId(), resolved.material(), profile.tlsEnabled());
}
case BrokerCredentialProfile.Nkey ignored ->
throw new IllegalArgumentException(
"NKey credentials are a NATS concept, not an AMQP one");
};
}
/**
* One connection's resolved credentials.
*
* <p>A class rather than a record because the secret has to stay mutable to be cleared, and a
* record carrying a {@code char[]} would compare and hash it by identity — two credentials with
* the same material would be unequal, which is a surprise waiting in any future collection use.
*
* <p>{@link #clear()} overwrites the secret. The caller is expected to call it once the
* connection is established, so the material's lifetime is the handshake rather than the process.
*/
public static final class AmqpCredentials {
private final String mechanism;
private final String username;
private final char[] secret;
private final boolean tls;
/**
* Creates connection credentials.
*
* @param mechanism the SASL mechanism name
* @param username the AMQP username
* @param secret the password or token, taken by reference and cleared by {@link #clear()}
* @param tls whether the connection uses TLS
*/
public AmqpCredentials(String mechanism, String username, char[] secret, boolean tls) {
Objects.requireNonNull(secret, "secret must not be null");
if (mechanism == null || mechanism.isBlank()) {
throw new IllegalArgumentException("mechanism must not be blank");
}
if (username == null || username.isBlank()) {
throw new IllegalArgumentException("username must not be blank");
}
this.mechanism = mechanism;
this.username = username;
this.secret = secret;
this.tls = tls;
}
/**
* Returns the SASL mechanism name.
*
* @return the mechanism
*/
public String mechanism() {
return mechanism;
}
/**
* Returns the AMQP username.
*
* @return the username
*/
public String username() {
return username;
}
/**
* Returns a copy of the secret.
*
* @return the password or token
*/
public char[] secret() {
return secret.clone();
}
/**
* Reports whether the connection uses TLS.
*
* @return true when TLS is enabled
*/
public boolean tls() {
return tls;
}
/** Overwrites the secret in place. */
public void clear() {
java.util.Arrays.fill(secret, '\0');
}
/**
* Returns a representation that names the connection without revealing it.
*
* @return a safe description
*/
@Override
public String toString() {
return "AmqpCredentials[mechanism=%s, username=%s, tls=%s]"
.formatted(mechanism, username, tls);
}
}
}
@@ -1,84 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.error.MessageSettlementException;
import dev.caskeleton.messaging.api.settlement.SettlementController;
import dev.caskeleton.messaging.api.settlement.SettlementResult;
import java.time.Duration;
import java.util.Objects;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.atomic.AtomicBoolean;
/**
* Manual settlement for one RabbitMQ delivery.
*
* <p>Exactly one terminal call is allowed. A second one fails loudly rather than racing the first,
* because a duplicated {@code basic.ack} on a reused delivery tag acknowledges a <em>different</em>
* message — a failure mode that shows up as unexplained message loss under load, far from its
* cause.
*
* <p>{@code retry} does not use {@code basic.nack} with requeue. Requeueing puts the message back
* at the head of the queue with no delay, which turns a transient downstream failure into a hot
* loop; the delayed retry queue is used instead.
*/
public final class RabbitSettlementController implements SettlementController {
private final long deliveryTag;
private final RabbitSettlementOperations operations;
private final AtomicBoolean settled = new AtomicBoolean();
/**
* Creates a controller for one delivery.
*
* @param deliveryTag the AMQP delivery tag
* @param operations the channel operations, invoked on the container thread
*/
public RabbitSettlementController(long deliveryTag, RabbitSettlementOperations operations) {
this.deliveryTag = deliveryTag;
this.operations = Objects.requireNonNull(operations, "operations must not be null");
}
@Override
public CompletionStage<SettlementResult> ack() {
return terminal(() -> operations.ack(deliveryTag));
}
@Override
public CompletionStage<SettlementResult> retry(Duration delay) {
Objects.requireNonNull(delay, "delay must not be null");
return terminal(() -> operations.publishToRetryQueue(deliveryTag, delay));
}
@Override
public CompletionStage<SettlementResult> deadLetter(FailureDescriptor failure) {
Objects.requireNonNull(failure, "failure must not be null");
return terminal(() -> operations.deadLetter(deliveryTag, failure));
}
@Override
public CompletionStage<SettlementResult> reject(FailureDescriptor failure) {
Objects.requireNonNull(failure, "failure must not be null");
return terminal(() -> operations.discard(deliveryTag, failure));
}
/**
* Reports whether this delivery has already been settled.
*
* @return true once a terminal call has been made
*/
public boolean isSettled() {
return settled.get();
}
private CompletionStage<SettlementResult> terminal(
java.util.function.Supplier<CompletionStage<SettlementResult>> operation) {
if (!settled.compareAndSet(false, true)) {
return CompletableFuture.failedFuture(
new MessageSettlementException(
"SETTLEMENT_ALREADY_COMPLETED",
"delivery tag " + deliveryTag + " has already been settled"));
}
return operation.get();
}
}
@@ -1,50 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.settlement.SettlementResult;
import java.time.Duration;
import java.util.concurrent.CompletionStage;
/**
* The channel-side operations a settlement controller may perform.
*
* <p>Separated from the controller so the one-terminal-call guard is testable without an AMQP
* channel, and so the controller cannot reach anything the platform has not exposed.
*/
public interface RabbitSettlementOperations {
/**
* Acknowledges a delivery.
*
* @param deliveryTag the AMQP delivery tag
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> ack(long deliveryTag);
/**
* Publishes to the delayed retry queue, then acknowledges the source once confirmed.
*
* @param deliveryTag the AMQP delivery tag
* @param delay how long the message should wait
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> publishToRetryQueue(long deliveryTag, Duration delay);
/**
* Publishes to the dead letter destination, then acknowledges the source once confirmed.
*
* @param deliveryTag the AMQP delivery tag
* @param failure the sanitized failure
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> deadLetter(long deliveryTag, FailureDescriptor failure);
/**
* Discards a delivery without requeueing or dead lettering.
*
* @param deliveryTag the AMQP delivery tag
* @param failure the sanitized failure
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> discard(long deliveryTag, FailureDescriptor failure);
}
@@ -1,137 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* The declared shape of one RabbitMQ destination: exchange, queue, and the arguments that give the
* queue its guarantees.
*
* <p>Quorum queues are required for anything durable. A classic mirrored queue can lose
* acknowledged messages during a partition — the promotion of a stale mirror is exactly the case
* where "the broker confirmed it" stops being true — and RabbitMQ itself has deprecated them.
*
* <p>The dead-letter exchange is part of the topology rather than a runtime decision, because a
* queue's {@code x-dead-letter-exchange} can only be set at declaration. A destination that gains a
* dead-letter policy later cannot acquire one without deleting and recreating the queue, so the
* mismatch is caught here instead of surfacing when the first message needs parking.
*
* @param exchange the exchange to publish to
* @param exchangeType the exchange type
* @param routingKey the routing key
* @param queue the queue that receives the messages
* @param quorum whether the queue is a quorum queue
* @param deadLetterExchange the dead letter exchange, when the destination has one
* @param deadLetterRoutingKey the dead letter routing key, when the destination has one
* @param maxLength the queue length limit, when one is set
*/
public record RabbitTopologyProfile(
String exchange,
String exchangeType,
String routingKey,
String queue,
boolean quorum,
Optional<String> deadLetterExchange,
Optional<String> deadLetterRoutingKey,
Optional<Long> maxLength) {
/** RabbitMQ's argument key for a queue's type. */
public static final String QUEUE_TYPE = "x-queue-type";
/** RabbitMQ's argument key for a queue's dead letter exchange. */
public static final String DEAD_LETTER_EXCHANGE = "x-dead-letter-exchange";
/** RabbitMQ's argument key for a queue's dead letter routing key. */
public static final String DEAD_LETTER_ROUTING_KEY = "x-dead-letter-routing-key";
/** RabbitMQ's argument key for a queue's length limit. */
public static final String MAX_LENGTH = "x-max-length";
public RabbitTopologyProfile {
Objects.requireNonNull(deadLetterExchange, "deadLetterExchange must not be null");
Objects.requireNonNull(deadLetterRoutingKey, "deadLetterRoutingKey must not be null");
Objects.requireNonNull(maxLength, "maxLength must not be null");
requireText(exchange, "exchange");
requireText(exchangeType, "exchangeType");
requireText(routingKey, "routingKey");
requireText(queue, "queue");
if (deadLetterRoutingKey.isPresent() && deadLetterExchange.isEmpty()) {
throw new IllegalArgumentException(
"a dead letter routing key without a dead letter exchange routes nowhere");
}
if (maxLength.isPresent() && maxLength.get() < 1) {
throw new IllegalArgumentException("maxLength must be positive when set");
}
}
/**
* Refuses a topology that cannot back a durable destination.
*
* @param durable whether the destination promises durability
* @throws MessagingConfigurationException when a durable destination lacks a quorum queue
*/
public void requireSafeFor(boolean durable) {
if (durable && !quorum) {
throw new MessagingConfigurationException(
"CLASSIC_QUEUE_ON_DURABLE_DESTINATION",
"queue %s is not a quorum queue; a classic mirrored queue can lose acknowledged messages "
.formatted(queue)
+ "when a stale mirror is promoted during a partition");
}
}
/**
* Returns the arguments this queue must be declared with.
*
* @return the declaration arguments
*/
public Map<String, Object> queueArguments() {
Map<String, Object> arguments = new LinkedHashMap<>();
arguments.put(QUEUE_TYPE, quorum ? "quorum" : "classic");
deadLetterExchange.ifPresent(value -> arguments.put(DEAD_LETTER_EXCHANGE, value));
deadLetterRoutingKey.ifPresent(value -> arguments.put(DEAD_LETTER_ROUTING_KEY, value));
maxLength.ifPresent(value -> arguments.put(MAX_LENGTH, value));
return Map.copyOf(arguments);
}
/**
* Reports whether the broker will route a rejected message itself.
*
* @return true when the queue was declared with a dead letter exchange
*/
public boolean hasNativeDeadLetter() {
return deadLetterExchange.isPresent();
}
/**
* Returns a durable work-queue topology with a dead letter exchange.
*
* @param exchange the exchange
* @param routingKey the routing key
* @param queue the queue
* @param deadLetterExchange the dead letter exchange
* @return the topology profile
*/
public static RabbitTopologyProfile workQueue(
String exchange, String routingKey, String queue, String deadLetterExchange) {
return new RabbitTopologyProfile(
exchange,
"direct",
routingKey,
queue,
true,
Optional.of(deadLetterExchange),
Optional.of(routingKey),
Optional.empty());
}
private static void requireText(String value, String field) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(field + " must not be blank");
}
}
}
@@ -1,24 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.testkit.MessagingAdapterContract;
import dev.caskeleton.messaging.testkit.MessagingAdapterHarness;
import org.junit.jupiter.api.Nested;
/**
* Runs the shared adapter contract against the RabbitMQ adapter.
*
* <p>Identical to the Kafka run. Two brokers with completely different machinery — offsets and
* commits versus delivery tags and confirms — answering the same seven questions the same way is
* what makes the logical destination abstraction real rather than aspirational.
*/
class RabbitAdapterContractTest {
@Nested
class Contract extends MessagingAdapterContract {
@Override
protected MessagingAdapterHarness harness() {
return RabbitContractHarness.create();
}
}
}
@@ -1,167 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import java.time.Duration;
import java.util.concurrent.CompletionStage;
import org.junit.jupiter.api.Test;
class RabbitConfirmCoordinatorTest {
private static final ConfirmationRequirement REPLICATION =
ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK;
private final RabbitConfirmCoordinator coordinator = new RabbitConfirmCoordinator();
@Test
void aPlainConfirmIsAConfirmedPublish() {
CompletionStage<PublishResult> stage =
coordinator.awaiting(1L, "notification.work", "email", REPLICATION);
coordinator.confirmed(1L, true, Duration.ofMillis(4));
PublishResult result = stage.toCompletableFuture().join();
assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.ROUTED);
assertThat(result.evidence().confirmationLevel())
.isEqualTo(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK);
}
@Test
void aReturnFollowedByAConfirmIsRejectedAsUnroutable() {
CompletionStage<PublishResult> stage =
coordinator.awaiting(1L, "notification.work", "missing", REPLICATION);
coordinator.returned(1L);
coordinator.confirmed(1L, true, Duration.ofMillis(4));
PublishResult result = stage.toCompletableFuture().join();
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.UNROUTABLE);
assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE);
}
@Test
void aReturnAloneDoesNotCompleteThePublish() {
CompletionStage<PublishResult> stage =
coordinator.awaiting(1L, "notification.work", "missing", REPLICATION);
coordinator.returned(1L);
assertThat(stage.toCompletableFuture()).isNotDone();
assertThat(coordinator.pendingCount()).isEqualTo(1);
}
@Test
void aNackIsARejectedPublish() {
CompletionStage<PublishResult> stage =
coordinator.awaiting(2L, "notification.work", "email", REPLICATION);
coordinator.confirmed(2L, false, Duration.ofMillis(9));
PublishResult result = stage.toCompletableFuture().join();
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.failure()).isPresent();
}
@Test
void aMissingConfirmIsAmbiguousRatherThanFailed() {
CompletionStage<PublishResult> stage =
coordinator.awaiting(3L, "notification.work", "email", REPLICATION);
coordinator.timedOut(3L, Duration.ofSeconds(5));
PublishResult result = stage.toCompletableFuture().join();
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.mayHaveBeenStored()).isTrue();
assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE);
}
@Test
void aConfirmedPublishCarriesItsExchangeAndSequence() {
CompletionStage<PublishResult> stage =
coordinator.awaiting(7L, "notification.work", "email", REPLICATION);
coordinator.confirmed(7L, true, Duration.ofMillis(1));
PublishResult result = stage.toCompletableFuture().join();
assertThat(result.position()).isPresent();
assertThat(result.position().orElseThrow().diagnosticAttributes())
.containsEntry("exchange", "notification.work")
.containsEntry("routingKey", "email")
.containsEntry("sequence", "7");
}
@Test
void resolvingAPublishRemovesItFromThePendingSet() {
coordinator.awaiting(1L, "notification.work", "email", REPLICATION);
coordinator.confirmed(1L, true, Duration.ofMillis(1));
assertThat(coordinator.pendingCount()).isZero();
}
@Test
void anUnknownSequenceIsIgnoredRatherThanFailingTheChannel() {
coordinator.confirmed(99L, true, Duration.ofMillis(1));
coordinator.returned(99L);
coordinator.timedOut(99L, Duration.ofMillis(1));
assertThat(coordinator.pendingCount()).isZero();
}
@Test
@org.junit.jupiter.api.DisplayName("a multiple ack resolves every pending publish up to the tag")
void aMultipleAckResolvesEveryPendingPublish() {
RabbitConfirmCoordinator coordinator = new RabbitConfirmCoordinator();
java.util.concurrent.CompletableFuture<dev.caskeleton.messaging.api.publish.PublishResult>
first = coordinator.awaiting(1L, "orders", "created", REPLICATION).toCompletableFuture();
java.util.concurrent.CompletableFuture<dev.caskeleton.messaging.api.publish.PublishResult>
second = coordinator.awaiting(2L, "orders", "created", REPLICATION).toCompletableFuture();
java.util.concurrent.CompletableFuture<dev.caskeleton.messaging.api.publish.PublishResult>
third = coordinator.awaiting(3L, "orders", "created", REPLICATION).toCompletableFuture();
coordinator.confirmed(2L, true, true, java.time.Duration.ofMillis(5));
assertThat(first)
.as("the multiple flag was dropped, so everything below the tag waited forever")
.isCompleted();
assertThat(second).isCompleted();
assertThat(third).isNotCompleted();
assertThat(coordinator.pendingCount()).isEqualTo(1);
}
@Test
@org.junit.jupiter.api.DisplayName("a nack records the frame as transmitted")
void aNackRecordsTheFrameAsTransmitted() {
RabbitConfirmCoordinator coordinator = new RabbitConfirmCoordinator();
java.util.concurrent.CompletableFuture<dev.caskeleton.messaging.api.publish.PublishResult>
pending = coordinator.awaiting(1L, "orders", "created", REPLICATION).toCompletableFuture();
coordinator.confirmed(1L, false, java.time.Duration.ofMillis(5));
assertThat(pending.join().evidence().transmission())
.as("a NACK is the broker's answer to a frame it received")
.isEqualTo(dev.caskeleton.messaging.api.publish.TransmissionEvidence.TRANSMITTED);
}
@Test
@org.junit.jupiter.api.DisplayName(
"a closed channel completes every pending publish as ambiguous")
void aClosedChannelCompletesEveryPendingPublish() {
RabbitConfirmCoordinator coordinator = new RabbitConfirmCoordinator();
java.util.concurrent.CompletableFuture<dev.caskeleton.messaging.api.publish.PublishResult>
pending = coordinator.awaiting(1L, "orders", "created", REPLICATION).toCompletableFuture();
assertThat(coordinator.channelClosed(java.time.Duration.ofMillis(5))).isEqualTo(1);
assertThat(pending.join().completion())
.as("the frames were written; a channel close says nothing about whether they were stored")
.isEqualTo(dev.caskeleton.messaging.api.publish.PublishCompletion.AMBIGUOUS);
assertThat(coordinator.pendingCount()).isZero();
}
}
@@ -1,304 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.testkit.ContractMessage;
import dev.caskeleton.messaging.testkit.FaultController;
import dev.caskeleton.messaging.testkit.HandleOutcome;
import dev.caskeleton.messaging.testkit.MessagingAdapterHarness;
import dev.caskeleton.messaging.testkit.ObservedDelivery;
import java.time.Duration;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.atomic.AtomicLong;
/**
* Runs the shared adapter contract against the real RabbitMQ confirm model.
*
* <p>Publishes go through the production {@link RabbitConfirmCoordinator}, which is the piece that
* has to get AMQP's confirm and return ordering right. Driving it from the harness is the only way
* to exercise a lost confirm deterministically — a live broker will not drop one on request.
*
* <p>Settlement goes through the production {@link RabbitSettlementController}, so the
* one-terminal-call guard and the DLQ-before-ack ordering are the real ones.
*/
final class RabbitContractHarness implements MessagingAdapterHarness {
private static final int MAX_PAYLOAD_BYTES = 1_048_576;
private static final String EXCHANGE = "order.events";
private static final String ROUTING_KEY = "created";
private final RabbitConfirmCoordinator coordinator = new RabbitConfirmCoordinator();
private final AtomicLong sequence = new AtomicLong();
private final AtomicLong deliveryTag = new AtomicLong();
private final Faults faults = new Faults();
private final Deque<Pending> pending = new ArrayDeque<>();
private final List<MessageId> deadLetters = new ArrayList<>();
private final Set<MessageId> unsettled = new LinkedHashSet<>();
private boolean shuttingDown;
static RabbitContractHarness create() {
return new RabbitContractHarness();
}
@Override
public String brokerName() {
return "rabbitmq";
}
@Override
public FaultController faults() {
return faults;
}
@Override
public CompletionStage<PublishResult> publish(ContractMessage message) {
if (shuttingDown) {
return CompletableFuture.completedFuture(
rejectedLocally("SHUTTING_DOWN", "the consumer is draining and accepts no new work"));
}
if (message.envelope().payload().size() > MAX_PAYLOAD_BYTES) {
return CompletableFuture.completedFuture(
rejectedLocally(
"PAYLOAD_TOO_LARGE", "encoded payload exceeds " + MAX_PAYLOAD_BYTES + " bytes"));
}
long next = sequence.incrementAndGet();
CompletionStage<PublishResult> stage =
coordinator.awaiting(
next, EXCHANGE, ROUTING_KEY, ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK);
if (faults.consumeRejectPublish()) {
coordinator.confirmed(next, false, Duration.ofMillis(2));
} else if (faults.consumeDropPublishConfirmation()) {
coordinator.timedOut(next, Duration.ofSeconds(5));
} else {
coordinator.confirmed(next, true, Duration.ofMillis(2));
}
return stage.thenApply(
result -> {
if (result.completion() == PublishCompletion.CONFIRMED) {
pending.addLast(
new Pending(message.messageId(), deliveryTag.incrementAndGet(), 1, false));
}
return result;
});
}
@Override
public List<ObservedDelivery> drain(HandleOutcome outcome) {
List<Pending> batch = new ArrayList<>(pending);
pending.clear();
List<ObservedDelivery> observed = new ArrayList<>();
for (Pending delivery : batch) {
RabbitSettlementController controller =
new RabbitSettlementController(delivery.deliveryTag(), new HarnessOperations(delivery));
boolean settled =
switch (outcome) {
case SUCCESS -> join(controller.ack());
case RETRY -> join(controller.retry(Duration.ofSeconds(1)));
case DEAD_LETTER ->
join(
controller.deadLetter(
FailureDescriptor.of(
FailureCategory.PERMANENT_BUSINESS,
"CONTRACT_FAILURE",
"permanent failure")));
};
observed.add(
new ObservedDelivery(
delivery.messageId(), delivery.attempt(), delivery.redelivered(), settled));
}
return List.copyOf(observed);
}
private static boolean join(
CompletionStage<dev.caskeleton.messaging.api.settlement.SettlementResult> stage) {
return stage.toCompletableFuture().join().completion()
== dev.caskeleton.messaging.api.settlement.SettlementCompletion.SETTLED;
}
private void redeliver(Pending delivery) {
pending.addLast(
new Pending(
delivery.messageId(), deliveryTag.incrementAndGet(), delivery.attempt() + 1, true));
}
@Override
public List<MessageId> deadLettered() {
return List.copyOf(deadLetters);
}
@Override
public List<MessageId> unsettled() {
return List.copyOf(unsettled);
}
@Override
public void beginShutdown() {
shuttingDown = true;
}
@Override
public boolean isAcceptingWork() {
return !shuttingDown;
}
@Override
public void close() {
pending.clear();
}
private static PublishResult rejectedLocally(String code, String message) {
return new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
Duration.ZERO,
Optional.of(FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, code, message)));
}
/** One message in flight on the channel. */
private record Pending(MessageId messageId, long deliveryTag, int attempt, boolean redelivered) {}
/** The channel operations the settlement controller drives. */
private final class HarnessOperations implements RabbitSettlementOperations {
private final Pending delivery;
private HarnessOperations(Pending delivery) {
this.delivery = delivery;
}
@Override
public CompletionStage<dev.caskeleton.messaging.api.settlement.SettlementResult> ack(long tag) {
if (faults.consumeDropSettlementConfirmation()) {
unsettled.add(delivery.messageId());
redeliver(delivery);
return CompletableFuture.completedFuture(unknownSettlement());
}
unsettled.remove(delivery.messageId());
return CompletableFuture.completedFuture(
dev.caskeleton.messaging.api.settlement.SettlementResult.settled());
}
@Override
public CompletionStage<dev.caskeleton.messaging.api.settlement.SettlementResult>
publishToRetryQueue(long tag, Duration delay) {
unsettled.add(delivery.messageId());
redeliver(delivery);
return CompletableFuture.completedFuture(unknownSettlement());
}
/** Publishes to the dead letter destination first, and only then acknowledges the source. */
@Override
public CompletionStage<dev.caskeleton.messaging.api.settlement.SettlementResult> deadLetter(
long tag, FailureDescriptor failure) {
if (faults.deadLetterPublishFails()) {
unsettled.add(delivery.messageId());
redeliver(delivery);
return CompletableFuture.completedFuture(unknownSettlement());
}
deadLetters.add(delivery.messageId());
unsettled.remove(delivery.messageId());
return CompletableFuture.completedFuture(
dev.caskeleton.messaging.api.settlement.SettlementResult.settled());
}
@Override
public CompletionStage<dev.caskeleton.messaging.api.settlement.SettlementResult> discard(
long tag, FailureDescriptor failure) {
unsettled.remove(delivery.messageId());
return CompletableFuture.completedFuture(
dev.caskeleton.messaging.api.settlement.SettlementResult.settled());
}
private dev.caskeleton.messaging.api.settlement.SettlementResult unknownSettlement() {
return new dev.caskeleton.messaging.api.settlement.SettlementResult(
dev.caskeleton.messaging.api.settlement.SettlementCompletion.UNKNOWN,
dev.caskeleton.messaging.api.settlement.SettlementEvidence.unknown(),
Optional.of(
FailureDescriptor.of(
FailureCategory.AMBIGUOUS,
"SETTLEMENT_UNKNOWN",
"the settlement was not confirmed")));
}
}
/** One-shot fault flags. */
private static final class Faults implements FaultController {
private boolean dropPublishConfirmation;
private boolean dropSettlementConfirmation;
private boolean failDeadLetterPublish;
private boolean rejectPublish;
@Override
public void dropPublishConfirmation() {
dropPublishConfirmation = true;
}
@Override
public void dropSettlementConfirmation() {
dropSettlementConfirmation = true;
}
@Override
public void failDeadLetterPublish() {
failDeadLetterPublish = true;
}
@Override
public void rejectPublish() {
rejectPublish = true;
}
@Override
public void reset() {
dropPublishConfirmation = false;
dropSettlementConfirmation = false;
failDeadLetterPublish = false;
rejectPublish = false;
}
boolean consumeDropPublishConfirmation() {
boolean active = dropPublishConfirmation;
dropPublishConfirmation = false;
return active;
}
boolean consumeDropSettlementConfirmation() {
boolean active = dropSettlementConfirmation;
dropSettlementConfirmation = false;
return active;
}
boolean consumeRejectPublish() {
boolean active = rejectPublish;
rejectPublish = false;
return active;
}
boolean deadLetterPublishFails() {
return failDeadLetterPublish;
}
}
}
@@ -1,152 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.CorrelationId;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.api.header.HeaderName;
import dev.caskeleton.messaging.api.header.HeaderValue;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.amqp.core.Message;
import org.springframework.amqp.core.MessageProperties;
/**
* What an envelope still holds after it has been through RabbitMQ.
*
* <p>The publish and delivery mappers were written against each other's headers but never checked
* as one trip, so the application's own headers were dropped on the way back and the retry
* bookkeeping went with them — an attempt counter that restarts on every hop caps no redeliveries
* at all.
*/
class RabbitEnvelopeRoundTripTest {
private static final Instant NOW = Instant.parse("2026-08-15T10:00:00Z");
private final RabbitHeaderMapper headerMapper = new RabbitHeaderMapper();
private final RabbitDeliveryMapper deliveryMapper = new RabbitDeliveryMapper(headerMapper);
@Test
@DisplayName("an application header survives the trip through the broker")
void anApplicationHeaderSurvivesTheTrip() {
MessageEnvelope<EncodedMessage> published =
envelope(
MessageHeaders.application(
Map.of(new HeaderName("x-source-system"), new HeaderValue("erp"))));
MessageEnvelope<EncodedMessage> delivered = roundTrip(published);
assertThat(delivered.headers().find("x-source-system"))
.map(HeaderValue::value)
.as("a header the producer wrote and the consumer cannot read is a header nobody has")
.hasValue("erp");
}
@Test
@DisplayName("the tenant survives the trip instead of arriving as no tenant at all")
void theTenantSurvivesTheTrip() {
MessageEnvelope<EncodedMessage> published =
envelope(MessageHeaders.empty())
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"));
MessageEnvelope<EncodedMessage> delivered = roundTrip(published);
assertThat(delivered.tenantContext())
.as("an AMQP message carries no ambient tenant, so an unwritten tenant is an absent one")
.contains(new dev.caskeleton.messaging.api.TenantContext("acme"));
}
@Test
@DisplayName("the retry attempt survives the trip instead of restarting at one")
void theRetryAttemptSurvivesTheTrip() {
MessageEnvelope<EncodedMessage> delivered = roundTrip(retryStamped(3));
assertThat(delivered.headers().find(ReservedHeaders.RETRY_ATTEMPT))
.map(HeaderValue::value)
.as("an attempt counter that resets on every hop caps nothing")
.hasValue("3");
}
@Test
@DisplayName("a retry-stamped envelope can be published to its retry queue")
void aRetryStampedEnvelopeCanBePublished() {
assertThatCode(() -> headerMapper.toProperties(retryStamped(2)))
.as("the platform's own bookkeeping is not message content forging an identity")
.doesNotThrowAnyException();
}
@Test
@DisplayName("a header restating the message id is still refused")
void aForgedMessageIdIsStillRefused() {
MessageEnvelope<EncodedMessage> forged =
envelope(
MessageHeaders.platform(
Map.of(new HeaderName(ReservedHeaders.MESSAGE_ID), new HeaderValue("forged"))));
assertThatThrownBy(() -> headerMapper.toProperties(forged))
.isInstanceOf(MessagingConfigurationException.class);
}
@Test
@DisplayName("identity is read from its field, not duplicated into the header map")
void identityIsNotDuplicatedIntoTheHeaderMap() {
MessageEnvelope<EncodedMessage> delivered = roundTrip(envelope(MessageHeaders.empty()));
assertThat(delivered.headers().find(ReservedHeaders.MESSAGE_ID))
.as("a copy that can drift from the field gives the same message two identities")
.isEmpty();
}
private MessageEnvelope<EncodedMessage> roundTrip(MessageEnvelope<EncodedMessage> published) {
MessageProperties properties = headerMapper.toProperties(published);
return deliveryMapper.toEnvelope(new Message(published.payload().bytes(), properties));
}
private static MessageEnvelope<EncodedMessage> retryStamped(int attempt) {
Map<HeaderName, HeaderValue> headers = new LinkedHashMap<>();
headers.put(
new HeaderName(ReservedHeaders.RETRY_ATTEMPT), new HeaderValue(Integer.toString(attempt)));
headers.put(new HeaderName(ReservedHeaders.LAST_FAILURE_AT), new HeaderValue(NOW.toString()));
return envelope(MessageHeaders.platform(headers));
}
private static MessageEnvelope<EncodedMessage> envelope(MessageHeaders headers) {
return new MessageEnvelope<>(
MessageId.newId(),
new MessageType("order.created"),
new SchemaVersion(1),
NOW,
Optional.of(NOW),
new ProducerId("order-api"),
Optional.of(new CorrelationId("wf-1")),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
headers,
new EncodedMessage(
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
ContentType.JSON,
Optional.empty()));
}
}
@@ -1,68 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import org.junit.jupiter.api.Test;
class RabbitProfileValidatorTest {
private final RabbitProfileValidator validator = new RabbitProfileValidator();
@Test
void stableProducerRequiresConfirms() {
assertThatThrownBy(() -> validator.validate(RabbitProfileFixtures.withoutConfirms()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("publisher confirms");
}
@Test
void stableProducerRequiresReturnsBecauseAConfirmDoesNotProveRouting() {
assertThatThrownBy(() -> validator.validate(RabbitProfileFixtures.withoutReturns()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("publisher returns");
}
@Test
void stableProducerRequiresMandatoryRouting() {
assertThatThrownBy(() -> validator.validate(RabbitProfileFixtures.withoutMandatory()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("mandatory");
}
@Test
void consumerAutoAckIsForbidden() {
assertThatThrownBy(() -> validator.validate(RabbitProfileFixtures.withAutoAck()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("auto ack");
}
@Test
void productionRequiresTlsAndAuthentication() {
assertThatThrownBy(() -> validator.validate(RabbitProfileFixtures.productionWithoutTls()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("TLS");
}
@Test
void aDurableWorkQueueMustBeAQuorumQueue() {
assertThatThrownBy(
() ->
validator.validateDestination(
RabbitProfileFixtures.workQueueDestination(),
RabbitProfileFixtures.withoutQuorumQueues()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("quorum");
}
@Test
void aStableProfileAndDestinationValidate() {
assertThatCode(
() -> {
validator.validate(RabbitProfileFixtures.stable());
validator.validateDestination(
RabbitProfileFixtures.workQueueDestination(), RabbitProfileFixtures.stable());
})
.doesNotThrowAnyException();
}
}
@@ -1,341 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.CorrelationId;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.schema.EncodedMessage;
import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator;
import dev.caskeleton.messaging.transport.TransportConsumerSpec;
import dev.caskeleton.messaging.transport.TransportDelivery;
import dev.caskeleton.messaging.transport.TransportPublishRequest;
import dev.caskeleton.messaging.transport.TransportPublishResult;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.atomic.AtomicLong;
import org.junit.jupiter.api.Test;
import org.springframework.amqp.core.Message;
class RabbitRuntimeTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private final AtomicLong sequence = new AtomicLong();
private final List<Message> published = new ArrayList<>();
private final List<TransportDelivery> handled = new ArrayList<>();
private RabbitMessagingTransport transport() {
return new RabbitMessagingTransport(
"rabbit-primary",
1,
new RabbitChannelPublisher() {
@Override
public long nextPublishSequence() {
return sequence.incrementAndGet();
}
@Override
public void publish(
long sequenceNumber,
String exchange,
String routingKey,
Message message,
boolean mandatory) {
published.add(message);
}
});
}
@Test
void aConfirmedPublishReportsRoutedWithReplicationEvidence() {
RabbitMessagingTransport transport = transport();
CompletionStage<TransportPublishResult> stage = transport.publish(request());
transport.onConfirm(1L, true, Duration.ofMillis(3));
var result = stage.toCompletableFuture().join().result();
assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.ROUTED);
}
@Test
void aReturnedThenConfirmedPublishIsRejectedAsUnroutable() {
RabbitMessagingTransport transport = transport();
CompletionStage<TransportPublishResult> stage = transport.publish(request());
transport.onReturn(1L);
transport.onConfirm(1L, true, Duration.ofMillis(3));
var result = stage.toCompletableFuture().join().result();
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.UNROUTABLE);
}
@Test
void aMissingConfirmExpiresWithoutAnExternalTimeoutCallback() throws Exception {
try (RabbitMessagingTransport timed =
new RabbitMessagingTransport(
"rabbit-primary",
1,
new RabbitChannelPublisher() {
@Override
public long nextPublishSequence() {
return sequence.incrementAndGet();
}
@Override
public void publish(
long sequenceNumber,
String exchange,
String routingKey,
Message message,
boolean mandatory) {
published.add(message);
}
},
Duration.ofMillis(20))) {
CompletionStage<TransportPublishResult> stage = timed.publish(request());
var result =
stage.toCompletableFuture().get(1, java.util.concurrent.TimeUnit.SECONDS).result();
assertThat(result.completion()).isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(timed.pendingConfirms()).isZero();
}
}
@Test
void aMissingConfirmIsAmbiguous() {
RabbitMessagingTransport transport = transport();
CompletionStage<TransportPublishResult> stage = transport.publish(request());
transport.onConfirmTimeout(1L, Duration.ofSeconds(5));
assertThat(stage.toCompletableFuture().join().result().mayHaveBeenStored()).isTrue();
}
@Test
void anOversizedPayloadNeverReachesTheChannel() {
RabbitMessagingTransport transport = transport();
var result =
transport.publish(request(new byte[1_048_577])).toCompletableFuture().join().result();
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(published).isEmpty();
}
@Test
void aClosedTransportRefusesPublishesLocally() {
RabbitMessagingTransport transport = transport();
transport.close();
var result = transport.publish(request()).toCompletableFuture().join().result();
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(transport.isAcceptingWork()).isFalse();
assertThat(published).isEmpty();
}
@Test
void theHeaderRoundTripPreservesIdentityAndProvenance() {
RabbitHeaderMapper headers = new RabbitHeaderMapper();
MessageEnvelope<EncodedMessage> envelope = envelope(new byte[] {1, 2, 3});
var properties = headers.toProperties(envelope);
assertThat(headers.value(properties, ReservedHeaders.MESSAGE_ID))
.isEqualTo(envelope.messageId().value().toString());
assertThat(headers.value(properties, ReservedHeaders.MESSAGE_TYPE)).isEqualTo("order.created");
assertThat(headers.value(properties, ReservedHeaders.CORRELATION_ID)).isEqualTo("wf-1");
assertThat(properties.getCorrelationId()).isEqualTo("wf-1");
}
@Test
void aDeliveryIsRebuiltFromItsHeaders() {
RabbitHeaderMapper headers = new RabbitHeaderMapper();
MessageEnvelope<EncodedMessage> original = envelope(new byte[] {1, 2, 3});
Message message = new Message(new byte[] {1, 2, 3}, headers.toProperties(original));
var restored = new RabbitDeliveryMapper().toEnvelope(message);
assertThat(restored.messageId()).isEqualTo(original.messageId());
assertThat(restored.messageType()).isEqualTo(original.messageType());
assertThat(restored.schemaVersion()).isEqualTo(original.schemaVersion());
assertThat(restored.payload().bytes()).containsExactly(1, 2, 3);
}
@Test
void theConsumerDispatchesAndSettlesThroughTheController() {
RecordingOperations operations = new RecordingOperations();
RabbitConsumerRegistrar registrar = registrar(operations, this::acknowledge);
boolean accepted = registrar.onMessage(deliveredMessage(7L), NOW);
assertThat(accepted).isTrue();
assertThat(handled).hasSize(1);
assertThat(operations.calls).containsExactly("ack:7");
}
@Test
void aPausedQueueRefusesDeliveriesSoTheBrokerRedeliversThem() {
RecordingOperations operations = new RecordingOperations();
RabbitConsumerRegistrar registrar = registrar(operations, this::acknowledge);
registrar.pause("").toCompletableFuture().join();
boolean accepted = registrar.onMessage(deliveredMessage(7L), NOW);
assertThat(accepted).isFalse();
assertThat(handled).isEmpty();
assertThat(operations.calls).isEmpty();
}
@Test
void drainingRefusesNewDeliveries() {
RecordingOperations operations = new RecordingOperations();
GracefulShutdownCoordinator shutdown = new GracefulShutdownCoordinator(Duration.ofSeconds(30));
try (RabbitConsumerRegistrar registrar =
new RabbitConsumerRegistrar(
new TransportConsumerSpec(
RabbitProfileFixtures.workQueueDestination(), this::acknowledge),
operations,
shutdown)) {
shutdown.beginDrain(NOW);
boolean accepted = registrar.onMessage(deliveredMessage(7L), NOW);
assertThat(accepted).isFalse();
assertThat(operations.calls).isEmpty();
}
}
@Test
void anUndecodableMessageIsDiscardedRatherThanRequeued() {
RecordingOperations operations = new RecordingOperations();
RabbitConsumerRegistrar registrar = registrar(operations, this::acknowledge);
Message malformed =
new Message(new byte[] {1}, new org.springframework.amqp.core.MessageProperties());
malformed.getMessageProperties().setDeliveryTag(9L);
boolean accepted = registrar.onMessage(malformed, NOW);
assertThat(accepted).isTrue();
assertThat(handled).isEmpty();
assertThat(operations.calls).containsExactly("discard:9");
}
private RabbitConsumerRegistrar registrar(
RabbitSettlementOperations operations,
java.util.function.Function<TransportDelivery, CompletionStage<Void>> sink) {
return new RabbitConsumerRegistrar(
new TransportConsumerSpec(RabbitProfileFixtures.workQueueDestination(), sink),
operations,
new GracefulShutdownCoordinator(Duration.ofSeconds(30)));
}
private CompletionStage<Void> acknowledge(TransportDelivery delivery) {
handled.add(delivery);
delivery.settlement().acknowledge().toCompletableFuture().join();
return CompletableFuture.completedFuture(null);
}
private Message deliveredMessage(long deliveryTag) {
Message message =
new Message(
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
new RabbitHeaderMapper().toProperties(envelope(new byte[] {1})));
message.getMessageProperties().setDeliveryTag(deliveryTag);
message.getMessageProperties().setConsumerQueue("notification.email.q");
return message;
}
private TransportPublishRequest request() {
return request("{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8));
}
private TransportPublishRequest request(byte[] payload) {
return new TransportPublishRequest(
RabbitProfileFixtures.workQueueDestination(), envelope(payload), PublishOptions.defaults());
}
private MessageEnvelope<EncodedMessage> envelope(byte[] payload) {
return new MessageEnvelope<>(
MessageId.newId(),
new MessageType("order.created"),
new SchemaVersion(1),
NOW,
Optional.of(NOW),
new ProducerId("order-api"),
Optional.of(new CorrelationId("wf-1")),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
new EncodedMessage(payload, ContentType.JSON, Optional.empty()));
}
@Test
@org.junit.jupiter.api.DisplayName("a handler failure is retried, not discarded as undecodable")
void aHandlerFailureIsRetriedNotDiscarded() {
RecordingOperations operations = new RecordingOperations();
RabbitConsumerRegistrar registrar =
registrar(
operations,
delivery -> {
throw new IllegalStateException("the projection is down");
});
registrar.onMessage(deliveredMessage(11), NOW);
assertThat(operations.calls)
.as("one catch covered decode, handler and settlement, so a retryable failure was deleted")
.containsExactly("retry:11:PT0S");
}
@Test
@org.junit.jupiter.api.DisplayName("a handler that never settles does not acknowledge")
void aHandlerThatNeverSettlesDoesNotAcknowledge() {
RecordingOperations operations = new RecordingOperations();
RabbitConsumerRegistrar registrar =
registrar(operations, delivery -> CompletableFuture.completedFuture(null));
registrar.onMessage(deliveredMessage(12), NOW);
assertThat(operations.calls)
.as("acknowledging on the handler's behalf silently drops a message nobody handled")
.containsExactly("retry:12:PT0S");
}
@Test
@org.junit.jupiter.api.DisplayName("a delivery after close is refused")
void aDeliveryAfterCloseIsRefused() {
RecordingOperations operations = new RecordingOperations();
RabbitConsumerRegistrar registrar =
registrar(operations, delivery -> CompletableFuture.completedFuture(null));
registrar.close();
assertThat(registrar.onMessage(deliveredMessage(13), NOW))
.as("close only flipped a flag that onMessage never read")
.isFalse();
}
}
@@ -1,105 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.settlement.SettlementResult;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import org.junit.jupiter.api.Test;
class RabbitSettlementControllerTest {
private static final FailureDescriptor FAILURE =
FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, "REJECTED", "rejected");
@Test
void acknowledgesExactlyOnce() {
RecordingOperations operations = new RecordingOperations();
RabbitSettlementController controller = new RabbitSettlementController(7L, operations);
controller.ack().toCompletableFuture().join();
assertThat(operations.calls).containsExactly("ack:7");
assertThat(controller.isSettled()).isTrue();
}
@Test
void aSecondTerminalCallFailsRatherThanRacingTheFirst() {
RecordingOperations operations = new RecordingOperations();
RabbitSettlementController controller = new RabbitSettlementController(7L, operations);
controller.ack().toCompletableFuture().join();
assertThat(controller.ack().toCompletableFuture()).isCompletedExceptionally();
assertThat(operations.calls).containsExactly("ack:7");
}
@Test
void mixingTerminalOperationsIsAlsoRefused() {
RecordingOperations operations = new RecordingOperations();
RabbitSettlementController controller = new RabbitSettlementController(7L, operations);
controller.deadLetter(FAILURE).toCompletableFuture().join();
assertThat(controller.ack().toCompletableFuture()).isCompletedExceptionally();
assertThat(operations.calls).containsExactly("deadLetter:7");
}
@Test
void retryGoesToTheDelayedQueueRatherThanRequeueingImmediately() {
RecordingOperations operations = new RecordingOperations();
RabbitSettlementController controller = new RabbitSettlementController(7L, operations);
controller.retry(Duration.ofSeconds(30)).toCompletableFuture().join();
assertThat(operations.calls).containsExactly("retry:7:PT30S");
}
@Test
void aRetryQueueCarriesTtlAndADeadLetterRouteBackToTheWorkQueue() {
RabbitRetryQueueTopology topology =
new RabbitRetryQueueTopology(
"notification.email.retry.q", "notification.work", "email", Duration.ofSeconds(30));
assertThat(topology.queueArguments())
.containsEntry("x-queue-type", "quorum")
.containsEntry("x-message-ttl", 30_000L)
.containsEntry("x-dead-letter-exchange", "notification.work")
.containsEntry("x-dead-letter-routing-key", "email");
}
}
/** Records which channel operation the controller invoked. */
final class RecordingOperations implements RabbitSettlementOperations {
final List<String> calls = new ArrayList<>();
@Override
public CompletionStage<SettlementResult> ack(long deliveryTag) {
calls.add("ack:" + deliveryTag);
return CompletableFuture.completedFuture(SettlementResult.settled());
}
@Override
public CompletionStage<SettlementResult> publishToRetryQueue(long deliveryTag, Duration delay) {
calls.add("retry:" + deliveryTag + ":" + delay);
return CompletableFuture.completedFuture(SettlementResult.settled());
}
@Override
public CompletionStage<SettlementResult> deadLetter(long deliveryTag, FailureDescriptor failure) {
calls.add("deadLetter:" + deliveryTag);
return CompletableFuture.completedFuture(SettlementResult.settled());
}
@Override
public CompletionStage<SettlementResult> discard(long deliveryTag, FailureDescriptor failure) {
calls.add("discard:" + deliveryTag);
return CompletableFuture.completedFuture(SettlementResult.settled());
}
}
@@ -1,253 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.api.publish.PublishCompletion;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
import java.io.IOException;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class RabbitTopologyAndBatchTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static RabbitTopologyProfile quorumWithDlx() {
return RabbitTopologyProfile.workQueue(
"notification.work", "email", "notification.email.q", "notification.dlx");
}
private static RabbitTopologyProfile classic() {
return new RabbitTopologyProfile(
"notification.work",
"direct",
"email",
"notification.email.q",
false,
Optional.empty(),
Optional.empty(),
Optional.empty());
}
@Test
void aDurableDestinationRequiresAQuorumQueue() {
assertThatThrownBy(() -> classic().requireSafeFor(true))
.as("a promoted stale mirror loses messages the broker already confirmed")
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("quorum");
}
@Test
void aQuorumQueueSatisfiesADurableDestination() {
assertThatCode(() -> quorumWithDlx().requireSafeFor(true)).doesNotThrowAnyException();
}
@Test
void theQueueArgumentsCarryTheDeclaredGuarantees() {
assertThat(quorumWithDlx().queueArguments())
.containsEntry(RabbitTopologyProfile.QUEUE_TYPE, "quorum")
.containsEntry(RabbitTopologyProfile.DEAD_LETTER_EXCHANGE, "notification.dlx");
}
@Test
void aDeadLetterRoutingKeyWithoutAnExchangeIsRejected() {
assertThatThrownBy(
() ->
new RabbitTopologyProfile(
"x",
"direct",
"k",
"q",
true,
Optional.empty(),
Optional.of("k"),
Optional.empty()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("routes nowhere");
}
@Test
void nativeDeadLetterNeedsBothADeclarationAndAVerifiedBinding() {
assertThat(new RabbitNativeDeadLetterCapability(quorumWithDlx(), true).mayUseNativeDeadLetter())
.isTrue();
assertThat(
new RabbitNativeDeadLetterCapability(quorumWithDlx(), false).mayUseNativeDeadLetter())
.as("an unbound dead letter exchange discards the message while the reject still succeeds")
.isFalse();
}
@Test
void aQueueWithoutADeadLetterExchangeFallsBackToThePlatformPublish() {
RabbitNativeDeadLetterCapability capability =
new RabbitNativeDeadLetterCapability(classic(), true);
assertThat(capability.requiresPlatformPublish()).isTrue();
assertThat(capability.reasonForPlatformPublish()).contains("without a dead letter exchange");
}
@Test
void theUnboundReasonExplainsTheSilentDiscard() {
assertThat(
new RabbitNativeDeadLetterCapability(quorumWithDlx(), false).reasonForPlatformPublish())
.contains("silently")
.contains("reporting success");
}
@Test
void aFailureBeforeTheFrameWasWrittenIsADefinitiveRejection() {
PublishResult result =
new RabbitPublishFailureClassifier()
.classify(new IllegalStateException("channel closed"), false, Duration.ofMillis(3));
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED);
}
@Test
void aFailureAfterTheFrameWasWrittenIsAmbiguous() {
PublishResult result =
new RabbitPublishFailureClassifier()
.classify(new IOException("connection reset"), true, Duration.ofMillis(3));
assertThat(result.completion())
.as("the broker may hold the message and only the confirm was lost")
.isEqualTo(PublishCompletion.AMBIGUOUS);
assertThat(result.evidence().transmission())
.isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED);
}
@Test
void authenticationFailureUsesTheTypedRabbitSignal() {
PublishResult result =
new RabbitPublishFailureClassifier()
.classify(
new com.rabbitmq.client.AuthenticationFailureException("bad credentials"),
false,
Duration.ofMillis(3));
assertThat(result.failure())
.hasValueSatisfying(
failure ->
assertThat(failure.category())
.isEqualTo(dev.caskeleton.messaging.api.error.FailureCategory.AUTHENTICATION));
}
@Test
void accessRefusedReplyCodeIsAuthorizationRatherThanBusinessRejection() {
com.rabbitmq.client.ShutdownSignalException accessRefused =
new com.rabbitmq.client.ShutdownSignalException(
false,
false,
new com.rabbitmq.client.impl.AMQImpl.Channel.Close(403, "ACCESS_REFUSED", 60, 40),
null);
PublishResult result =
new RabbitPublishFailureClassifier().classify(accessRefused, false, Duration.ofMillis(3));
assertThat(result.failure())
.hasValueSatisfying(
failure ->
assertThat(failure.category())
.isEqualTo(dev.caskeleton.messaging.api.error.FailureCategory.AUTHORIZATION));
}
@Test
void aNackIsRejectedButStillCountsAsTransmitted() {
PublishResult result = new RabbitPublishFailureClassifier().nacked(Duration.ofMillis(3));
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.TRANSMITTED);
}
@Test
void aBatchIsReleasedOnceItIsFull() {
RabbitBatchConsumerRegistrar registrar =
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 3, Duration.ofSeconds(5));
assertThat(registrar.add(1, NOW)).isEmpty();
assertThat(registrar.add(2, NOW)).isEmpty();
assertThat(registrar.add(3, NOW))
.hasValueSatisfying(batch -> assertThat(batch.deliveryTags()).containsExactly(1L, 2L, 3L));
}
@Test
void aPartialBatchIsReleasedOnceItsOldestDeliveryGoesStale() {
RabbitBatchConsumerRegistrar registrar =
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 100, Duration.ofSeconds(5));
registrar.add(1, NOW);
assertThat(registrar.releaseIfStale(NOW.plusSeconds(1))).isEmpty();
assertThat(registrar.releaseIfStale(NOW.plusSeconds(6)))
.as("a quiet queue would otherwise hold its last messages unacknowledged indefinitely")
.isPresent();
}
@Test
void anAccumulatedBatchIsNotSettlableAsAUnit() {
RabbitBatchConsumerRegistrar registrar =
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 2, Duration.ofSeconds(5));
registrar.add(1, NOW);
assertThat(registrar.add(2, NOW))
.hasValueSatisfying(
batch ->
assertThat(batch.metadata().settlableAsBatch())
.as("AMQP multiple-ack settles work that is still in flight")
.isFalse());
}
@Test
void anAccumulatedBatchNamesExactlyOneOrderingUnit() {
RabbitBatchConsumerRegistrar registrar =
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 1, Duration.ofSeconds(5));
assertThat(registrar.add(1, NOW))
.hasValueSatisfying(
batch -> assertThat(batch.metadata().isSafeForOrderedDestination()).isTrue());
}
@Test
void aPrefetchBelowTheBatchSizeWouldDeadlockAndIsRefused() {
RabbitBatchConsumerRegistrar registrar =
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 50, Duration.ofSeconds(5));
assertThatThrownBy(() -> registrar.requirePrefetchFor(10))
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("prefetch");
assertThatCode(() -> registrar.requirePrefetchFor(100)).doesNotThrowAnyException();
}
@Test
void aZeroBatchAgeIsRefusedBecauseItStrandsQuietQueues() {
assertThatThrownBy(
() ->
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 10, Duration.ZERO))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void drainingReleasesWhateverIsPendingForShutdown() {
RabbitBatchConsumerRegistrar registrar =
new RabbitBatchConsumerRegistrar(
RabbitProfileFixtures.workQueueDestination(), 100, Duration.ofSeconds(5));
registrar.add(1, NOW);
registrar.add(2, NOW);
assertThat(registrar.drain(NOW))
.hasValueSatisfying(batch -> assertThat(batch.deliveryTags()).hasSize(2));
assertThat(registrar.pending()).isZero();
assertThat(registrar.drain(NOW)).isEmpty();
}
}
@@ -1,118 +0,0 @@
package dev.caskeleton.messaging.rabbit;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.delivery.DeliveryGuarantee;
import dev.caskeleton.messaging.api.delivery.ExternalSideEffectGuarantee;
import dev.caskeleton.messaging.api.delivery.OrderingScope;
import dev.caskeleton.messaging.api.destination.DestinationKind;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.policy.CapabilityTier;
import dev.caskeleton.messaging.policy.ConsumerPolicy;
import dev.caskeleton.messaging.policy.DeadLetterPolicy;
import dev.caskeleton.messaging.policy.DestinationProfile;
import dev.caskeleton.messaging.policy.PayloadPolicy;
import dev.caskeleton.messaging.policy.PhysicalDestination;
import dev.caskeleton.messaging.policy.ProducerPolicy;
import dev.caskeleton.messaging.policy.RetryPolicy;
import dev.caskeleton.messaging.policy.SchemaPolicy;
import dev.caskeleton.messaging.schema.SchemaCompatibility;
import java.time.Duration;
import java.util.List;
import java.util.Set;
/** Builds RabbitMQ profiles for validator tests. */
final class RabbitProfileFixtures {
private RabbitProfileFixtures() {}
static RabbitBrokerProfile stable() {
return new RabbitBrokerProfile(
"rabbit-primary",
true,
false,
List.of("localhost:5672"),
true,
true,
true,
Duration.ofSeconds(5),
false,
16,
true,
true,
true);
}
static RabbitBrokerProfile withoutConfirms() {
return copy(stable(), false, true, true, false, true, false, true);
}
static RabbitBrokerProfile withoutReturns() {
return copy(stable(), true, false, true, false, true, false, true);
}
static RabbitBrokerProfile withoutMandatory() {
return copy(stable(), true, true, false, false, true, false, true);
}
static RabbitBrokerProfile withAutoAck() {
return copy(stable(), true, true, true, true, true, false, true);
}
static RabbitBrokerProfile withoutQuorumQueues() {
return copy(stable(), true, true, true, false, false, false, true);
}
static RabbitBrokerProfile productionWithoutTls() {
return copy(stable(), true, true, true, false, true, true, false);
}
private static RabbitBrokerProfile copy(
RabbitBrokerProfile base,
boolean confirms,
boolean returns,
boolean mandatory,
boolean autoAck,
boolean quorumQueues,
boolean production,
boolean tlsEnabled) {
return new RabbitBrokerProfile(
base.broker(),
base.stable(),
production,
base.addresses(),
confirms,
returns,
mandatory,
base.confirmTimeout(),
autoAck,
base.prefetch(),
quorumQueues,
tlsEnabled,
base.authenticationEnabled());
}
static DestinationProfile workQueueDestination() {
return new DestinationProfile(
new DestinationName("email-work"),
"rabbit-primary",
DestinationKind.WORK_QUEUE,
PhysicalDestination.rabbitQueue("notification.work", "email", "notification.email.q"),
new SchemaPolicy(
ContentType.JSON,
SchemaCompatibility.BACKWARD,
Set.of(new MessageType("email.requested"))),
DeliveryGuarantee.AT_LEAST_ONCE,
OrderingScope.NONE,
ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED,
ProducerPolicy.defaults(),
ConsumerPolicy.defaults("notification"),
RetryPolicy.none(),
DeadLetterPolicy.to(new DestinationName("email-work-dlq")),
PayloadPolicy.defaults(),
CapabilityTier.M1,
false,
false,
false);
}
}
@@ -301,6 +301,14 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM
}
private <T> MessageEnvelope<EncodedMessage> encode(MessageEnvelope<T> message) {
// The outbox relay, dead lettering and the retry topic republish bytes a codec already wrote.
// Encoding them again handed the codec a payload that is not its type, so each such publish was
// REJECTED (or, with a lenient codec, sent the envelope's toString). They go out as they are.
if (message.payload() instanceof EncodedMessage alreadyEncoded) {
MessageEnvelope<EncodedMessage> encoded = message.withPayload(alreadyEncoded);
requireEncodedEnvelope(encoded);
return encoded;
}
MessageCodec codec = codecs.find(message.contentType()).orElseGet(codecs::defaultCodec);
EncodedMessage bytes =
codec.encode(message.messageType(), message.schemaVersion(), message.payload());
@@ -10,9 +10,14 @@ import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.delivery.DeliveryContext;
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import dev.caskeleton.messaging.api.destination.DestinationCapabilities;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
@@ -21,6 +26,7 @@ import dev.caskeleton.messaging.api.publish.PublishEvidence;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import dev.caskeleton.messaging.api.publish.RoutingOutcome;
import dev.caskeleton.messaging.policy.DeadLetterOrchestrator;
import dev.caskeleton.messaging.policy.InFlightLimiter;
import dev.caskeleton.messaging.policy.MessagingAdmissionController;
import dev.caskeleton.messaging.policy.PayloadLimitGuard;
@@ -120,6 +126,55 @@ class DefaultMessagePublisherTest {
assertThat(admission.inFlight()).isZero();
}
@Test
void aDeadLetterPublishedThroughThisPublisherReachesTheTransportWithTheOriginalBytes() {
// given
DestinationName deadLetters = new DestinationName("order-events-dlq");
DefaultMessagePublisher publisher =
new DefaultMessagePublisher(
DestinationProfileRegistry.of(
Map.of(
ORDERS,
RuntimeFixtures.profile(ORDERS),
deadLetters,
RuntimeFixtures.profile(deadLetters))),
new DestinationAccessPolicy(
java.util.Set.of(deadLetters), java.util.Set.of(), java.util.Set.of()),
new SingleCodecRegistry(),
admission,
new FixedRuntimeRegistry(transport),
transport);
byte[] wireBytes = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8);
MessageDelivery<EncodedMessage> failed =
new MessageDelivery<>(
envelope()
.withPayload(new EncodedMessage(wireBytes, ContentType.JSON, Optional.empty())),
new DeliveryMetadata(
ORDERS,
3,
true,
Optional.empty(),
Optional.empty(),
Optional.of("order-projection"),
Instant.parse("2026-08-14T00:00:05Z")),
new DeliveryContext(Instant.parse("2026-08-14T00:00:35Z"), false, "order-projection"));
// when
new DeadLetterOrchestrator(publisher)
.deadLetter(
RuntimeFixtures.profile(ORDERS),
failed,
FailureDescriptor.of(FailureCategory.PERMANENT_BUSINESS, "ORDER_REJECTED", "rejected"),
() -> CompletableFuture.completedFuture(null))
.toCompletableFuture()
.join();
// then
assertThat(transport.lastRequest().envelope().payload().bytes())
.as("encoding an already-encoded payload again rewrites the bytes or fails the codec")
.containsExactly(wireBytes);
}
@Test
@DisplayName("an unregistered destination is rejected before anything is encoded")
void anUnregisteredDestinationIsRejected() {
@@ -34,8 +34,6 @@ commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
info.picocli:picocli:4.7.7=checkstyle
io.cloudevents:cloudevents-api:4.0.1=runtimeClasspath,testRuntimeClasspath
io.cloudevents:cloudevents-core:4.0.1=runtimeClasspath,testRuntimeClasspath
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -4,6 +4,7 @@ import dev.caskeleton.messaging.kafka.KafkaProfileValidator;
import dev.caskeleton.messaging.kafka.KafkaPublishFailureClassifier;
import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer;
import dev.caskeleton.messaging.kafka.KafkaTransactionProfileValidator;
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
import dev.caskeleton.messaging.security.BrokerTlsPolicy;
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
import org.springframework.beans.factory.ObjectProvider;
@@ -24,13 +25,19 @@ import org.springframework.context.annotation.Configuration;
* localhost:9092} — which in a test environment usually succeeds against something.
*
* <p>Reached only when app.messaging.broker=kafka selected it. The @ConditionalOnClass this used to
* carry could not select: the starter depends on messaging-kafka and messaging-rabbit, each of
* which exposes its client library as `api`, so both conditions were true for every adopter and
* both providers assembled.
* carry could not select: the starter then depended on two broker adapters, each of which exposed
* its client library as `api`, so both conditions were true for every adopter and both providers
* assembled.
*/
@Configuration(proxyBeanMethods = false)
public class KafkaMessagingAutoConfiguration {
/**
* The two versions {@code BrokerTlsPolicy} accepts. No setting names them, so both are offered.
*/
private static final java.util.List<String> TLS_PROTOCOLS =
java.util.List.of("TLSv1.3", "TLSv1.2");
/**
* Returns the Kafka destination profile validator.
*
@@ -123,12 +130,28 @@ public class KafkaMessagingAutoConfiguration {
* and a serializer configured here would be a second encoder disagreeing with it.
*
* @param environment the resolved environment
* @param compiled the broker and security profiles compiled from {@code app.messaging}
* @param declaredSecurity the security profiles the application declared as beans
* @param securityConfigurer the Kafka security configurer, present only with a credential source
* @return the producer, closed with the context
*/
@Bean(destroyMethod = "close")
@ConditionalOnMissingBean
public org.apache.kafka.clients.producer.Producer<byte[], byte[]> messagingKafkaProducer(
org.springframework.core.env.Environment environment) {
org.springframework.core.env.Environment environment,
CompiledMessagingConfiguration compiled,
ObjectProvider<BrokerSecurityProfile> declaredSecurity,
ObjectProvider<KafkaSecurityConfigurer> securityConfigurer) {
return new org.apache.kafka.clients.producer.KafkaProducer<>(
producerConfig(environment, compiled, declaredSecurity, securityConfigurer));
}
/** The producer's client configuration; package-visible so a test can read what it holds. */
static java.util.Map<String, Object> producerConfig(
org.springframework.core.env.Environment environment,
CompiledMessagingConfiguration compiled,
ObjectProvider<BrokerSecurityProfile> declaredSecurity,
ObjectProvider<KafkaSecurityConfigurer> securityConfigurer) {
String bootstrapServers = environment.getProperty("spring.kafka.bootstrap-servers", "").trim();
if (bootstrapServers.isEmpty()) {
throw new IllegalStateException(
@@ -150,7 +173,66 @@ public class KafkaMessagingAutoConfiguration {
// failover, which is exactly the outcome an outbox exists to prevent.
config.put(org.apache.kafka.clients.producer.ProducerConfig.ACKS_CONFIG, "all");
config.put(org.apache.kafka.clients.producer.ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
return new org.apache.kafka.clients.producer.KafkaProducer<>(config);
config.putAll(producerSecurity(compiled, declaredSecurity, securityConfigurer));
return config;
}
/**
* The producer's security properties, from the one security profile of the Kafka broker.
*
* <p>{@code KafkaSecurityConfigurer} was a bean nothing called, so a broker that passed the TLS
* and credential checks was reached over plaintext with no authentication. Every case that cannot
* be applied fails startup rather than falling back to that.
*/
private static java.util.Map<String, Object> producerSecurity(
CompiledMessagingConfiguration compiled,
ObjectProvider<BrokerSecurityProfile> declaredSecurity,
ObjectProvider<KafkaSecurityConfigurer> securityConfigurer) {
java.util.Map<String, BrokerSettings> kafkaBrokers = new java.util.TreeMap<>();
compiled.brokers().entrySet().stream()
.filter(entry -> BrokerSettings.KAFKA.equalsIgnoreCase(entry.getValue().type()))
.forEach(entry -> kafkaBrokers.put(entry.getKey(), entry.getValue()));
// The same fallback as the runtime's logical name: bean-declared profiles name the family.
java.util.Set<String> names =
kafkaBrokers.isEmpty() ? java.util.Set.of(BrokerSettings.KAFKA) : kafkaBrokers.keySet();
java.util.List<BrokerSecurityProfile> profiles =
java.util.stream.Stream.concat(
compiled.security().stream(), declaredSecurity.orderedStream())
.filter(profile -> names.contains(profile.broker()))
.toList();
if (profiles.isEmpty()) {
kafkaBrokers.forEach(
(name, broker) -> {
if (broker.tlsEnabled() || broker.authenticationEnabled()) {
throw new IllegalStateException(
"Kafka broker '"
+ name
+ "' enables TLS or authentication but has no app.messaging.security."
+ name
+ " entry; the producer cannot apply either without one");
}
});
return java.util.Map.of();
}
if (profiles.size() > 1) {
throw new IllegalStateException(
"the Kafka producer has one security posture but "
+ profiles.size()
+ " security profiles match "
+ names);
}
BrokerSecurityProfile profile = profiles.getFirst();
KafkaSecurityConfigurer configurer = securityConfigurer.getIfAvailable();
if (configurer == null) {
throw new IllegalStateException(
"app.messaging.security."
+ profile.broker()
+ " is configured but no CredentialProvider bean exists; the producer cannot"
+ " resolve its credential and must not connect without it");
}
return configurer.configure(
profile, profile.producer(), TLS_PROTOCOLS, java.time.Instant.now());
}
/**
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
id 'ca.spring-config'
}
dependencies {
// Capability artifact: Rabbit types/client exist only when this artifact is deliberately added.
api project(':messaging:messaging-spring-boot-starter')
api project(':messaging:messaging-rabbit')
implementation 'org.springframework.boot:spring-boot-autoconfigure'
}
@@ -1,124 +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.fasterxml.jackson.core:jackson-annotations:2.21=runtimeClasspath,testRuntimeClasspath
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
com.rabbitmq:amqp-client:5.27.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
info.picocli:picocli:4.7.7=checkstyle
io.cloudevents:cloudevents-api:4.0.1=runtimeClasspath,testRuntimeClasspath
io.cloudevents:cloudevents-core:4.0.1=runtimeClasspath,testRuntimeClasspath
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-buffer:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-base:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-compression:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-marshalling:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-protobuf:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-common:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-handler:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-resolver:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-transport-native-unix-common:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-transport:4.2.17.Final=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.projectreactor:reactor-core:3.8.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
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.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
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.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
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.reactivestreams:reactive-streams:1.0.4=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=compileClasspath,runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springframework.amqp:spring-amqp:4.0.5=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.amqp:spring-rabbit:4.0.5=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-actuator:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-autoconfigure:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-configuration-processor:4.0.8=annotationProcessor
org.springframework.boot:spring-boot:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-context:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-core:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-jdbc:7.0.9=runtimeClasspath,testRuntimeClasspath
org.springframework:spring-messaging:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
tools.jackson.core:jackson-core:3.1.5=runtimeClasspath,testRuntimeClasspath
tools.jackson.core:jackson-databind:3.1.5=runtimeClasspath,testRuntimeClasspath
tools.jackson:jackson-bom:3.1.5=runtimeClasspath,testRuntimeClasspath
empty=
@@ -1,126 +0,0 @@
package dev.caskeleton.messaging.autoconfigure;
import dev.caskeleton.messaging.rabbit.RabbitProfileValidator;
import dev.caskeleton.messaging.rabbit.RabbitPublishFailureClassifier;
import dev.caskeleton.messaging.rabbit.RabbitSecurityConfigurer;
import dev.caskeleton.messaging.security.BrokerTlsPolicy;
import dev.caskeleton.messaging.security.CredentialRuntimeRegistry;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Wires the RabbitMQ adapter's validators and security configurer.
*
* <p>Conditional on the AMQP client, for the same reason the Kafka configuration is conditional on
* the Kafka client: a service using one broker must not need the other on its classpath.
*
* <p>No connection or channel bean is created here. A channel opened before the application has
* declared its security profile would connect with whatever defaults the client carries, which for
* RabbitMQ means {@code guest/guest} against localhost.
*
* <p>Reached only when app.messaging.broker=rabbit selected it; see MessagingProviderSelection for
* why a classpath condition could not make this choice.
*/
@Configuration(proxyBeanMethods = false)
public class RabbitMessagingAutoConfiguration {
/**
* Returns the RabbitMQ destination profile validator.
*
* @return the validator
*/
@Bean
@ConditionalOnMissingBean
public RabbitProfileValidator rabbitProfileValidator() {
return new RabbitProfileValidator();
}
/**
* Runs the RabbitMQ profile validator over every broker profile, declared or configured.
*
* @param profiles the broker profiles the application declared as beans
* @param compiled the broker profiles compiled from {@code app.messaging.brokers}
* @param validator the RabbitMQ profile validator
* @return the startup validation
*/
@Bean
public StartupProfileValidation<dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
rabbitProfileStartupValidation(
org.springframework.beans.factory.ObjectProvider<
dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
profiles,
CompiledMessagingConfiguration compiled,
RabbitProfileValidator validator) {
return new StartupProfileValidation<>(
() ->
java.util.stream.Stream.concat(
configuredRabbitProfiles(compiled).stream(), profiles.orderedStream())
.toList(),
validator::validate);
}
/**
* Returns the publish failure classifier.
*
* @return the classifier
*/
@Bean
@ConditionalOnMissingBean
public RabbitPublishFailureClassifier rabbitPublishFailureClassifier() {
return new RabbitPublishFailureClassifier();
}
/**
* Returns the AMQP security configurer.
*
* @param credentials the credential runtime registry
* @param tlsPolicy the transport security policy
* @return the configurer
*/
/**
* The security configurer, which exists only when a credential source does.
*
* <p>It took {@code CredentialRuntimeRegistry} as a required parameter, and that registry is
* created only when the application supplies a {@code CredentialProvider}. Without one the
* context failed on a missing bean naming the registry — an error that describes the platform's
* internals rather than the one thing the operator has to do. The condition moves the failure to
* a place that can say so.
*/
@Bean
@ConditionalOnMissingBean
@org.springframework.boot.autoconfigure.condition.ConditionalOnBean(
CredentialRuntimeRegistry.class)
public RabbitSecurityConfigurer rabbitSecurityConfigurer(
CredentialRuntimeRegistry credentials, BrokerTlsPolicy tlsPolicy) {
return new RabbitSecurityConfigurer(credentials, tlsPolicy);
}
private static java.util.List<dev.caskeleton.messaging.rabbit.RabbitBrokerProfile>
configuredRabbitProfiles(CompiledMessagingConfiguration compiled) {
return compiled.brokers().entrySet().stream()
.filter(
entry ->
entry.getValue().type() != null
&& entry.getValue().type().equalsIgnoreCase(BrokerSettings.RABBITMQ))
.map(
entry -> {
BrokerSettings broker = entry.getValue();
return new dev.caskeleton.messaging.rabbit.RabbitBrokerProfile(
entry.getKey(),
broker.stable(),
broker.production(),
broker.addresses(),
broker.publisherConfirms(),
broker.publisherReturns(),
broker.mandatory(),
broker.confirmTimeout(),
broker.autoAck(),
broker.prefetch(),
broker.quorumQueues(),
broker.tlsEnabled(),
broker.authenticationEnabled());
})
.toList();
}
}
@@ -2,21 +2,21 @@
## 아티팩트 분리
기본 `messaging-spring-boot-starter`는 이제 **broker-neutral core**다. Kafka/Rabbit client를
기본 `messaging-spring-boot-starter`는 이제 **broker-neutral core**다. Kafka client를
production runtime에 직접 넣지 않으며, 브로커 채택은 capability artifact를 composition에 추가하는
build-time 결정이다.
```text
messaging-spring-boot-starter
├─ messaging-spring-boot-starter-kafka # Kafka client/transport capability
└─ messaging-spring-boot-starter-rabbit # Rabbit profile/validator capability
└─ messaging-spring-boot-starter-kafka # Kafka client/transport capability
```
- 기본 app-bootstrap은 core starter만 가진다. 따라서 messaging off/default runtime에는
`kafka-clients`, `spring-kafka`, `spring-rabbit`, `amqp-client`가 없다.
- Kafka를 채택하는 composition은 `:messaging:messaging-spring-boot-starter-kafka`를 추가한다.
- Rabbit capability도 별도 artifact지만, 아래 설명처럼 아직 production transport가 없어
`app.messaging.broker=rabbit` 선택은 startup에서 거부된다.
- 기본 app-bootstrap은 messaging을 싣지 않는다. 서비스는 `runtimeOnly
project(':adapter:outbound:messaging-kafka')` 한 줄로 Kafka capability를 고르고, 그 모듈이
`:messaging:messaging-spring-boot-starter-kafka`(와 이 core starter)를 runtime으로 끌어온다.
- starter는 있으면 켜진다(`app.messaging.enabled` 기본 on). `app.messaging.enabled=false`로만 끈다.
- 등록된 broker 계열은 Kafka 하나다. RabbitMQ 설정 키(`type: rabbitmq`, `addresses`, `prefetch` 등)는
transport 없이 바인딩만 되던 키라 삭제했고, 지금은 키 이름을 담아 기동이 거부된다.
- reliability/admin의 추가 artifact 분리는 별도 구조 개선 여지로 남지만, broker SDK 동시 탑재 문제와
transport 선택 문제는 core/broker capability 분리로 해소했다.
- legacy R0 outbound bridge도 같은 원칙을 따른다. broker-neutral
@@ -35,13 +35,9 @@ consume을 채택하려면 애플리케이션 composition이 별도로 `KafkaCon
조립해야 한다. leaf 안의 consumer/rebalance/settlement 테스트가 초록이라는 사실은 capability
starter가 consumer runtime까지 자동 제공한다는 뜻이 아니다.
### RabbitMQ
### RabbitMQ (삭제됨)
RabbitMQ는 별도 capability artifact에 격리되어 있지만 **아직 선택할 수 없는 transport**다.
`app.messaging.broker=rabbit`을 설정하면 `MessagingProviderSelection`이 startup에서 거부한다.
이 leaf에는 validator, failure classifier, topology/security 부품과 테스트는 있지만 production
`RabbitChannelPublisher` 구현이 없어 `MessagingTransport`를 완성할 수 없다.
현재 selectable broker는 Kafka뿐이다. Rabbit이 selectable로 승격되는 조건은 production
channel publisher/settlement bridge를 구현하고 starter composition 및 broker integration 증거를
함께 추가하는 것이다.
production transport가 없어 선택할 수 없던 `messaging-rabbit`·`messaging-spring-boot-starter-rabbit`는
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). 현재 등록된 broker는 Kafka 하나다.
`app.messaging.brokers.<name>.type: rabbitmq` 설정 family는 아직 바인딩·검증되지만 소비하는 transport가
없다.
@@ -6,15 +6,9 @@ plugins {
// Scopes, not a flat list of `api`.
//
// Sixteen internal leaves were exposed as `api`, so every adopter of the starter compiled against
// the Kafka adapter, the Rabbit adapter, both JDBC reliability leaves and the admin plane whether
// they used them or not — and both brokers' `@ConditionalOnClass` guards were true at once because
// the starter itself dragged in both clients.
//
// `api` is now the types that genuinely appear in this module's public signatures; everything else
// is `implementation`. Splitting the starter into per-capability artifacts (core / kafka / rabbit /
// reliability / admin) is the structural fix the review asks for and is a registry change of its
// own; this is the part that stops an adopter's compile classpath from containing two broker SDKs.
// `api` is the types that genuinely appear in this module's public signatures; everything else is
// `implementation`. Broker transports live in capability starters (messaging-spring-boot-starter-kafka),
// so this starter's compile classpath carries no broker SDK.
auxiliarySourceSets {
sourceSet('integrationTest') {
compilesAgainst 'main'
@@ -33,14 +27,12 @@ dependencies {
// Wired by the auto-configurations and never named in an adopter's source.
implementation project(':messaging:messaging-schema-json')
implementation project(':messaging:messaging-cloudevents')
// The publisher and its collaborators live here. The starter did not depend on it at all,
// which is why MessagingCoreAutoConfiguration consumed a MessagePublisher that nothing in
// reach could produce (MSG-INT-003).
implementation project(':messaging:messaging-runtime-core')
implementation project(':messaging:messaging-outbox-jdbc-postgresql')
implementation project(':messaging:messaging-inbox-jdbc-postgresql')
implementation project(':messaging:messaging-claim-check')
implementation project(':messaging:messaging-admin-api')
implementation project(':messaging:messaging-admin-runtime')
@@ -56,9 +48,8 @@ dependencies {
testImplementation 'org.springframework.boot:spring-boot-test'
testImplementation 'org.springframework:spring-test'
// Provider auto-configurations live in capability artifacts. Tests that exercise provider
// selection add them only to the test graph; the production starter remains broker-neutral.
// selection add it only to the test graph; the production starter remains broker-neutral.
testImplementation project(':messaging:messaging-spring-boot-starter-kafka')
testImplementation project(':messaging:messaging-spring-boot-starter-rabbit')
// Test-only, and specifically so the configuration reference can be executed rather than read:
// MessagingConfigurationBindingTest loads the YAML blocks out of the shipped document and boots
// a context on them. Spring Boot 4 treats snakeyaml as optional, so a document-driven test has
@@ -32,7 +32,6 @@ com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,integrat
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
com.rabbitmq:amqp-client:5.27.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-codec:commons-codec:1.19.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath
commons-collections:commons-collections:3.2.2=checkstyle
@@ -40,24 +39,11 @@ commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRunt
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
info.picocli:picocli:4.7.7=checkstyle
io.cloudevents:cloudevents-api:4.0.1=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.cloudevents:cloudevents-core:4.0.1=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
io.micrometer:micrometer-commons:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-buffer:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-base:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-compression:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-marshalling:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec-protobuf:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-codec:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-common:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-handler:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-resolver:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-transport-native-unix-common:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.netty:netty-transport:4.2.17.Final=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.projectreactor:reactor-core:3.8.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.projectreactor:reactor-test:3.8.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
@@ -113,11 +99,9 @@ org.pcollections:pcollections:4.0.1=annotationProcessor,integrationTestAnnotatio
org.reactivestreams:reactive-streams:1.0.4=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.reflections:reflections:0.10.2=checkstyle
org.rnorth.duct-tape:duct-tape:1.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.slf4j:slf4j-api:2.0.18=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-api:2.0.18=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springframework.amqp:spring-amqp:4.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.amqp:spring-rabbit:4.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-actuator:4.0.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-autoconfigure:4.0.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-configuration-processor:4.0.8=annotationProcessor
@@ -129,9 +113,8 @@ org.springframework:spring-context:7.0.9=compileClasspath,integrationTestCompile
org.springframework:spring-core:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-jdbc:7.0.9=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath
org.springframework:spring-messaging:7.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-test:7.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=integrationTestRuntimeClasspath,runtimeClasspath,testRuntimeClasspath
org.testcontainers:testcontainers-junit-jupiter:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
@@ -7,18 +7,16 @@ import org.springframework.boot.context.properties.bind.DefaultValue;
/**
* One entry of {@code app.messaging.brokers}.
*
* <p>Both broker families are described by one record because a deployment names its brokers in one
* map, and a reader of that map should not have to know which half of the fields apply. Which half
* does apply is decided by {@link #type()}, and the compiler refuses a field belonging to the other
* family rather than ignoring it — a Kafka broker carrying {@code prefetch} is a configuration the
* author believed was doing something.
* <p>Kafka is the one broker family this platform has a transport for, so the record carries only
* Kafka fields. RabbitMQ fields used to live here too and bound with no transport behind them: a
* deployment could configure a RabbitMQ broker that nothing would ever connect to.
*
* <p>{@code tlsEnabled} and {@code production} live here rather than beside the credentials, so a
* broker is described once. They were previously implied by whichever object happened to be
* constructed, which is how a profile can be production in one validator's view and not in
* another's.
*
* @param type the broker family, {@code kafka} or {@code rabbitmq}
* @param type the broker family; {@code kafka} is the only one
* @param stable whether this profile claims the Stable guarantees
* @param production whether this profile is used in production
* @param tlsEnabled whether transport encryption is on
@@ -30,14 +28,6 @@ import org.springframework.boot.context.properties.bind.DefaultValue;
* @param deliveryTimeout the Kafka producer delivery deadline
* @param enableAutoCommit whether the Kafka consumer commits offsets on a timer
* @param consumerGroup the Kafka consumer group
* @param addresses RabbitMQ broker addresses
* @param publisherConfirms whether correlated publisher confirms are on
* @param publisherReturns whether unroutable returns are delivered
* @param mandatory whether publishes carry the mandatory flag
* @param confirmTimeout how long to wait for a RabbitMQ confirm
* @param autoAck whether the RabbitMQ consumer acknowledges on delivery
* @param prefetch the RabbitMQ consumer prefetch window
* @param quorumQueues whether durable work queues are declared as quorum queues
*/
public record BrokerSettings(
String type,
@@ -51,19 +41,8 @@ public record BrokerSettings(
@DefaultValue("5") int maxInFlightRequestsPerConnection,
@DefaultValue("30s") Duration deliveryTimeout,
@DefaultValue("false") boolean enableAutoCommit,
@DefaultValue("") String consumerGroup,
@DefaultValue List<String> addresses,
@DefaultValue("true") boolean publisherConfirms,
@DefaultValue("true") boolean publisherReturns,
@DefaultValue("true") boolean mandatory,
@DefaultValue("5s") Duration confirmTimeout,
@DefaultValue("false") boolean autoAck,
@DefaultValue("16") int prefetch,
@DefaultValue("true") boolean quorumQueues) {
@DefaultValue("") String consumerGroup) {
/** The broker family a Kafka entry declares. */
public static final String KAFKA = "kafka";
/** The broker family a RabbitMQ entry declares. */
public static final String RABBITMQ = "rabbitmq";
}
@@ -101,19 +101,11 @@ public final class MessagingConfigurationCompiler {
+ "localhost:9092 and fails at the first publish rather than at startup");
}
}
case BrokerSettings.RABBITMQ -> {
if (broker.addresses().isEmpty()) {
throw configurationError(
key("brokers", name, "addresses"),
"a RabbitMQ broker needs at least one address; a client with none defaults to "
+ "localhost and connects as guest");
}
}
default ->
throw configurationError(
key("brokers", name, "type"),
"'%s' is not a broker family this platform binds; use '%s' or '%s'"
.formatted(broker.type(), BrokerSettings.KAFKA, BrokerSettings.RABBITMQ));
"'%s' is not a broker family this platform has a transport for; use '%s'"
.formatted(broker.type(), BrokerSettings.KAFKA));
}
}
@@ -5,7 +5,6 @@ import java.lang.reflect.RecordComponent;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
@@ -38,29 +37,6 @@ import org.springframework.core.env.PropertySource;
*/
public final class MessagingConfigurationKeyValidator implements InitializingBean {
/** Broker keys that only a Kafka entry may carry. */
private static final Set<String> KAFKA_ONLY_KEYS =
Set.of(
"bootstrap-servers",
"enable-idempotence",
"acks",
"max-in-flight-requests-per-connection",
"delivery-timeout",
"enable-auto-commit",
"consumer-group");
/** Broker keys that only a RabbitMQ entry may carry. */
private static final Set<String> RABBIT_ONLY_KEYS =
Set.of(
"addresses",
"publisher-confirms",
"publisher-returns",
"mandatory",
"confirm-timeout",
"auto-ack",
"prefetch",
"quorum-queues");
private final ConfigurableEnvironment environment;
/**
@@ -102,8 +78,6 @@ public final class MessagingConfigurationKeyValidator implements InitializingBea
rejected.add(
"%s binds nothing; %s entries accept %s"
.formatted(key, section, legal.stream().sorted().toList()));
} else if ("brokers".equals(section)) {
wrongFamily(entry).ifPresent(rejected::add);
}
}
});
@@ -125,32 +99,6 @@ public final class MessagingConfigurationKeyValidator implements InitializingBea
+ (rejected.size() > 10 ? " (and " + (rejected.size() - 10) + " more)" : ""));
}
/**
* Reports a broker key that belongs to the other broker family.
*
* <p>Both families are described by one record, so a Kafka entry carrying {@code prefetch} binds
* without complaint and does nothing. The author of that line believed it was doing something,
* which is the same silence this class exists to end.
*/
private java.util.Optional<String> wrongFamily(Entry entry) {
String declared =
environment.getProperty(
MessagingSettings.PREFIX + ".brokers." + entry.name() + ".type", "");
String family = declared.toLowerCase(Locale.ROOT);
String leaf = entry.leaf();
if (BrokerSettings.KAFKA.equals(family) && RABBIT_ONLY_KEYS.contains(leaf)) {
return java.util.Optional.of(
"%s.brokers.%s.%s is a RabbitMQ setting on a Kafka broker"
.formatted(MessagingSettings.PREFIX, entry.name(), leaf));
}
if (BrokerSettings.RABBITMQ.equals(family) && KAFKA_ONLY_KEYS.contains(leaf)) {
return java.util.Optional.of(
"%s.brokers.%s.%s is a Kafka setting on a RabbitMQ broker"
.formatted(MessagingSettings.PREFIX, entry.name(), leaf));
}
return java.util.Optional.empty();
}
/** One configuration key split into the map entry it configures and the leaf inside it. */
private record Entry(String name, String leaf) {}
@@ -516,7 +516,6 @@ public class MessagingCoreAutoConfiguration {
String configuredFamily =
switch (selected.brokerName()) {
case "kafka" -> BrokerSettings.KAFKA;
case "rabbit" -> BrokerSettings.RABBITMQ;
default -> selected.brokerName();
};
java.util.List<String> configuredNames =
@@ -20,13 +20,18 @@ import org.springframework.context.annotation.Import;
* whichever bean won. Selection now reads {@code app.messaging.broker} against a closed registry,
* and a value outside it is a startup error rather than a context with no provider at all.
*
* <p>{@code app.messaging.enabled=false} means no beans, no clients, no threads, and no bound
* detail namespace. {@code MessagingStarterOffContractTest} holds that against a full context
* including this starter's owned imports. Vendor auto-configuration is verified in its own runtime
* lanes.
* <p>On when present: a missing {@code app.messaging.enabled} means on, because an application that
* put this starter on its classpath chose messaging. {@code app.messaging.enabled=false} means no
* beans, no clients, no threads, and no bound detail namespace. {@code
* MessagingStarterOffContractTest} holds that against a full context including this starter's owned
* imports. Vendor auto-configuration is verified in its own runtime lanes.
*/
@AutoConfiguration
@ConditionalOnProperty(prefix = MessagingSettings.PREFIX, name = "enabled", havingValue = "true")
@ConditionalOnProperty(
prefix = MessagingSettings.PREFIX,
name = "enabled",
havingValue = "true",
matchIfMissing = true)
@EnableConfigurationProperties(MessagingSettings.class)
@Import({
MessagingCoreAutoConfiguration.class,
@@ -13,9 +13,9 @@ import org.springframework.util.ClassUtils;
/**
* Selects exactly one transport, from a closed registry, by name (MSG-INT-004).
*
* <p>Selection used to be {@code @ConditionalOnClass}: Kafka assembled because a Kafka class was on
* the classpath and Rabbit because a Rabbit class was, so an application with both libraries — one
* transitive dependency is enough — assembled both and published through whichever bean won a
* <p>Selection used to be {@code @ConditionalOnClass}: a transport assembled because its client
* class was on the classpath, so an application with two client libraries — one transitive
* dependency is enough — assembled both and published through whichever bean won a
* {@code @ConditionalOnMissingBean} race. Nothing failed; the message simply went somewhere nobody
* chose.
*
@@ -25,7 +25,8 @@ import org.springframework.util.ClassUtils;
* <li>a broker id outside the registry — the operator set something the platform cannot honour;
* <li>a registered broker whose client library is absent — a deployment that asked for Kafka and
* shipped without it is told so, instead of starting with no publisher at all;
* <li>a blank broker while messaging is on — the master switch says yes and nothing says what to.
* <li>a blank broker while messaging is on — the capability switch says yes and nothing says what
* to.
* </ul>
*
* <p>The provider configurations carry no condition of their own any more. Each is reached only
@@ -38,58 +39,21 @@ public class MessagingProviderSelection {
/** Broker id to the client class that must be present for it to be honoured. */
static final Map<String, String> REGISTERED_BROKERS =
Map.of(
"kafka", "org.apache.kafka.clients.producer.Producer",
"rabbit", "com.rabbitmq.client.Channel");
Map.of("kafka", "org.apache.kafka.clients.producer.Producer");
/** Broker id to the configuration that assembles it. */
static final Map<String, String> PROVIDER_CONFIGURATIONS =
Map.of(
"kafka", "dev.caskeleton.messaging.autoconfigure.KafkaMessagingAutoConfiguration",
"rabbit", "dev.caskeleton.messaging.autoconfigure.RabbitMessagingAutoConfiguration");
Map.of("kafka", "dev.caskeleton.messaging.autoconfigure.KafkaMessagingAutoConfiguration");
/** Broker id to the starter a deployment adds to its build to obtain that transport. */
static final Map<String, String> PROVIDER_STARTERS =
Map.of(
"kafka", "messaging-spring-boot-starter-kafka",
"rabbit", "messaging-spring-boot-starter-rabbit");
/**
* Broker ids that ship without a {@code MessagingTransport}, and why.
*
* <p>Registered is not the same as assemblable. The Rabbit leaf ships its profile validator,
* failure classifier and security configurer, and no transport — the native channel bridge those
* would sit on has only test implementations. Selecting it therefore produced an unsatisfied
* dependency on {@code MessagingTransport} deep inside the core configuration, which tells an
* operator that a bean is missing rather than that the transport they chose is not finished.
*
* <p>Refused here instead, next to the other selection errors, so the message names the state the
* deployment is actually in. An entry leaves this map on the day its transport does exist.
*/
static final Map<String, String> BROKERS_WITHOUT_A_TRANSPORT =
Map.of(
"rabbit",
"the Rabbit adapter ships its validators and security configuration but no "
+ "MessagingTransport: its native channel publisher is not implemented, so a publish "
+ "has nothing to travel on");
Map.of("kafka", "messaging-spring-boot-starter-kafka");
/** The registered broker ids, so a message can tell an operator what is available. */
public static List<String> registeredBrokerIds() {
return REGISTERED_BROKERS.keySet().stream().sorted().toList();
}
/**
* The registered broker ids that actually assemble a transport.
*
* @return the ids a deployment can select today
*/
public static List<String> assemblableBrokerIds() {
return REGISTERED_BROKERS.keySet().stream()
.filter(id -> !BROKERS_WITHOUT_A_TRANSPORT.containsKey(id))
.sorted()
.toList();
}
/**
* Resolves the selection, or throws naming the property and the values it accepts.
*
@@ -141,17 +105,6 @@ public class MessagingProviderSelection {
+ " module on the classpath; this core starter is broker-neutral and the deployment"
+ " did not compose the transport it selected");
}
String unfinished = BROKERS_WITHOUT_A_TRANSPORT.get(broker);
if (unfinished != null) {
throw new IllegalStateException(
MessagingSettings.PREFIX
+ ".broker="
+ broker
+ " cannot be selected: "
+ unfinished
+ ". Transports that can be assembled today: "
+ assemblableBrokerIds());
}
return broker;
}
@@ -20,11 +20,6 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
* the failure it prevents (a deployment split across two prefixes, each half-configuring the
* platform) is worse than an actionable startup error.
*
* <p>Every Experimental and bridge flag defaults to {@code false}. An adapter whose contract suite
* is still being proven must not become load-bearing because a default turned it on, and the same
* applies to the Spring Cloud Stream bridge, which bypasses the platform's retry and dead letter
* policy by design.
*
* <p>The destination, broker and security maps are what the configuration reference has always
* described and nothing bound. Until they existed, a deployment that configured them exactly as
* documented changed no behaviour and produced no error: the profiles the platform actually used
@@ -48,8 +43,6 @@ public class MessagingSettings {
/** The prefix the configuration reference documented, which nothing ever bound. */
public static final String DOCUMENTED_PREFIX = "messaging";
private final Experimental experimental = new Experimental();
private final Bridge bridge = new Bridge();
private final Backpressure backpressure = new Backpressure();
private final Shutdown shutdown = new Shutdown();
private Map<String, DestinationSettings> destinations = new LinkedHashMap<>();
@@ -110,24 +103,6 @@ public class MessagingSettings {
this.security = new LinkedHashMap<>(security);
}
/**
* Returns the experimental adapter switches.
*
* @return the experimental settings
*/
public Experimental getExperimental() {
return experimental;
}
/**
* Returns the optional bridge switches.
*
* @return the bridge settings
*/
public Bridge getBridge() {
return bridge;
}
/**
* Returns the backpressure limits.
*
@@ -146,92 +121,6 @@ public class MessagingSettings {
return shutdown;
}
/** Experimental adapter switches, all off by default. */
public static class Experimental {
private boolean kafkaShare;
private boolean pulsar;
private boolean nats;
/**
* Reports whether the Kafka Share Group adapter is enabled.
*
* @return true when enabled
*/
public boolean isKafkaShare() {
return kafkaShare;
}
/**
* Enables or disables the Kafka Share Group adapter.
*
* @param kafkaShare whether to enable it
*/
public void setKafkaShare(boolean kafkaShare) {
this.kafkaShare = kafkaShare;
}
/**
* Reports whether the Pulsar adapter is enabled.
*
* @return true when enabled
*/
public boolean isPulsar() {
return pulsar;
}
/**
* Enables or disables the Pulsar adapter.
*
* @param pulsar whether to enable it
*/
public void setPulsar(boolean pulsar) {
this.pulsar = pulsar;
}
/**
* Reports whether the NATS JetStream adapter is enabled.
*
* @return true when enabled
*/
public boolean isNats() {
return nats;
}
/**
* Enables or disables the NATS JetStream adapter.
*
* @param nats whether to enable it
*/
public void setNats(boolean nats) {
this.nats = nats;
}
}
/** Optional integration bridges, off by default. */
public static class Bridge {
private boolean springCloudStream;
/**
* Reports whether the Spring Cloud Stream bridge is enabled.
*
* @return true when enabled
*/
public boolean isSpringCloudStream() {
return springCloudStream;
}
/**
* Enables or disables the Spring Cloud Stream bridge.
*
* @param springCloudStream whether to enable it
*/
public void setSpringCloudStream(boolean springCloudStream) {
this.springCloudStream = springCloudStream;
}
}
/** In-flight limits. */
public static class Backpressure {
@@ -0,0 +1,151 @@
package dev.caskeleton.messaging.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer;
import dev.caskeleton.messaging.security.BrokerSecurityProfile;
import dev.caskeleton.messaging.security.CredentialProvider;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.assertj.AssertableApplicationContext;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* What the Kafka producer is actually configured with once {@code app.messaging.security} says how.
*
* <p>The security settings were bound, compiled and validated, and {@code KafkaSecurityConfigurer}
* was a bean nothing called: the producer was built from the bootstrap address, serializers, acks
* and idempotence alone, so a broker that passed the TLS and credential checks was reached over
* plaintext with no authentication.
*/
class KafkaProducerSecurityTest {
// Assembled through the root, as an application is: the import order it fixes is what lets the
// configurer see the credential registry.
private final ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class))
.withPropertyValues(
"app.messaging.enabled=true",
"app.messaging.broker=kafka",
"spring.kafka.bootstrap-servers=localhost:9092",
"app.messaging.brokers.kafka-primary.type=kafka",
"app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9092");
private static final String[] SCRAM_CREDENTIALS = {
"app.messaging.security.kafka-primary.producer.type=SASL_SCRAM",
"app.messaging.security.kafka-primary.producer.credential-id=kafka-producer",
"app.messaging.security.kafka-primary.consumer.type=SASL_SCRAM",
"app.messaging.security.kafka-primary.consumer.credential-id=kafka-consumer",
};
@Test
void aTlsBrokerWithScramCredentialsConfiguresTheProducerForSaslSsl() {
runner
.withUserConfiguration(Credentials.class)
.withPropertyValues(SCRAM_CREDENTIALS)
.withPropertyValues(
"app.messaging.brokers.kafka-primary.tls-enabled=true",
"app.messaging.brokers.kafka-primary.authentication-enabled=true")
.run(
context ->
assertThat(producerConfig(context))
.extractingByKeys(
"security.protocol",
"sasl.mechanism",
"ssl.enabled.protocols",
"ssl.endpoint.identification.algorithm")
.containsExactly("SASL_SSL", "SCRAM-SHA-512", "TLSv1.3,TLSv1.2", "https"));
}
@Test
void aPlaintextBrokerWithPasswordCredentialsConfiguresTheProducerForSaslPlaintext() {
runner
.withUserConfiguration(Credentials.class)
.withPropertyValues(
"app.messaging.brokers.kafka-primary.authentication-enabled=true",
"app.messaging.security.kafka-primary.producer.type=USERNAME_PASSWORD",
"app.messaging.security.kafka-primary.producer.credential-id=kafka-producer",
"app.messaging.security.kafka-primary.consumer.type=USERNAME_PASSWORD",
"app.messaging.security.kafka-primary.consumer.credential-id=kafka-consumer")
.run(
context ->
assertThat(producerConfig(context))
.extractingByKeys("security.protocol", "sasl.mechanism")
.containsExactly("SASL_PLAINTEXT", "PLAIN"));
}
@Test
void theProducerLogsInWithTheProducerCredentialResolvedFromTheProvider() {
runner
.withUserConfiguration(Credentials.class)
.withPropertyValues(SCRAM_CREDENTIALS)
.withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true")
.run(
context ->
assertThat(String.valueOf(producerConfig(context).get("sasl.jaas.config")))
.startsWith("org.apache.kafka.common.security.scram.ScramLoginModule required")
.contains("username=\"kafka-producer\"", "password=\"" + Credentials.SECRET));
}
@Test
void aBrokerDeclaringTlsWithoutASecurityEntryFailsStartup() {
runner
.withPropertyValues("app.messaging.brokers.kafka-primary.tls-enabled=true")
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.as("a producer that cannot apply TLS connected over plaintext instead")
.hasMessageContaining("app.messaging.security.kafka-primary"));
}
@Test
void aSecurityEntryWithoutACredentialProviderFailsStartup() {
runner
.withPropertyValues(SCRAM_CREDENTIALS)
.run(
context ->
assertThat(context)
.hasFailed()
.getFailure()
.as("a producer that cannot resolve its credential connected without one")
.hasMessageContaining("CredentialProvider"));
}
private static Map<String, Object> producerConfig(AssertableApplicationContext context) {
return KafkaMessagingAutoConfiguration.producerConfig(
context.getEnvironment(),
context.getBean(CompiledMessagingConfiguration.class),
context.getBeanProvider(BrokerSecurityProfile.class),
context.getBeanProvider(KafkaSecurityConfigurer.class));
}
/** A credential source that answers every id with the same test secret. */
@Configuration(proxyBeanMethods = false)
static class Credentials {
static final String SECRET = "test-only-secret";
@Bean
CredentialProvider credentialProvider() {
return new CredentialProvider() {
@Override
public char[] resolve(String credentialId) {
return SECRET.toCharArray();
}
@Override
public Optional<Instant> expiresAt(String credentialId) {
return Optional.empty();
}
};
}
}
}

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