From 5e44be9ab4a4b4d1e2db2954be122397b3c42a18 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 12:49:07 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20=EB=B6=80=EA=B0=80=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=EC=9D=84=20capability=20=EB=AA=A8=EB=93=88=EB=A1=9C?= =?UTF-8?q?=20=ED=8F=AC=EC=9E=A5=ED=95=98=EA=B3=A0=20=EA=B8=B0=EB=B3=B8=20?= =?UTF-8?q?=EC=A1=B0=EB=A6=BD=EC=9D=84=20web-only=EB=A1=9C=20=EC=A0=84?= =?UTF-8?q?=ED=99=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 설계: 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) --- docs/messaging/configuration-reference.md | 57 +-- docs/messaging/cutover.md | 5 +- docs/messaging/experimental-policy.md | 57 +-- docs/messaging/operations.md | 3 +- docs/messaging/outbox-inbox.md | 10 +- docs/messaging/support-matrix.md | 72 ++-- messaging/CLAUDE.md | 26 +- .../build.gradle | 11 - .../gradle.lockfile | 93 ----- .../kafka/share/KafkaShareGroupRegistrar.java | 48 --- .../kafka/share/KafkaShareProfile.java | 33 -- .../share/KafkaShareProfileValidator.java | 42 --- .../share/KafkaShareWorkQueueCapability.java | 27 -- .../share/KafkaShareProfileValidatorTest.java | 113 ------ messaging/messaging-kafka/build.gradle | 36 +- messaging/messaging-kafka/gradle.lockfile | 29 +- .../messaging-nats-experimental/build.gradle | 14 - .../gradle.lockfile | 89 ----- .../messaging/nats/NatsAckMode.java | 57 --- .../messaging/nats/NatsJetStreamProfile.java | 103 ------ .../nats/NatsJetStreamProfileValidator.java | 75 ---- .../nats/NatsJetStreamTransport.java | 295 --------------- .../nats/NatsMaxDeliverParkingWorkflow.java | 85 ----- .../messaging/nats/NatsPreSendRejection.java | 65 ---- .../messaging/nats/NatsStreamPosition.java | 75 ---- .../nats/NatsAdapterContractTest.java | 337 ----------------- .../nats/NatsMaxDeliverParkingTest.java | 123 ------- .../build.gradle | 3 + .../messaging/outbox/OutboxPostgresIT.java | 14 +- .../outbox/DebeziumMappedRecord.java | 54 --- .../outbox/DebeziumOutboxEventRouter.java | 151 -------- .../outbox/DebeziumOutboxProfile.java | 67 ---- .../outbox/DebeziumOutboxRecordMapper.java | 79 ---- .../debezium/outbox-event-router.properties | 43 --- .../DebeziumOutboxRecordMapperTest.java | 199 ---------- .../messaging/outbox/OutboxRelayTest.java | 168 +++++++++ .../build.gradle | 14 - .../gradle.lockfile | 89 ----- .../pulsar/PulsarMessagePosition.java | 49 --- .../pulsar/PulsarMessagingTransport.java | 275 -------------- .../pulsar/PulsarPreSendRejection.java | 65 ---- .../messaging/pulsar/PulsarProfile.java | 80 ---- .../pulsar/PulsarProfileValidator.java | 66 ---- .../pulsar/PulsarSubscriptionMode.java | 62 ---- .../pulsar/PulsarSubscriptionType.java | 17 - .../pulsar/PulsarTransactionCapability.java | 49 --- .../pulsar/PulsarAdapterContractTest.java | 289 --------------- .../pulsar/PulsarSubscriptionGuardTest.java | 125 ------- messaging/messaging-rabbit/build.gradle | 43 --- messaging/messaging-rabbit/gradle.lockfile | 128 ------- .../messaging/rabbit/RabbitBrokerIT.java | 232 ------------ .../rabbit/RabbitFixtureProfiles.java | 32 -- .../rabbit/RabbitPublishBenchmark.java | 156 -------- .../rabbit/RabbitBatchConsumerRegistrar.java | 165 --------- .../messaging/rabbit/RabbitBrokerProfile.java | 50 --- .../rabbit/RabbitChannelPublisher.java | 42 --- .../rabbit/RabbitConfirmCoordinator.java | 279 -------------- .../rabbit/RabbitConsumerRegistrar.java | 238 ------------ .../rabbit/RabbitDeadLetterPublisher.java | 130 ------- .../rabbit/RabbitDeliveryMapper.java | 195 ---------- .../messaging/rabbit/RabbitHeaderMapper.java | 180 --------- .../rabbit/RabbitMessagingTransport.java | 286 --------------- .../RabbitNativeDeadLetterCapability.java | 70 ---- .../rabbit/RabbitProfileValidator.java | 83 ----- .../RabbitPublishFailureClassifier.java | 133 ------- .../messaging/rabbit/RabbitPublishMapper.java | 72 ---- .../rabbit/RabbitPublishReference.java | 37 -- .../messaging/rabbit/RabbitRequestReply.java | 32 -- .../rabbit/RabbitRetryQueueTopology.java | 57 --- .../rabbit/RabbitSecurityConfigurer.java | 179 --------- .../rabbit/RabbitSettlementController.java | 84 ----- .../rabbit/RabbitSettlementOperations.java | 50 --- .../rabbit/RabbitTopologyProfile.java | 137 ------- .../rabbit/RabbitAdapterContractTest.java | 24 -- .../rabbit/RabbitConfirmCoordinatorTest.java | 167 --------- .../rabbit/RabbitContractHarness.java | 304 ---------------- .../rabbit/RabbitEnvelopeRoundTripTest.java | 152 -------- .../rabbit/RabbitProfileValidatorTest.java | 68 ---- .../messaging/rabbit/RabbitRuntimeTest.java | 341 ------------------ .../RabbitSettlementControllerTest.java | 105 ------ .../rabbit/RabbitTopologyAndBatchTest.java | 253 ------------- .../rabbit/RabbitProfileFixtures.java | 118 ------ .../runtime/DefaultMessagePublisher.java | 8 + .../runtime/DefaultMessagePublisherTest.java | 55 +++ .../gradle.lockfile | 2 - .../KafkaMessagingAutoConfiguration.java | 92 ++++- .../build.gradle | 12 - .../gradle.lockfile | 124 ------- .../RabbitMessagingAutoConfiguration.java | 126 ------- .../messaging-spring-boot-starter/README.md | 30 +- .../build.gradle | 17 +- .../gradle.lockfile | 21 +- .../autoconfigure/BrokerSettings.java | 31 +- .../MessagingConfigurationCompiler.java | 12 +- .../MessagingConfigurationKeyValidator.java | 52 --- .../MessagingCoreAutoConfiguration.java | 1 - ...essagingPlatformRootAutoConfiguration.java | 15 +- .../MessagingProviderSelection.java | 63 +--- .../autoconfigure/MessagingSettings.java | 111 ------ .../KafkaProducerSecurityTest.java | 151 ++++++++ .../MessagingAutoConfigurationTest.java | 14 - .../MessagingConfigurationBindingTest.java | 25 +- .../MessagingStarterOffContractTest.java | 113 ++---- .../src/test/resources/application-valid.yml | 10 - .../build.gradle | 10 - .../gradle.lockfile | 84 ----- .../streambridge/BindingCapabilityReport.java | 88 ----- .../streambridge/BindingProfileValidator.java | 97 ----- .../streambridge/MessagingBindingBridge.java | 34 -- .../SpringCloudStreamConsumerBridge.java | 87 ----- .../SpringCloudStreamPublisherBridge.java | 156 -------- .../streambridge/StreamBridgePolicyGuard.java | 52 --- .../BindingProfileValidatorTest.java | 164 --------- .../BridgePublishEvidenceTest.java | 131 ------- messaging/messaging-testkit/build.gradle | 8 +- messaging/messaging-testkit/gradle.lockfile | 11 +- .../testkit/CompatibilityMatrix.java | 41 +-- .../testkit/MessagingAdapterHarness.java | 4 +- .../testkit/CertifiedEvidenceTest.java | 4 +- .../testkit/CompatibilityMatrixTest.java | 2 - .../testkit/CrossBrokerContractSuite.java | 17 +- .../MessagingDocumentationContractTest.java | 4 - 122 files changed, 725 insertions(+), 9914 deletions(-) delete mode 100644 messaging/messaging-kafka-share-experimental/build.gradle delete mode 100644 messaging/messaging-kafka-share-experimental/gradle.lockfile delete mode 100644 messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareGroupRegistrar.java delete mode 100644 messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfile.java delete mode 100644 messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidator.java delete mode 100644 messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareWorkQueueCapability.java delete mode 100644 messaging/messaging-kafka-share-experimental/src/test/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidatorTest.java delete mode 100644 messaging/messaging-nats-experimental/build.gradle delete mode 100644 messaging/messaging-nats-experimental/gradle.lockfile delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsAckMode.java delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfile.java delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfileValidator.java delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamTransport.java delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingWorkflow.java delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsPreSendRejection.java delete mode 100644 messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsStreamPosition.java delete mode 100644 messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsAdapterContractTest.java delete mode 100644 messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingTest.java delete mode 100644 messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumMappedRecord.java delete mode 100644 messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxEventRouter.java delete mode 100644 messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxProfile.java delete mode 100644 messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java delete mode 100644 messaging/messaging-outbox-jdbc-postgresql/src/main/resources/debezium/outbox-event-router.properties delete mode 100644 messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java delete mode 100644 messaging/messaging-pulsar-experimental/build.gradle delete mode 100644 messaging/messaging-pulsar-experimental/gradle.lockfile delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagePosition.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagingTransport.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarPreSendRejection.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfile.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfileValidator.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionMode.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionType.java delete mode 100644 messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarTransactionCapability.java delete mode 100644 messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java delete mode 100644 messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionGuardTest.java delete mode 100644 messaging/messaging-rabbit/build.gradle delete mode 100644 messaging/messaging-rabbit/gradle.lockfile delete mode 100644 messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitBrokerIT.java delete mode 100644 messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitFixtureProfiles.java delete mode 100644 messaging/messaging-rabbit/src/jmh/java/dev/caskeleton/messaging/rabbit/RabbitPublishBenchmark.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBatchConsumerRegistrar.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBrokerProfile.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitChannelPublisher.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinator.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConsumerRegistrar.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeadLetterPublisher.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitHeaderMapper.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitMessagingTransport.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitNativeDeadLetterCapability.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidator.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishFailureClassifier.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishMapper.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishReference.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRequestReply.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRetryQueueTopology.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSecurityConfigurer.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementController.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementOperations.java delete mode 100644 messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitTopologyProfile.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitAdapterContractTest.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinatorTest.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitContractHarness.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitEnvelopeRoundTripTest.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidatorTest.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitRuntimeTest.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitSettlementControllerTest.java delete mode 100644 messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitTopologyAndBatchTest.java delete mode 100644 messaging/messaging-rabbit/src/testFixtures/java/dev/caskeleton/messaging/rabbit/RabbitProfileFixtures.java delete mode 100644 messaging/messaging-spring-boot-starter-rabbit/build.gradle delete mode 100644 messaging/messaging-spring-boot-starter-rabbit/gradle.lockfile delete mode 100644 messaging/messaging-spring-boot-starter-rabbit/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java create mode 100644 messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/build.gradle delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/gradle.lockfile delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingCapabilityReport.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingProfileValidator.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/MessagingBindingBridge.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamConsumerBridge.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamPublisherBridge.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/StreamBridgePolicyGuard.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BindingProfileValidatorTest.java delete mode 100644 messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BridgePublishEvidenceTest.java diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md index ea220b4..d4dc00d 100644 --- a/docs/messaging/configuration-reference.md +++ b/docs/messaging/configuration-reference.md @@ -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.`가 없을 때, security 항목은 +있는데 `CredentialProvider` bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때. +한계: truststore/keystore 설정 키가 없어 TLS는 JVM 기본 truststore를 쓰고, `MUTUAL_TLS`는 클라이언트 +인증서를 제출할 수 없다(미지원). ## Backpressure diff --git a/docs/messaging/cutover.md b/docs/messaging/cutover.md index a65e341..f697177 100644 --- a/docs/messaging/cutover.md +++ b/docs/messaging/cutover.md @@ -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. diff --git a/docs/messaging/experimental-policy.md b/docs/messaging/experimental-policy.md index e2052c4..de8f5b1 100644 --- a/docs/messaging/experimental-policy.md +++ b/docs/messaging/experimental-policy.md @@ -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에서 실패한다. 조용히 약화되지 않는다. ## 승격 조건 diff --git a/docs/messaging/operations.md b/docs/messaging/operations.md index 5cea33b..5bccc75 100644 --- a/docs/messaging/operations.md +++ b/docs/messaging/operations.md @@ -3,8 +3,7 @@ ## 배포 전 체크 ```bash -./gradlew verifyCleanArchitectureDependencies --console=plain -./gradlew verifyRuntimeModuleMembership --console=plain +./gradlew architectureCheck --console=plain ./gradlew checkstyleMain --console=plain ``` diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index 4dac3ee..d4b68ab 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -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 diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md index 563bd88..84c9647 100644 --- a/docs/messaging/support-matrix.md +++ b/docs/messaging/support-matrix.md @@ -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다. diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index d051e29..6b2ad64 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -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가 없는 상태로 성공 기동하는 경로는 없다. diff --git a/messaging/messaging-kafka-share-experimental/build.gradle b/messaging/messaging-kafka-share-experimental/build.gradle deleted file mode 100644 index 33edc25..0000000 --- a/messaging/messaging-kafka-share-experimental/build.gradle +++ /dev/null @@ -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') - -} diff --git a/messaging/messaging-kafka-share-experimental/gradle.lockfile b/messaging/messaging-kafka-share-experimental/gradle.lockfile deleted file mode 100644 index eaf97d5..0000000 --- a/messaging/messaging-kafka-share-experimental/gradle.lockfile +++ /dev/null @@ -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= diff --git a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareGroupRegistrar.java b/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareGroupRegistrar.java deleted file mode 100644 index 07c9ec1..0000000 --- a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareGroupRegistrar.java +++ /dev/null @@ -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. - * - *

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"); - } -} diff --git a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfile.java b/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfile.java deleted file mode 100644 index 276207c..0000000 --- a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfile.java +++ /dev/null @@ -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"); - } - } -} diff --git a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidator.java b/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidator.java deleted file mode 100644 index 1bd0390..0000000 --- a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidator.java +++ /dev/null @@ -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. - * - *

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. - * - *

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()); - } - } -} diff --git a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareWorkQueueCapability.java b/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareWorkQueueCapability.java deleted file mode 100644 index afa4907..0000000 --- a/messaging/messaging-kafka-share-experimental/src/main/java/dev/caskeleton/messaging/kafka/share/KafkaShareWorkQueueCapability.java +++ /dev/null @@ -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. - * - *

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. - * - *

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); - } -} diff --git a/messaging/messaging-kafka-share-experimental/src/test/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidatorTest.java b/messaging/messaging-kafka-share-experimental/src/test/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidatorTest.java deleted file mode 100644 index e2ecf9a..0000000 --- a/messaging/messaging-kafka-share-experimental/src/test/java/dev/caskeleton/messaging/kafka/share/KafkaShareProfileValidatorTest.java +++ /dev/null @@ -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); - } -} diff --git a/messaging/messaging-kafka/build.gradle b/messaging/messaging-kafka/build.gradle index 789445b..75b48b2 100644 --- a/messaging/messaging-kafka/build.gradle +++ b/messaging/messaging-kafka/build.gradle @@ -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.") + } + } +} + diff --git a/messaging/messaging-kafka/gradle.lockfile b/messaging/messaging-kafka/gradle.lockfile index b0dd01f..ecffd2e 100644 --- a/messaging/messaging-kafka/gradle.lockfile +++ b/messaging/messaging-kafka/gradle.lockfile @@ -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 diff --git a/messaging/messaging-nats-experimental/build.gradle b/messaging/messaging-nats-experimental/build.gradle deleted file mode 100644 index 929bf94..0000000 --- a/messaging/messaging-nats-experimental/build.gradle +++ /dev/null @@ -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') - -} diff --git a/messaging/messaging-nats-experimental/gradle.lockfile b/messaging/messaging-nats-experimental/gradle.lockfile deleted file mode 100644 index f5ad1bb..0000000 --- a/messaging/messaging-nats-experimental/gradle.lockfile +++ /dev/null @@ -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= diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsAckMode.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsAckMode.java deleted file mode 100644 index 2a8b865..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsAckMode.java +++ /dev/null @@ -1,57 +0,0 @@ -package dev.caskeleton.messaging.nats; - -/** - * How a JetStream consumer acknowledges what it has handled. - * - *

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. - * - *

{@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"; - }; - } -} diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfile.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfile.java deleted file mode 100644 index 2713ab2..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfile.java +++ /dev/null @@ -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. - * - *

{@code maxDeliver} is the setting that makes the platform's dead-lettering necessary. When a - * message reaches it, JetStream terminates 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. - * - *

{@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 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. - * - *

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"); - } - } -} diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfileValidator.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfileValidator.java deleted file mode 100644 index e5aaf17..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamProfileValidator.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

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); - } -} diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamTransport.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamTransport.java deleted file mode 100644 index bf8f5c8..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsJetStreamTransport.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

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. - * - *

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 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 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 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. - * - *

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 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. - * - *

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 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 publish( - String subject, Optional deduplicationId, TransportPublishRequest request); - } -} diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingWorkflow.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingWorkflow.java deleted file mode 100644 index d13ee0c..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingWorkflow.java +++ /dev/null @@ -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. - * - *

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. - * - *

The parking therefore happens on the delivery before 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. - * - *

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. - * - *

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(); - } -} diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsPreSendRejection.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsPreSendRejection.java deleted file mode 100644 index 039addc..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsPreSendRejection.java +++ /dev/null @@ -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}. - * - *

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. - * - *

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; - } -} diff --git a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsStreamPosition.java b/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsStreamPosition.java deleted file mode 100644 index 7463b69..0000000 --- a/messaging/messaging-nats-experimental/src/main/java/dev/caskeleton/messaging/nats/NatsStreamPosition.java +++ /dev/null @@ -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. - * - *

Two sequences, because they answer different questions. The stream sequence identifies the - * message and is what a replay seeks to. The consumer sequence counts deliveries 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 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)); - } -} diff --git a/messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsAdapterContractTest.java b/messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsAdapterContractTest.java deleted file mode 100644 index 6e9dd33..0000000 --- a/messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsAdapterContractTest.java +++ /dev/null @@ -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> capturedDeduplicationIds = new ArrayList<>(); - - private NatsJetStreamTransport confirming(Optional 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 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 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 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())); - } -} diff --git a/messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingTest.java b/messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingTest.java deleted file mode 100644 index 93d0a0c..0000000 --- a/messaging/messaging-nats-experimental/src/test/java/dev/caskeleton/messaging/nats/NatsMaxDeliverParkingTest.java +++ /dev/null @@ -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(); - } -} diff --git a/messaging/messaging-outbox-jdbc-postgresql/build.gradle b/messaging/messaging-outbox-jdbc-postgresql/build.gradle index 36beb14..c933afe 100644 --- a/messaging/messaging-outbox-jdbc-postgresql/build.gradle +++ b/messaging/messaging-outbox-jdbc-postgresql/build.gradle @@ -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' diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java b/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java index 992ad2f..0e2d870 100644 --- a/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java +++ b/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java @@ -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 diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumMappedRecord.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumMappedRecord.java deleted file mode 100644 index cd53419..0000000 --- a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumMappedRecord.java +++ /dev/null @@ -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. - * - *

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 key, byte[] payload, Map 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)); - } -} diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxEventRouter.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxEventRouter.java deleted file mode 100644 index dbb64a8..0000000 --- a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxEventRouter.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

The message key and the topic are two different questions and used to be answered by one - * column. {@code destination} routed the topic and 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. - * - *

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 connectorConfiguration(String topicPrefix) { - Objects.requireNonNull(topicPrefix, "topicPrefix must not be null"); - Map 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. - * - *

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 reservedHeaders(OutboxRecord record) { - Objects.requireNonNull(record, "record must not be null"); - Map 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. - * - *

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()); - } -} diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxProfile.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxProfile.java deleted file mode 100644 index 4c08572..0000000 --- a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxProfile.java +++ /dev/null @@ -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. - * - *

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"); - } - } -} diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java b/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java deleted file mode 100644 index 513f246..0000000 --- a/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapper.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

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 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 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)); - } -} diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/debezium/outbox-event-router.properties b/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/debezium/outbox-event-router.properties deleted file mode 100644 index b28a254..0000000 --- a/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/debezium/outbox-event-router.properties +++ /dev/null @@ -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 diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java b/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java deleted file mode 100644 index e49e162..0000000 --- a/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/DebeziumOutboxRecordMapperTest.java +++ /dev/null @@ -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 headers) { - return record(headers, OutboxCanonicalMetadata.none()); - } - - private static OutboxRecord record( - Map 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 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 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 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); - } -} diff --git a/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java b/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java index 471ba56..3a8256a 100644 --- a/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java +++ b/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java @@ -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 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 payloads = new ArrayList<>(); + + List payloads() { + return List.copyOf(payloads); + } + + @Override + public CompletionStage 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() {} +} diff --git a/messaging/messaging-pulsar-experimental/build.gradle b/messaging/messaging-pulsar-experimental/build.gradle deleted file mode 100644 index 929bf94..0000000 --- a/messaging/messaging-pulsar-experimental/build.gradle +++ /dev/null @@ -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') - -} diff --git a/messaging/messaging-pulsar-experimental/gradle.lockfile b/messaging/messaging-pulsar-experimental/gradle.lockfile deleted file mode 100644 index f5ad1bb..0000000 --- a/messaging/messaging-pulsar-experimental/gradle.lockfile +++ /dev/null @@ -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= diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagePosition.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagePosition.java deleted file mode 100644 index 7271ac0..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagePosition.java +++ /dev/null @@ -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. - * - *

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 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); - } -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagingTransport.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagingTransport.java deleted file mode 100644 index 1884d57..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarMessagingTransport.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

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 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 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 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. - * - *

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 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 send(String topic, TransportPublishRequest request); - } -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarPreSendRejection.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarPreSendRejection.java deleted file mode 100644 index 6cf5f62..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarPreSendRejection.java +++ /dev/null @@ -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}. - * - *

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. - * - *

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; - } -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfile.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfile.java deleted file mode 100644 index 154cce1..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfile.java +++ /dev/null @@ -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. - * - *

{@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 is the backoff, and setting it to - * zero converts a failing handler into a spin loop against the broker. - * - *

{@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 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"); - } - } -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfileValidator.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfileValidator.java deleted file mode 100644 index b0e0db3..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarProfileValidator.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

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); - } -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionMode.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionMode.java deleted file mode 100644 index 4d2c53e..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionMode.java +++ /dev/null @@ -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. - * - *

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; - } -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionType.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionType.java deleted file mode 100644 index 4a88a32..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionType.java +++ /dev/null @@ -1,17 +0,0 @@ -package dev.caskeleton.messaging.pulsar; - -/** - * The Pulsar subscription types the Experimental adapter exposes. - * - *

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 -} diff --git a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarTransactionCapability.java b/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarTransactionCapability.java deleted file mode 100644 index 104caf4..0000000 --- a/messaging/messaging-pulsar-experimental/src/main/java/dev/caskeleton/messaging/pulsar/PulsarTransactionCapability.java +++ /dev/null @@ -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. - * - *

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". - * - *

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. - * - *

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"); - } -} diff --git a/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java b/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java deleted file mode 100644 index 0ec8223..0000000 --- a/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarAdapterContractTest.java +++ /dev/null @@ -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 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())); - } -} diff --git a/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionGuardTest.java b/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionGuardTest.java deleted file mode 100644 index a7dea10..0000000 --- a/messaging/messaging-pulsar-experimental/src/test/java/dev/caskeleton/messaging/pulsar/PulsarSubscriptionGuardTest.java +++ /dev/null @@ -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(); - } -} diff --git a/messaging/messaging-rabbit/build.gradle b/messaging/messaging-rabbit/build.gradle deleted file mode 100644 index f346996..0000000 --- a/messaging/messaging-rabbit/build.gradle +++ /dev/null @@ -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.' - } -} diff --git a/messaging/messaging-rabbit/gradle.lockfile b/messaging/messaging-rabbit/gradle.lockfile deleted file mode 100644 index e5000c2..0000000 --- a/messaging/messaging-rabbit/gradle.lockfile +++ /dev/null @@ -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= diff --git a/messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitBrokerIT.java b/messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitBrokerIT.java deleted file mode 100644 index 7937f52..0000000 --- a/messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitBrokerIT.java +++ /dev/null @@ -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. - * - *

The test that matters is the unroutable one. AMQP delivers a {@code basic.return} - * before 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. - * - *

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 withSequence(MessageProperties source, long sequence) { - java.util.Map headers = new java.util.LinkedHashMap<>(source.getHeaders()); - headers.put("x-seq", Long.toString(sequence)); - return headers; - } - - private static PublishResult await( - CompletionStage 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 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())); - } -} diff --git a/messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitFixtureProfiles.java b/messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitFixtureProfiles.java deleted file mode 100644 index da40530..0000000 --- a/messaging/messaging-rabbit/src/integrationTest/java/dev/caskeleton/messaging/rabbit/RabbitFixtureProfiles.java +++ /dev/null @@ -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()); - } -} diff --git a/messaging/messaging-rabbit/src/jmh/java/dev/caskeleton/messaging/rabbit/RabbitPublishBenchmark.java b/messaging/messaging-rabbit/src/jmh/java/dev/caskeleton/messaging/rabbit/RabbitPublishBenchmark.java deleted file mode 100644 index e8e2d46..0000000 --- a/messaging/messaging-rabbit/src/jmh/java/dev/caskeleton/messaging/rabbit/RabbitPublishBenchmark.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 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. - * - *

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))); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBatchConsumerRegistrar.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBatchConsumerRegistrar.java deleted file mode 100644 index 68ab87a..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBatchConsumerRegistrar.java +++ /dev/null @@ -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. - * - *

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. - * - *

{@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. - * - *

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 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 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 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 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. - * - *

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 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 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"); - } - } - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBrokerProfile.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBrokerProfile.java deleted file mode 100644 index e53d377..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitBrokerProfile.java +++ /dev/null @@ -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 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); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitChannelPublisher.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitChannelPublisher.java deleted file mode 100644 index 8fe08f2..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitChannelPublisher.java +++ /dev/null @@ -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. - * - *

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. - * - *

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() {} -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinator.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinator.java deleted file mode 100644 index f65c985..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinator.java +++ /dev/null @@ -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. - * - *

This is the piece that makes the Rabbit adapter honest. AMQP delivers a return before - * 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. - * - *

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. - * - *

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. - * - *

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 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 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. - * - *

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 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. - * - *

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. - * - *

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 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()); - } - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConsumerRegistrar.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConsumerRegistrar.java deleted file mode 100644 index 1852966..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitConsumerRegistrar.java +++ /dev/null @@ -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. - * - *

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 different message, which shows up as - * unexplained loss under load, far from its cause. - * - *

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 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. - * - *

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 pause(String scope) { - pausedScopes.add(scope == null ? "" : scope); - return CompletableFuture.completedFuture(null); - } - - @Override - public CompletionStage 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 acknowledge() { - return controller.ack(); - } - - @Override - public CompletionStage 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 discard() { - return controller.reject( - FailureDescriptor.of( - FailureCategory.PERMANENT_BUSINESS, "RABBIT_DISCARDED", "the message was discarded")); - } - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeadLetterPublisher.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeadLetterPublisher.java deleted file mode 100644 index e534a91..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeadLetterPublisher.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 deadLetter( - DestinationProfile profile, - MessageDelivery 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. - * - *

{@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 reject(long deliveryTag); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java deleted file mode 100644 index 0572c18..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitDeliveryMapper.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 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); - } - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitHeaderMapper.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitHeaderMapper.java deleted file mode 100644 index dc5124c..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitHeaderMapper.java +++ /dev/null @@ -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. - * - *

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 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. - * - *

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. - * - *

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 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); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitMessagingTransport.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitMessagingTransport.java deleted file mode 100644 index b6d5862..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitMessagingTransport.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 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 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 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 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 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. - * - *

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 completed(TransportPublishResult result) { - return CompletableFuture.completedFuture(result); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitNativeDeadLetterCapability.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitNativeDeadLetterCapability.java deleted file mode 100644 index 84d5e88..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitNativeDeadLetterCapability.java +++ /dev/null @@ -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. - * - *

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 not 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. - * - *

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: the source is settled only after the dead-letter - * publish is confirmed. - */ -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"; - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidator.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidator.java deleted file mode 100644 index 3463b5c..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidator.java +++ /dev/null @@ -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. - * - *

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. - * - *

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()); - } - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishFailureClassifier.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishFailureClassifier.java deleted file mode 100644 index c9408b9..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishFailureClassifier.java +++ /dev/null @@ -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. - * - *

The distinction that matters is where the failure happened. A channel-level exception raised - * before {@code basicPublish} returned means nothing was written: rejected, with no - * ambiguity. A connection that drops after the frame was written proves nothing — the - * broker may have the message and only the confirm was lost. - * - *

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(); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishMapper.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishMapper.java deleted file mode 100644 index ec03aae..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishMapper.java +++ /dev/null @@ -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. - * - *

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(""); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishReference.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishReference.java deleted file mode 100644 index aee6d79..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitPublishReference.java +++ /dev/null @@ -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 diagnosticAttributes() { - return Map.of( - "exchange", exchange, - "routingKey", routingKey, - "sequence", Long.toString(sequence)); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRequestReply.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRequestReply.java deleted file mode 100644 index 2854b41..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRequestReply.java +++ /dev/null @@ -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. - * - *

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> request( - MessageDestination destination, - MessageEnvelope request, - Duration timeout); -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRetryQueueTopology.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRetryQueueTopology.java deleted file mode 100644 index ca42dfb..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitRetryQueueTopology.java +++ /dev/null @@ -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. - * - *

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 queueArguments() { - Map 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); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSecurityConfigurer.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSecurityConfigurer.java deleted file mode 100644 index 9841916..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSecurityConfigurer.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 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. - * - *

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. - * - *

{@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); - } - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementController.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementController.java deleted file mode 100644 index 3f0a248..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementController.java +++ /dev/null @@ -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. - * - *

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 different - * message — a failure mode that shows up as unexplained message loss under load, far from its - * cause. - * - *

{@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 ack() { - return terminal(() -> operations.ack(deliveryTag)); - } - - @Override - public CompletionStage retry(Duration delay) { - Objects.requireNonNull(delay, "delay must not be null"); - return terminal(() -> operations.publishToRetryQueue(deliveryTag, delay)); - } - - @Override - public CompletionStage deadLetter(FailureDescriptor failure) { - Objects.requireNonNull(failure, "failure must not be null"); - return terminal(() -> operations.deadLetter(deliveryTag, failure)); - } - - @Override - public CompletionStage 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 terminal( - java.util.function.Supplier> operation) { - if (!settled.compareAndSet(false, true)) { - return CompletableFuture.failedFuture( - new MessageSettlementException( - "SETTLEMENT_ALREADY_COMPLETED", - "delivery tag " + deliveryTag + " has already been settled")); - } - return operation.get(); - } -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementOperations.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementOperations.java deleted file mode 100644 index 6f2c975..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitSettlementOperations.java +++ /dev/null @@ -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. - * - *

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 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 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 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 discard(long deliveryTag, FailureDescriptor failure); -} diff --git a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitTopologyProfile.java b/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitTopologyProfile.java deleted file mode 100644 index 66633bb..0000000 --- a/messaging/messaging-rabbit/src/main/java/dev/caskeleton/messaging/rabbit/RabbitTopologyProfile.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 deadLetterExchange, - Optional deadLetterRoutingKey, - Optional 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 queueArguments() { - Map 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"); - } - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitAdapterContractTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitAdapterContractTest.java deleted file mode 100644 index 60d8e24..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitAdapterContractTest.java +++ /dev/null @@ -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. - * - *

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(); - } - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinatorTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinatorTest.java deleted file mode 100644 index c9bd1ec..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitConfirmCoordinatorTest.java +++ /dev/null @@ -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 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 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 stage = - coordinator.awaiting(1L, "notification.work", "missing", REPLICATION); - - coordinator.returned(1L); - - assertThat(stage.toCompletableFuture()).isNotDone(); - assertThat(coordinator.pendingCount()).isEqualTo(1); - } - - @Test - void aNackIsARejectedPublish() { - CompletionStage 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 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 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 - first = coordinator.awaiting(1L, "orders", "created", REPLICATION).toCompletableFuture(); - java.util.concurrent.CompletableFuture - second = coordinator.awaiting(2L, "orders", "created", REPLICATION).toCompletableFuture(); - java.util.concurrent.CompletableFuture - 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 - 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 - 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(); - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitContractHarness.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitContractHarness.java deleted file mode 100644 index 54394d5..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitContractHarness.java +++ /dev/null @@ -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. - * - *

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. - * - *

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 = new ArrayDeque<>(); - private final List deadLetters = new ArrayList<>(); - private final Set 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 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 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 drain(HandleOutcome outcome) { - List batch = new ArrayList<>(pending); - pending.clear(); - - List 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 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 deadLettered() { - return List.copyOf(deadLetters); - } - - @Override - public List 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 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 - 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 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 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; - } - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitEnvelopeRoundTripTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitEnvelopeRoundTripTest.java deleted file mode 100644 index 4a6f105..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitEnvelopeRoundTripTest.java +++ /dev/null @@ -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. - * - *

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 published = - envelope( - MessageHeaders.application( - Map.of(new HeaderName("x-source-system"), new HeaderValue("erp")))); - - MessageEnvelope 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 published = - envelope(MessageHeaders.empty()) - .withTenant(new dev.caskeleton.messaging.api.TenantContext("acme")); - - MessageEnvelope 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 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 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 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 roundTrip(MessageEnvelope published) { - MessageProperties properties = headerMapper.toProperties(published); - return deliveryMapper.toEnvelope(new Message(published.payload().bytes(), properties)); - } - - private static MessageEnvelope retryStamped(int attempt) { - Map 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 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())); - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidatorTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidatorTest.java deleted file mode 100644 index ba0f14f..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitProfileValidatorTest.java +++ /dev/null @@ -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(); - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitRuntimeTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitRuntimeTest.java deleted file mode 100644 index 903beae..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitRuntimeTest.java +++ /dev/null @@ -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 published = new ArrayList<>(); - private final List 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 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 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 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 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 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 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> sink) { - return new RabbitConsumerRegistrar( - new TransportConsumerSpec(RabbitProfileFixtures.workQueueDestination(), sink), - operations, - new GracefulShutdownCoordinator(Duration.ofSeconds(30))); - } - - private CompletionStage 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 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(); - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitSettlementControllerTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitSettlementControllerTest.java deleted file mode 100644 index f0cba51..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitSettlementControllerTest.java +++ /dev/null @@ -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 calls = new ArrayList<>(); - - @Override - public CompletionStage ack(long deliveryTag) { - calls.add("ack:" + deliveryTag); - return CompletableFuture.completedFuture(SettlementResult.settled()); - } - - @Override - public CompletionStage publishToRetryQueue(long deliveryTag, Duration delay) { - calls.add("retry:" + deliveryTag + ":" + delay); - return CompletableFuture.completedFuture(SettlementResult.settled()); - } - - @Override - public CompletionStage deadLetter(long deliveryTag, FailureDescriptor failure) { - calls.add("deadLetter:" + deliveryTag); - return CompletableFuture.completedFuture(SettlementResult.settled()); - } - - @Override - public CompletionStage discard(long deliveryTag, FailureDescriptor failure) { - calls.add("discard:" + deliveryTag); - return CompletableFuture.completedFuture(SettlementResult.settled()); - } -} diff --git a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitTopologyAndBatchTest.java b/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitTopologyAndBatchTest.java deleted file mode 100644 index 040513e..0000000 --- a/messaging/messaging-rabbit/src/test/java/dev/caskeleton/messaging/rabbit/RabbitTopologyAndBatchTest.java +++ /dev/null @@ -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(); - } -} diff --git a/messaging/messaging-rabbit/src/testFixtures/java/dev/caskeleton/messaging/rabbit/RabbitProfileFixtures.java b/messaging/messaging-rabbit/src/testFixtures/java/dev/caskeleton/messaging/rabbit/RabbitProfileFixtures.java deleted file mode 100644 index e505cd2..0000000 --- a/messaging/messaging-rabbit/src/testFixtures/java/dev/caskeleton/messaging/rabbit/RabbitProfileFixtures.java +++ /dev/null @@ -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); - } -} diff --git a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java index 4942565..fe59a3e 100644 --- a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java @@ -301,6 +301,14 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM } private MessageEnvelope encode(MessageEnvelope 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 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()); diff --git a/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java b/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java index 510c451..5302ed6 100644 --- a/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java +++ b/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java @@ -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 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() { diff --git a/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile b/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile index 53df71c..ffc4211 100644 --- a/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile +++ b/messaging/messaging-spring-boot-starter-kafka/gradle.lockfile @@ -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 diff --git a/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java b/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java index cc2b247..bec88a6 100644 --- a/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java +++ b/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java @@ -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. * *

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 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 messagingKafkaProducer( - org.springframework.core.env.Environment environment) { + org.springframework.core.env.Environment environment, + CompiledMessagingConfiguration compiled, + ObjectProvider declaredSecurity, + ObjectProvider 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 producerConfig( + org.springframework.core.env.Environment environment, + CompiledMessagingConfiguration compiled, + ObjectProvider declaredSecurity, + ObjectProvider 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. + * + *

{@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 producerSecurity( + CompiledMessagingConfiguration compiled, + ObjectProvider declaredSecurity, + ObjectProvider securityConfigurer) { + java.util.Map 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 names = + kafkaBrokers.isEmpty() ? java.util.Set.of(BrokerSettings.KAFKA) : kafkaBrokers.keySet(); + java.util.List 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()); } /** diff --git a/messaging/messaging-spring-boot-starter-rabbit/build.gradle b/messaging/messaging-spring-boot-starter-rabbit/build.gradle deleted file mode 100644 index 3635e1c..0000000 --- a/messaging/messaging-spring-boot-starter-rabbit/build.gradle +++ /dev/null @@ -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' -} diff --git a/messaging/messaging-spring-boot-starter-rabbit/gradle.lockfile b/messaging/messaging-spring-boot-starter-rabbit/gradle.lockfile deleted file mode 100644 index 1d3075d..0000000 --- a/messaging/messaging-spring-boot-starter-rabbit/gradle.lockfile +++ /dev/null @@ -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= diff --git a/messaging/messaging-spring-boot-starter-rabbit/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java b/messaging/messaging-spring-boot-starter-rabbit/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java deleted file mode 100644 index f64cd42..0000000 --- a/messaging/messaging-spring-boot-starter-rabbit/src/main/java/dev/caskeleton/messaging/autoconfigure/RabbitMessagingAutoConfiguration.java +++ /dev/null @@ -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. - * - *

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. - * - *

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. - * - *

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 - 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. - * - *

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 - 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(); - } -} diff --git a/messaging/messaging-spring-boot-starter/README.md b/messaging/messaging-spring-boot-starter/README.md index 9580cea..2cb6c3e 100644 --- a/messaging/messaging-spring-boot-starter/README.md +++ b/messaging/messaging-spring-boot-starter/README.md @@ -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..type: rabbitmq` 설정 family는 아직 바인딩·검증되지만 소비하는 transport가 +없다. diff --git a/messaging/messaging-spring-boot-starter/build.gradle b/messaging/messaging-spring-boot-starter/build.gradle index 14167fa..acae04e 100644 --- a/messaging/messaging-spring-boot-starter/build.gradle +++ b/messaging/messaging-spring-boot-starter/build.gradle @@ -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 diff --git a/messaging/messaging-spring-boot-starter/gradle.lockfile b/messaging/messaging-spring-boot-starter/gradle.lockfile index 7f5981c..d606cfc 100644 --- a/messaging/messaging-spring-boot-starter/gradle.lockfile +++ b/messaging/messaging-spring-boot-starter/gradle.lockfile @@ -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 diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java index 5274dd5..fb3a111 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/BrokerSettings.java @@ -7,18 +7,16 @@ import org.springframework.boot.context.properties.bind.DefaultValue; /** * One entry of {@code app.messaging.brokers}. * - *

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. + *

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. * *

{@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 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"; } diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java index dca2d39..88fa8cb 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java @@ -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)); } } diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java index 84e9baa..b5c534a 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationKeyValidator.java @@ -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 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 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. - * - *

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 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) {} diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java index 81b0602..a61db17 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java @@ -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 configuredNames = diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java index 8e3b816..3534ca2 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java @@ -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. * - *

{@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. + *

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, diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java index 227965c..91cf33b 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java @@ -13,9 +13,9 @@ import org.springframework.util.ClassUtils; /** * Selects exactly one transport, from a closed registry, by name (MSG-INT-004). * - *

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 + *

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; *

  • a broker id outside the registry — the operator set something the platform cannot honour; *
  • 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; - *
  • a blank broker while messaging is on — the master switch says yes and nothing says what to. + *
  • a blank broker while messaging is on — the capability switch says yes and nothing says what + * to. * * *

    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 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 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 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. - * - *

    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. - * - *

    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 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 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 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; } diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java index 92fef98..9985b6e 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java @@ -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. * - *

    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. - * *

    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 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 { diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java new file mode 100644 index 0000000..ac651f8 --- /dev/null +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java @@ -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. + * + *

    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 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 expiresAt(String credentialId) { + return Optional.empty(); + } + }; + } + } +} diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java index ba6b2c7..6c82922 100644 --- a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java @@ -98,30 +98,16 @@ class MessagingAutoConfigurationTest { .hasMessageContaining("exactly one logical broker")); } - @Test - void experimentalAdaptersAndTheBridgeAreOffByDefault() { - runner.run( - context -> { - MessagingSettings properties = context.getBean(MessagingSettings.class); - assertThat(properties.getExperimental().isKafkaShare()).isFalse(); - assertThat(properties.getExperimental().isPulsar()).isFalse(); - assertThat(properties.getExperimental().isNats()).isFalse(); - assertThat(properties.getBridge().isSpringCloudStream()).isFalse(); - }); - } - @Test void propertiesBindFromConfiguration() { runner .withPropertyValues( - "app.messaging.experimental.pulsar=true", "app.messaging.backpressure.global-limit=64", "app.messaging.backpressure.per-destination-limit=8", "app.messaging.shutdown.drain-deadline=15s") .run( context -> { MessagingSettings properties = context.getBean(MessagingSettings.class); - assertThat(properties.getExperimental().isPulsar()).isTrue(); assertThat(properties.getBackpressure().getGlobalLimit()).isEqualTo(64); assertThat(properties.getShutdown().getDrainDeadline()) .isEqualTo(java.time.Duration.ofSeconds(15)); diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java index 437ca3f..73f8a08 100644 --- a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java @@ -67,15 +67,12 @@ class MessagingConfigurationBindingTest { CompiledMessagingConfiguration compiled = context.getBean(CompiledMessagingConfiguration.class); - assertThat(compiled.brokers()).containsKeys("kafka-primary", "rabbit-primary"); + assertThat(compiled.brokers()).containsOnlyKeys("kafka-primary"); BrokerSettings kafka = compiled.brokers().get("kafka-primary"); assertThat(kafka.type()).isEqualTo(BrokerSettings.KAFKA); assertThat(kafka.bootstrapServers()) .containsExactly("broker-1:9093", "broker-2:9093"); assertThat(kafka.enableAutoCommit()).isFalse(); - BrokerSettings rabbit = compiled.brokers().get("rabbit-primary"); - assertThat(rabbit.type()).isEqualTo(BrokerSettings.RABBITMQ); - assertThat(rabbit.quorumQueues()).isTrue(); assertThat(compiled.security()) .singleElement() .satisfies( @@ -175,7 +172,7 @@ class MessagingConfigurationBindingTest { } @Test - void aRabbitSettingOnAKafkaBrokerFailsNamingTheKey() { + void aRabbitMqSettingBindsNothingAndFailsNamingTheKey() { runner .withPropertyValues(minimal()) .withPropertyValues("app.messaging.brokers.kafka-primary.prefetch=32") @@ -184,8 +181,22 @@ class MessagingConfigurationBindingTest { assertThat(context) .hasFailed() .getFailure() - .hasMessageContaining("app.messaging.brokers.kafka-primary.prefetch") - .hasMessageContaining("RabbitMQ setting on a Kafka broker")); + .hasMessageContaining( + "app.messaging.brokers.kafka-primary.prefetch binds nothing")); + } + + @Test + void aRabbitMqBrokerIsRefusedBecauseNoTransportExists() { + runner + .withPropertyValues( + "app.messaging.brokers.rabbit-primary.type=rabbitmq", + "app.messaging.brokers.rabbit-primary.bootstrap-servers[0]=rabbit:5672") + .run( + context -> + assertThat(context) + .hasFailed() + .getFailure() + .hasMessageContaining("app.messaging.brokers.rabbit-primary.type")); } @Test diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java index 033fb0d..4da59b9 100644 --- a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java @@ -15,17 +15,16 @@ import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.springframework.boot.autoconfigure.AutoConfigurations; import org.springframework.boot.test.context.runner.ApplicationContextRunner; -import org.springframework.util.ClassUtils; /** * Off means nothing, and on means exactly one transport (MSG-INT-004). * *

    The starter registered five auto-configurations and none carried a messaging master condition, * so an application acquired the platform by having the starter on its classpath. Worse, provider - * selection was {@code @ConditionalOnClass} while this starter depends on {@code messaging-kafka} - * and {@code messaging-rabbit}, each of which exposes its client library as {@code api} — so both - * conditions are true for **every** adopter, always. Selection by classpath could not select; it - * assembled both and let a {@code @ConditionalOnMissingBean} race decide where messages went. + * selection was {@code @ConditionalOnClass} while this starter depended on two broker adapters, + * each exposing its client library as {@code api} — so both conditions were true for **every** + * adopter, always. Selection by classpath could not select; it assembled both and let a + * {@code @ConditionalOnMissingBean} race decide where messages went. * *

    The cases below are the replacement contract. The off case is deliberately checked on bean * names and live threads rather than on a handful of types: a platform that leaves a scheduler @@ -38,40 +37,41 @@ class MessagingStarterOffContractTest { .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)); @Test - @DisplayName( - "both client libraries really are on this classpath, so the old condition could not select") - void bothClientLibrariesArePresent() { - ClassLoader loader = getClass().getClassLoader(); - - assertThat(ClassUtils.isPresent("org.apache.kafka.clients.producer.Producer", loader)) - .as("messaging-kafka exposes kafka-clients as api") - .isTrue(); - assertThat(ClassUtils.isPresent("com.rabbitmq.client.Channel", loader)) - .as("messaging-rabbit exposes spring-rabbit as api") - .isTrue(); + @DisplayName("present without the switch is on") + void presentWithoutTheSwitchIsOn() { + runner + .withPropertyValues( + "app.messaging.broker=kafka", "spring.kafka.bootstrap-servers=localhost:9092") + .run( + context -> { + assertThat(context).hasNotFailed(); + assertThat(context).hasSingleBean(MessagePublisher.class); + }); } @Test @DisplayName("with the switch off there are no platform beans") void offMeansNoBeans() { - runner.run( - context -> { - assertThat(context).hasNotFailed(); + runner + .withPropertyValues("app.messaging.enabled=false") + .run( + context -> { + assertThat(context).hasNotFailed(); - Set platformBeans = - java.util.Arrays.stream(context.getBeanDefinitionNames()) - .filter( - name -> { - Class type = context.getBeanFactory().getType(name, false); - return type != null - && type.getName().startsWith("dev.caskeleton.messaging."); - }) - .collect(Collectors.toSet()); + Set platformBeans = + java.util.Arrays.stream(context.getBeanDefinitionNames()) + .filter( + name -> { + Class type = context.getBeanFactory().getType(name, false); + return type != null + && type.getName().startsWith("dev.caskeleton.messaging."); + }) + .collect(Collectors.toSet()); - assertThat(platformBeans) - .as("off is a structural fact, not a set of individually-conditioned beans") - .isEmpty(); - }); + assertThat(platformBeans) + .as("off is a structural fact, not a set of individually-conditioned beans") + .isEmpty(); + }); } @Test @@ -79,7 +79,9 @@ class MessagingStarterOffContractTest { void offMeansNoThreads() { Set before = liveThreadNames(); - runner.run(context -> assertThat(context).hasNotFailed()); + runner + .withPropertyValues("app.messaging.enabled=false") + .run(context -> assertThat(context).hasNotFailed()); assertThat(newMessagingThreadsSince(before)) .as("a bean that exists but was never started is acceptable; a running thread is not") @@ -111,11 +113,11 @@ class MessagingStarterOffContractTest { .hasFailed() .getFailure() .rootCause() - .hasMessageContaining("registered: [kafka, rabbit]")); + .hasMessageContaining("registered: [kafka]")); } @Test - @DisplayName("selecting Kafka assembles Kafka and not Rabbit") + @DisplayName("selecting Kafka assembles Kafka") void selectingKafkaAssemblesOnlyKafka() { withAPublisher() .withPropertyValues( @@ -126,48 +128,9 @@ class MessagingStarterOffContractTest { context -> { assertThat(context).hasNotFailed(); assertThat(context).hasSingleBean(KafkaMessagingAutoConfiguration.class); - assertThat(context) - .as("both client libraries are present, so only the property can be selecting") - .doesNotHaveBean(RabbitMessagingAutoConfiguration.class); }); } - @Test - @DisplayName("selecting Rabbit is refused, and the message says the transport is not finished") - void selectingRabbitIsRefused() { - // This test used to run under `withAPublisher()` and assert the context started. The fake - // MessagePublisher tripped @ConditionalOnMissingBean and removed the very bean whose missing - // dependency is the defect — so a configuration that cannot start in any deployment passed as - // "assembles Rabbit and not Kafka". Without the fake, the real behaviour appears. - // - // Rabbit ships validators and a security configurer and no MessagingTransport, because its - // native channel publisher has only test implementations. That is refused at selection now, - // where the message can say so, rather than surfacing as "No qualifying bean of type - // MessagingTransport" from inside the core configuration. - runner - .withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit") - .run( - context -> { - assertThat(context).hasFailed(); - assertThat(context.getStartupFailure()) - .rootCause() - .hasMessageContaining("app.messaging.broker=rabbit") - .hasMessageContaining("no MessagingTransport") - .hasMessageContaining("kafka"); - }); - } - - @Test - @DisplayName("a fake publisher does not make an unassemblable transport look assemblable") - void aFakePublisherDoesNotHideAnUnassemblableTransport() { - // The guard on the test above. Supplying a MessagePublisher removes the dependency that fails, - // so if the refusal ever moves back to bean wiring this case goes green while the deployment - // stays broken. Selection-time refusal is what makes it fail either way. - withAPublisher() - .withPropertyValues("app.messaging.enabled=true", "app.messaging.broker=rabbit") - .run(context -> assertThat(context).hasFailed()); - } - @Test @DisplayName("MSG-INT-003: a selected transport now assembles a publisher") void aSelectedTransportAssemblesAPublisher() { @@ -279,8 +242,6 @@ class MessagingStarterOffContractTest { name -> { String lower = name.toLowerCase(java.util.Locale.ROOT); return lower.contains("kafka") - || lower.contains("rabbit") - || lower.contains("amqp") || lower.contains("messaging") || lower.contains("outbox"); }) diff --git a/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml b/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml index 8101b6e..b1894f0 100644 --- a/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml +++ b/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml @@ -1,16 +1,6 @@ # A configuration the platform accepts. -# -# Every experimental adapter is off and the bridge is off, which is the shipped default: an -# adapter whose contract suite is still being proven must never become load-bearing because a -# configuration defaulted it on. backend: messaging: - experimental: - kafka-share: false - pulsar: false - nats: false - bridge: - spring-cloud-stream: false backpressure: # The per-destination limit stays below the global one; a per-destination limit at or above # the global limit would let one destination consume every slot in the process. diff --git a/messaging/messaging-spring-cloud-stream-bridge/build.gradle b/messaging/messaging-spring-cloud-stream-bridge/build.gradle deleted file mode 100644 index d104567..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/build.gradle +++ /dev/null @@ -1,10 +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') - -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/gradle.lockfile b/messaging/messaging-spring-cloud-stream-bridge/gradle.lockfile deleted file mode 100644 index e2c9585..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/gradle.lockfile +++ /dev/null @@ -1,84 +0,0 @@ -# This is a Gradle generated file for dependency locking. -# Manual edits can break the build and are not advised. -# This file is expected to be part of source control. -com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor -com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor -com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs -com.github.spotbugs:spotbugs:4.10.2=spotbugs -com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs -com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor -com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor -com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor -com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs -com.google.code.gson:gson:2.13.2=spotbugs -com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_annotations:2.41.0=spotbugs -com.google.errorprone:error_prone_annotations:2.47.0=checkstyle -com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor -com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor -com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor -com.google.guava:guava:33.6.0-jre=checkstyle -com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor -com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor -com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins -com.puppycrawl.tools:checkstyle:13.5.0=checkstyle -commons-beanutils:commons-beanutils:1.11.0=checkstyle -commons-collections:commons-collections:3.2.2=checkstyle -commons-io:commons-io:2.21.0=spotbugs -info.picocli:picocli:4.7.7=checkstyle -io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor -io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor -javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor -jaxen:jaxen:2.0.6=spotbugs -net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath -net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs -org.antlr:antlr4-runtime:4.13.2=checkstyle -org.apache.bcel:bcel:6.12.0=spotbugs -org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs -org.apache.commons:commons-text:1.15.0=spotbugs -org.apache.commons:commons-text:1.3=checkstyle -org.apache.httpcomponents:httpclient:4.5.13=checkstyle -org.apache.httpcomponents:httpcore:4.4.16=checkstyle -org.apache.logging.log4j:log4j-api:2.25.5=spotbugs -org.apache.logging.log4j:log4j-core:2.25.5=spotbugs -org.apache.maven.doxia:doxia-core:1.12.0=checkstyle -org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle -org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle -org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle -org.apache.xbean:xbean-reflect:3.7=checkstyle -org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath -org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath -org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle -org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle -org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle -org.codehaus.plexus:plexus-utils:3.3.0=checkstyle -org.dom4j:dom4j:2.2.0=spotbugs -org.javassist:javassist:3.28.0-GA=checkstyle -org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath -org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath -org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath -org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath -org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath -org.junit:junit-bom:6.1.0=spotbugs -org.mockito:mockito-core:5.20.0=mockitoAgent -org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath -org.ow2.asm:asm-analysis:9.10.1=spotbugs -org.ow2.asm:asm-commons:9.10.1=spotbugs -org.ow2.asm:asm-tree:9.10.1=spotbugs -org.ow2.asm:asm-util:9.10.1=spotbugs -org.ow2.asm:asm:9.10.1=spotbugs -org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor -org.reflections:reflections:0.10.2=checkstyle -org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j -org.slf4j:slf4j-simple:2.0.18=checkstyle -org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs -empty=compileClasspath,runtimeClasspath diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingCapabilityReport.java b/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingCapabilityReport.java deleted file mode 100644 index fb34a1a..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingCapabilityReport.java +++ /dev/null @@ -1,88 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import java.util.List; -import java.util.Objects; - -/** - * States, per binding, which platform guarantees the bridge does not provide. - * - *

    An explicit report rather than silence. The binder does provide retry and dead-lettering of - * its own, so a binding looks like it has them; what it does not have is the platform's versions — - * bounded attempts under the destination's retry policy, and a dead-letter publish confirmed before - * the source is settled. An operator comparing a bridged binding to a native one needs that - * difference written down, because nothing at runtime will show it. - * - * @param destination the logical destination - * @param bindingName the Stream binding name - * @param publishEvidenceAvailable whether the bridge can report broker publish evidence - * @param platformRetryApplied whether the destination's retry policy is enforced - * @param confirmedDeadLetterApplied whether dead-letter publishes are confirmed before settlement - * @param orderingEnforced whether the destination's ordering scope is enforced - */ -public record BindingCapabilityReport( - DestinationName destination, - String bindingName, - boolean publishEvidenceAvailable, - boolean platformRetryApplied, - boolean confirmedDeadLetterApplied, - boolean orderingEnforced) { - - public BindingCapabilityReport { - Objects.requireNonNull(destination, "destination must not be null"); - if (bindingName == null || bindingName.isBlank()) { - throw new IllegalArgumentException("bindingName must not be blank"); - } - } - - /** - * Returns the report for a binding served through the bridge. - * - *

    Every platform guarantee is false, because the bridge hands the message to the binder and - * the binder is what decides these. - * - * @param destination the logical destination - * @param bindingName the Stream binding name - * @return the report - */ - public static BindingCapabilityReport bridged(DestinationName destination, String bindingName) { - return new BindingCapabilityReport(destination, bindingName, false, false, false, false); - } - - /** - * Returns the guarantees this binding does not carry, as sanitized text. - * - * @return the gaps, empty when nothing is missing - */ - public List gaps() { - List gaps = new java.util.ArrayList<>(); - if (!publishEvidenceAvailable) { - gaps.add( - "publish evidence: the binder reports a send, not a broker confirmation, so an " - + "ambiguous publish is indistinguishable from a confirmed one"); - } - if (!platformRetryApplied) { - gaps.add( - "retry: the binder's own retry runs instead of the destination's retry policy, with its " - + "own attempt budget and backoff"); - } - if (!confirmedDeadLetterApplied) { - gaps.add( - "dead letter: the binder settles the source without waiting for the dead-letter publish " - + "to confirm, so a dead-letter outage loses the message"); - } - if (!orderingEnforced) { - gaps.add("ordering: the binder's concurrency settings decide ordering, not the profile"); - } - return List.copyOf(gaps); - } - - /** - * Reports whether this binding carries every platform guarantee. - * - * @return true when nothing is missing - */ - public boolean isFullyGuaranteed() { - return gaps().isEmpty(); - } -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingProfileValidator.java b/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingProfileValidator.java deleted file mode 100644 index cb3d159..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/BindingProfileValidator.java +++ /dev/null @@ -1,97 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.Objects; -import java.util.regex.Pattern; - -/** - * Checks a binding against its destination before the bridge is wired. - * - *

    Runs on top of {@link StreamBridgePolicyGuard}: the guard decides whether a destination is - * eligible for the bridge at all, and this decides whether a particular binding is configured - * coherently for it. - * - *

    The binder's extended properties are the sharp edge. Stream lets a binding override the - * serializer, the acknowledgement mode, and the concurrency, and each of those silently replaces - * something the destination profile already decided. Rather than merging the two — which produces a - * configuration nobody can read — a conflicting extended property is rejected and the operator is - * told which side to remove. - */ -public final class BindingProfileValidator { - - private static final Pattern BINDING_NAME = Pattern.compile("[a-zA-Z][a-zA-Z0-9-]{0,63}"); - - /** Extended properties that would override a platform decision. */ - private static final java.util.Set CONFLICTING_PROPERTIES = - java.util.Set.of( - "autoBindDlq", - "republishToDlq", - "maxAttempts", - "backOffInitialInterval", - "autoCommitOffset", - "ackMode", - "useNativeEncoding", - "contentType"); - - private final StreamBridgePolicyGuard guard = new StreamBridgePolicyGuard(); - - /** - * Validates one binding. - * - * @param profile the destination profile - * @param bindingName the Stream binding name - * @param extendedProperties the binder extended properties configured for the binding - * @param enabled whether the bridge is switched on - * @return the capability report for the accepted binding - */ - public BindingCapabilityReport validate( - DestinationProfile profile, - String bindingName, - java.util.Map extendedProperties, - boolean enabled) { - Objects.requireNonNull(profile, "profile must not be null"); - Objects.requireNonNull(extendedProperties, "extendedProperties must not be null"); - - guard.validate(profile, enabled); - - if (bindingName == null || !BINDING_NAME.matcher(bindingName).matches()) { - throw new MessagingConfigurationException( - "INVALID_BINDING_NAME", - "binding name must match %s: %s".formatted(BINDING_NAME.pattern(), bindingName)); - } - - for (String property : extendedProperties.keySet()) { - if (CONFLICTING_PROPERTIES.contains(property)) { - throw new MessagingConfigurationException( - "BINDING_OVERRIDES_PLATFORM_POLICY", - "binding %s sets %s, which overrides what the %s destination profile already decides; " - .formatted(bindingName, property, profile.name().value()) - + "remove it from the binding or move the destination to the native adapter"); - } - } - - if (profile.production()) { - throw new MessagingConfigurationException( - "BRIDGE_ON_PRODUCTION_DESTINATION", - "destination %s is marked production; the bridge does not carry the platform's publish " - .formatted(profile.name().value()) - + "evidence, retry, or confirmed dead lettering"); - } - - return BindingCapabilityReport.bridged(profile.name(), bindingName); - } - - /** - * Returns the report for a destination that is not bridged at all. - * - * @param destination the logical destination - * @param bindingName the Stream binding name - * @return a report stating every guarantee holds - */ - public static BindingCapabilityReport nativeAdapter( - DestinationName destination, String bindingName) { - return new BindingCapabilityReport(destination, bindingName, true, true, true, true); - } -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/MessagingBindingBridge.java b/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/MessagingBindingBridge.java deleted file mode 100644 index 49be29e..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/MessagingBindingBridge.java +++ /dev/null @@ -1,34 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import dev.caskeleton.messaging.api.destination.DestinationName; - -/** - * Connects a logical destination to a Spring Cloud Stream binding. - * - *

    The bridge is an interoperability seam, not a second messaging API. Its whole reason to exist - * is that a service already has Stream bindings and needs to reach the same destinations without a - * rewrite. - * - *

    Binder semantics are never promoted to platform guarantees. Stream's binder has its own retry, - * its own dead-letter, and its own acknowledgement mode, and they look enough like the platform's - * to be mistaken for them — so a destination that actually relies on the platform's versions is - * refused by {@link StreamBridgePolicyGuard} rather than served with the binder's. - */ -public interface MessagingBindingBridge { - - /** - * Binds a Stream output to a logical destination. - * - * @param destination the logical destination - * @param bindingName the Stream binding name - */ - void bindPublisher(DestinationName destination, String bindingName); - - /** - * Binds a Stream input to a logical destination. - * - * @param destination the logical destination - * @param bindingName the Stream binding name - */ - void bindConsumer(DestinationName destination, String bindingName); -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamConsumerBridge.java b/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamConsumerBridge.java deleted file mode 100644 index e0b304f..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamConsumerBridge.java +++ /dev/null @@ -1,87 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; - -/** - * Receives from a Spring Cloud Stream input binding and hands the message to a platform handler. - * - *

    Settlement stays with the binder. The bridge cannot acknowledge, retry, or dead-letter a - * message itself, because Stream's binder already owns the acknowledgement for that binding and two - * things settling one message is worse than either doing it alone. - * - *

    What the bridge does own is the translation and the honesty about it: a handler failure is - * rethrown so the binder's error channel sees it, rather than being converted into a platform - * {@code HandleResult} that nothing downstream would act on. - */ -public final class SpringCloudStreamConsumerBridge { - - private final Map handlers = new ConcurrentHashMap<>(); - private final Map destinations = new ConcurrentHashMap<>(); - - /** - * Registers a handler for a binding. - * - * @param destination the logical destination - * @param bindingName the Stream binding name - * @param handler the handler to invoke - */ - public void register(DestinationName destination, String bindingName, BridgedHandler handler) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(handler, "handler must not be null"); - if (bindingName == null || bindingName.isBlank()) { - throw new IllegalArgumentException("bindingName must not be blank"); - } - handlers.put(bindingName, handler); - destinations.put(bindingName, destination); - } - - /** - * Dispatches one message received on a binding. - * - * @param bindingName the Stream binding name - * @param payload the encoded payload - * @param headers the received headers - * @throws MessagingConfigurationException when nothing is registered for the binding - */ - public void dispatch(String bindingName, byte[] payload, Map headers) { - Objects.requireNonNull(payload, "payload must not be null"); - Objects.requireNonNull(headers, "headers must not be null"); - - BridgedHandler handler = handlers.get(bindingName); - DestinationName destination = destinations.get(bindingName); - if (handler == null || destination == null) { - throw new MessagingConfigurationException( - "NO_BRIDGED_HANDLER", "no handler is registered for Stream binding " + bindingName); - } - // Not caught. The binder's error channel is what retries and dead-letters this binding, and - // swallowing the failure here would acknowledge a message nothing handled. - handler.handle(destination, payload, headers); - } - - /** - * Returns how many bindings have a handler. - * - * @return the registered binding count - */ - public int registeredBindings() { - return handlers.size(); - } - - /** A platform handler reached through a Stream binding. */ - @FunctionalInterface - public interface BridgedHandler { - - /** - * Handles one bridged message. - * - * @param destination the logical destination - * @param payload the encoded payload - * @param headers the received headers - */ - void handle(DestinationName destination, byte[] payload, Map headers); - } -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamPublisherBridge.java b/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamPublisherBridge.java deleted file mode 100644 index 059144f..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/SpringCloudStreamPublisherBridge.java +++ /dev/null @@ -1,156 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -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.time.Duration; -import java.util.Map; -import java.util.Objects; -import java.util.Optional; -import java.util.concurrent.ConcurrentHashMap; - -/** - * Framework-neutral publish evidence bridge for a future Spring Cloud Stream adapter. - * - *

    Despite the historical module/class name, this type does not itself depend on Spring Cloud - * Stream and does not auto-configure {@code StreamBridge}. A product integrating Spring Cloud - * Stream supplies the {@link ChannelSend} seam explicitly. Keeping that limitation in the type - * contract prevents this module from being mistaken for a shipped Spring Cloud Stream integration. - * - *

    Sends through a Spring Cloud Stream output binding and reports what that actually proves. - * - *

    The result is deliberately {@code AMBIGUOUS} rather than {@code CONFIRMED}. A Stream {@code - * send} returns a boolean from the message channel — it says the binder accepted the message, not - * that a broker did. Reporting that as confirmed would put the platform's strongest word on the - * binder's weakest evidence, and a caller reading {@code CONFIRMED} would stop worrying about a - * message that may never have left the process. - * - *

    A caller that needs real publish evidence has to use the native adapter. That is the honest - * trade the bridge exists to make visible. - */ -public final class SpringCloudStreamPublisherBridge implements MessagingBindingBridge { - - private final Map outputBindings = new ConcurrentHashMap<>(); - private final Map inputBindings = new ConcurrentHashMap<>(); - private final ChannelSend send; - - /** - * Creates a publisher bridge. - * - * @param send the Stream channel send operation - */ - public SpringCloudStreamPublisherBridge(ChannelSend send) { - this.send = Objects.requireNonNull(send, "send must not be null"); - } - - @Override - public void bindPublisher(DestinationName destination, String bindingName) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(bindingName, "bindingName must not be null"); - outputBindings.put(destination, bindingName); - } - - @Override - public void bindConsumer(DestinationName destination, String bindingName) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(bindingName, "bindingName must not be null"); - inputBindings.put(destination, bindingName); - } - - /** - * Publishes through the bound output binding. - * - * @param destination the logical destination - * @param payload the encoded payload - * @param headers the headers to carry - * @return the outcome, never stronger than the binder can prove - */ - public PublishResult publish( - DestinationName destination, byte[] payload, Map headers) { - Objects.requireNonNull(destination, "destination must not be null"); - Objects.requireNonNull(payload, "payload must not be null"); - Objects.requireNonNull(headers, "headers must not be null"); - - String binding = outputBindings.get(destination); - if (binding == null) { - throw new MessagingConfigurationException( - "NO_OUTPUT_BINDING", "no Stream output binding is bound to " + destination.value()); - } - - boolean accepted = send.send(binding, payload, headers); - return accepted ? acceptedByBinder() : rejectedByBinder(); - } - - /** - * Returns the binding bound to a destination for consuming. - * - * @param destination the logical destination - * @return the binding name, when one is bound - */ - public Optional consumerBinding(DestinationName destination) { - return Optional.ofNullable(inputBindings.get(destination)); - } - - /** - * Returns the binding bound to a destination for publishing. - * - * @param destination the logical destination - * @return the binding name, when one is bound - */ - public Optional publisherBinding(DestinationName destination) { - return Optional.ofNullable(outputBindings.get(destination)); - } - - private static PublishResult acceptedByBinder() { - return new PublishResult( - // The binder accepted it; no broker has confirmed anything. AMBIGUOUS is the only honest - // answer, and it is what makes the bridge's weaker guarantee visible to the caller. - PublishCompletion.AMBIGUOUS, - new PublishEvidence( - true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE), - RoutingOutcome.UNKNOWN, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of( - dev.caskeleton.messaging.api.error.FailureDescriptor.of( - dev.caskeleton.messaging.api.error.FailureCategory.AMBIGUOUS, - "STREAM_BRIDGE_NO_BROKER_EVIDENCE", - "the Stream binder accepted the message; no broker confirmation is available"))); - } - - private static PublishResult rejectedByBinder() { - return new PublishResult( - PublishCompletion.REJECTED, - PublishEvidence.notTransmitted(), - RoutingOutcome.NOT_APPLICABLE, - Optional.empty(), - 1, - Duration.ZERO, - Optional.of( - dev.caskeleton.messaging.api.error.FailureDescriptor.of( - dev.caskeleton.messaging.api.error.FailureCategory.TRANSIENT_INFRASTRUCTURE, - "STREAM_BRIDGE_SEND_REFUSED", - "the Stream channel refused the message"))); - } - - /** The Stream channel send, isolated so the bridge is testable without a binder. */ - @FunctionalInterface - public interface ChannelSend { - - /** - * Sends one message to a binding. - * - * @param bindingName the Stream binding name - * @param payload the encoded payload - * @param headers the headers to carry - * @return whether the channel accepted the message - */ - boolean send(String bindingName, byte[] payload, Map headers); - } -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/StreamBridgePolicyGuard.java b/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/StreamBridgePolicyGuard.java deleted file mode 100644 index e676f35..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/main/java/dev/caskeleton/messaging/streambridge/StreamBridgePolicyGuard.java +++ /dev/null @@ -1,52 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -import dev.caskeleton.messaging.policy.DestinationProfile; -import java.util.Objects; - -/** - * Keeps the optional Spring Cloud Stream bridge inside platform policy. - * - *

    The bridge exists for interoperability with existing Spring Cloud Stream bindings, and its - * risk is specific: Stream owns its own binder configuration, so a binding can quietly acquire its - * own serializer, its own error handling, and its own acknowledgement mode — none of which the - * destination profile knows about. - * - *

    So the bridge is only permitted where the platform's guarantees are not the thing being relied - * on: a destination that declares an ordering scope, a retry policy, or a dead letter destination - * must go through the native adapter, where those are actually enforced. - */ -public final class StreamBridgePolicyGuard { - - /** - * Validates that a destination may be served through the bridge. - * - * @param profile the destination profile - * @param enabled whether the bridge is switched on - */ - public void validate(DestinationProfile profile, boolean enabled) { - Objects.requireNonNull(profile, "profile must not be null"); - - if (!enabled) { - throw new MessagingConfigurationException( - "STREAM_BRIDGE_DISABLED", - "the Spring Cloud Stream bridge is optional and disabled unless " - + "backend.messaging.bridge.spring-cloud-stream=true"); - } - if (profile.isOrdered()) { - throw new MessagingConfigurationException( - "STREAM_BRIDGE_ORDERING_UNSUPPORTED", - "an ordered destination must use the native adapter: " + profile.name().value()); - } - if (profile.retry().mode() != dev.caskeleton.messaging.policy.RetryMode.NONE) { - throw new MessagingConfigurationException( - "STREAM_BRIDGE_RETRY_UNSUPPORTED", - "the bridge does not apply the platform retry policy: " + profile.name().value()); - } - if (profile.deadLetter().enabled()) { - throw new MessagingConfigurationException( - "STREAM_BRIDGE_DLQ_UNSUPPORTED", - "the bridge does not apply confirmed dead lettering: " + profile.name().value()); - } - } -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BindingProfileValidatorTest.java b/messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BindingProfileValidatorTest.java deleted file mode 100644 index 1f5f403..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BindingProfileValidatorTest.java +++ /dev/null @@ -1,164 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -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.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.api.error.MessagingConfigurationException; -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.util.Map; -import java.util.Set; -import org.junit.jupiter.api.Test; - -class BindingProfileValidatorTest { - - private final BindingProfileValidator validator = new BindingProfileValidator(); - - private static DestinationProfile profile( - OrderingScope ordering, RetryPolicy retry, DeadLetterPolicy deadLetter, boolean production) { - return new DestinationProfile( - new DestinationName("orders.v1"), - "kafka-primary", - DestinationKind.EVENT_STREAM, - PhysicalDestination.kafkaTopic("orders.v1"), - new SchemaPolicy( - ContentType.JSON, - SchemaCompatibility.BACKWARD, - Set.of(new MessageType("order.created"))), - DeliveryGuarantee.AT_LEAST_ONCE, - ordering, - ExternalSideEffectGuarantee.IDEMPOTENCY_REQUIRED, - ProducerPolicy.defaults(), - ConsumerPolicy.defaults("orders"), - retry, - deadLetter, - PayloadPolicy.defaults(), - CapabilityTier.M1, - production, - false, - false); - } - - private static DestinationProfile bridgeable() { - return profile(OrderingScope.NONE, RetryPolicy.none(), DeadLetterPolicy.disabled(), false); - } - - @Test - void aBridgeableDestinationIsAccepted() { - BindingCapabilityReport report = validator.validate(bridgeable(), "orders-out", Map.of(), true); - - assertThat(report.bindingName()).isEqualTo("orders-out"); - } - - @Test - void aDisabledBridgeRefusesEverything() { - assertThatThrownBy(() -> validator.validate(bridgeable(), "orders-out", Map.of(), false)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("disabled"); - } - - @Test - void anOrderedDestinationMustUseTheNativeAdapter() { - assertThatThrownBy( - () -> - validator.validate( - profile( - OrderingScope.KEY, RetryPolicy.none(), DeadLetterPolicy.disabled(), false), - "orders-out", - Map.of(), - true)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("ordered"); - } - - @Test - void aDestinationWithADeadLetterMustUseTheNativeAdapter() { - assertThatThrownBy( - () -> - validator.validate( - profile( - OrderingScope.NONE, - RetryPolicy.none(), - DeadLetterPolicy.to(new DestinationName("orders.v1.dlq")), - false), - "orders-out", - Map.of(), - true)) - .as("the binder settles the source without confirming the dead-letter publish") - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - void aProductionDestinationIsRefused() { - assertThatThrownBy( - () -> - validator.validate( - profile( - OrderingScope.NONE, RetryPolicy.none(), DeadLetterPolicy.disabled(), true), - "orders-out", - Map.of(), - true)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("production"); - } - - @Test - void aBinderPropertyThatOverridesPlatformPolicyIsRejectedRatherThanMerged() { - assertThatThrownBy( - () -> validator.validate(bridgeable(), "orders-out", Map.of("maxAttempts", "10"), true)) - .as("merging the two produces a configuration nobody can read") - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("maxAttempts"); - } - - @Test - void aHarmlessBinderPropertyIsAllowedThrough() { - assertThatCode( - () -> validator.validate(bridgeable(), "orders-out", Map.of("concurrency", "4"), true)) - .doesNotThrowAnyException(); - } - - @Test - void anInvalidBindingNameIsRejected() { - assertThatThrownBy(() -> validator.validate(bridgeable(), "9-bad name!", Map.of(), true)) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("binding name"); - } - - @Test - void aBridgedBindingReportsEveryGuaranteeItDoesNotCarry() { - BindingCapabilityReport report = validator.validate(bridgeable(), "orders-out", Map.of(), true); - - assertThat(report.isFullyGuaranteed()).isFalse(); - assertThat(report.gaps()).hasSize(4); - assertThat(String.join(" ", report.gaps())) - .contains("publish evidence") - .contains("retry") - .contains("dead letter") - .contains("ordering"); - } - - @Test - void aNativeBindingReportsNoGaps() { - assertThat( - BindingProfileValidator.nativeAdapter(new DestinationName("orders.v1"), "orders-out") - .isFullyGuaranteed()) - .isTrue(); - } -} diff --git a/messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BridgePublishEvidenceTest.java b/messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BridgePublishEvidenceTest.java deleted file mode 100644 index 411f04f..0000000 --- a/messaging/messaging-spring-cloud-stream-bridge/src/test/java/dev/caskeleton/messaging/streambridge/BridgePublishEvidenceTest.java +++ /dev/null @@ -1,131 +0,0 @@ -package dev.caskeleton.messaging.streambridge; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; - -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.error.MessagingConfigurationException; -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.TransmissionEvidence; -import java.nio.charset.StandardCharsets; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import org.junit.jupiter.api.Test; - -class BridgePublishEvidenceTest { - - private static final DestinationName ORDERS = new DestinationName("orders.v1"); - private static final byte[] PAYLOAD = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8); - - private static SpringCloudStreamPublisherBridge bridge(boolean channelAccepts) { - SpringCloudStreamPublisherBridge bridge = - new SpringCloudStreamPublisherBridge((binding, payload, headers) -> channelAccepts); - bridge.bindPublisher(ORDERS, "orders-out"); - return bridge; - } - - @Test - void anAcceptedSendIsAmbiguousBecauseNoBrokerConfirmedIt() { - PublishResult result = bridge(true).publish(ORDERS, PAYLOAD, Map.of()); - - assertThat(result.completion()) - .as("a channel send says the binder took it, not that a broker did") - .isEqualTo(PublishCompletion.AMBIGUOUS); - assertThat(result.evidence().brokerAccepted()).isFalse(); - assertThat(result.evidence().confirmationLevel()).isEqualTo(ConfirmationLevel.NONE); - } - - @Test - void anAcceptedSendReportsThatTransmissionIsUnknown() { - assertThat(bridge(true).publish(ORDERS, PAYLOAD, Map.of()).evidence().transmission()) - .isEqualTo(TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED); - } - - @Test - void theFailureDescriptorNamesTheMissingEvidence() { - assertThat(bridge(true).publish(ORDERS, PAYLOAD, Map.of()).failure()) - .hasValueSatisfying( - failure -> assertThat(failure.code()).isEqualTo("STREAM_BRIDGE_NO_BROKER_EVIDENCE")); - } - - @Test - void aRefusedChannelSendIsRejectedNotAmbiguous() { - PublishResult result = bridge(false).publish(ORDERS, PAYLOAD, Map.of()); - - assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); - assertThat(result.evidence().transmission()).isEqualTo(TransmissionEvidence.NOT_TRANSMITTED); - } - - @Test - void publishingToAnUnboundDestinationFailsLoudly() { - SpringCloudStreamPublisherBridge bridge = - new SpringCloudStreamPublisherBridge((binding, payload, headers) -> true); - - assertThatThrownBy(() -> bridge.publish(ORDERS, PAYLOAD, Map.of())) - .isInstanceOf(MessagingConfigurationException.class) - .hasMessageContaining("orders.v1"); - } - - @Test - void thePayloadReachesTheBoundBinding() { - List bindings = new ArrayList<>(); - SpringCloudStreamPublisherBridge bridge = - new SpringCloudStreamPublisherBridge( - (binding, payload, headers) -> { - bindings.add(binding); - return true; - }); - bridge.bindPublisher(ORDERS, "orders-out"); - - bridge.publish(ORDERS, PAYLOAD, Map.of()); - - assertThat(bindings).containsExactly("orders-out"); - } - - @Test - void bindingsAreQueryableInBothDirections() { - SpringCloudStreamPublisherBridge bridge = bridge(true); - bridge.bindConsumer(ORDERS, "orders-in"); - - assertThat(bridge.publisherBinding(ORDERS)).hasValue("orders-out"); - assertThat(bridge.consumerBinding(ORDERS)).hasValue("orders-in"); - } - - @Test - void aHandlerFailureIsRethrownSoTheBindersErrorChannelSeesIt() { - SpringCloudStreamConsumerBridge consumer = new SpringCloudStreamConsumerBridge(); - consumer.register( - ORDERS, - "orders-in", - (destination, payload, headers) -> { - throw new IllegalStateException("handler failed"); - }); - - assertThatThrownBy(() -> consumer.dispatch("orders-in", PAYLOAD, Map.of())) - .as("swallowing it would acknowledge a message nothing handled") - .isInstanceOf(IllegalStateException.class); - } - - @Test - void dispatchingToAnUnregisteredBindingFailsLoudly() { - assertThatThrownBy( - () -> new SpringCloudStreamConsumerBridge().dispatch("orders-in", PAYLOAD, Map.of())) - .isInstanceOf(MessagingConfigurationException.class); - } - - @Test - void aRegisteredHandlerReceivesTheDestinationItWasBoundTo() { - List seen = new ArrayList<>(); - SpringCloudStreamConsumerBridge consumer = new SpringCloudStreamConsumerBridge(); - consumer.register( - ORDERS, "orders-in", (destination, payload, headers) -> seen.add(destination)); - - consumer.dispatch("orders-in", PAYLOAD, Map.of()); - - assertThat(seen).containsExactly(ORDERS); - assertThat(consumer.registeredBindings()).isEqualTo(1); - } -} diff --git a/messaging/messaging-testkit/build.gradle b/messaging/messaging-testkit/build.gradle index 559464f..a7492ce 100644 --- a/messaging/messaging-testkit/build.gradle +++ b/messaging/messaging-testkit/build.gradle @@ -1,5 +1,11 @@ plugins { - id 'ca.jmh-benchmarks' + id 'ca.platform-module' + id 'me.champeau.jmh' +} + +jmh { + jmhVersion = libs.versions.jmh.get() + includeTests = true } dependencies { diff --git a/messaging/messaging-testkit/gradle.lockfile b/messaging/messaging-testkit/gradle.lockfile index 98b1f9d..4334c11 100644 --- a/messaging/messaging-testkit/gradle.lockfile +++ b/messaging/messaging-testkit/gradle.lockfile @@ -35,12 +35,12 @@ io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,jmhAnnotation javax.inject:javax.inject:1=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor jaxen:jaxen:2.0.6=spotbugs net.bytebuddy:byte-buddy:1.17.8=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath -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-lang3:3.20.0=checkstyle,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 @@ -71,13 +71,16 @@ org.junit.platform:junit-platform-launcher:6.0.3=jmhRuntimeClasspath,testRuntime org.junit:junit-bom:6.0.3=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.junit:junit-bom:6.1.0=spotbugs 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.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=compileClasspath,jmhCompileClasspath,jmhRuntimeClasspath,runtimeClasspath,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.0=jmh,jmhCompileClasspath,jmhRuntimeClasspath org.ow2.asm:asm:9.10.1=spotbugs org.pcollections:pcollections:4.0.1=annotationProcessor,jmhAnnotationProcessor,testAnnotationProcessor org.reflections:reflections:0.10.2=checkstyle diff --git a/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java b/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java index 13d7486..42d4271 100644 --- a/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java +++ b/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java @@ -51,9 +51,9 @@ public final class CompatibilityMatrix { * Reports whether a lane has run this adapter against a real broker. * *

    Read from the evidence rather than declared. As a field it was a boolean an author set - * next to the tier, and RabbitMQ carried {@code true} while no fault scenario had ever been - * executed against it — the same shape as the coverage matrix that used to assert its own - * constants. + * next to the tier, and an Experimental adapter carried {@code true} while no fault scenario + * had ever been executed against it — the same shape as the coverage matrix that used to assert + * its own constants. * * @return true when {@link CertifiedEvidence} has live-broker evidence for this adapter */ @@ -78,36 +78,11 @@ public final class CompatibilityMatrix { private static final Map ENTRIES = Map.of( "messaging-kafka", - // 4.1 only. The declared 4.2/4.3 were never run: the fixtures pin apache/kafka:4.1.0 - // and - // the locked client is 4.1.1, so the matrix and the support document agreed with each - // other and with nothing that had executed. A version returns here when a lane runs - // against its image. - new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true), - "messaging-rabbit", - // Experimental until a lane runs a fault scenario against a RabbitMQ container. The - // adapter passes the shared contract and its broker IT exercises the routable and - // unroutable happy paths, but Stable in this repository means fault evidence, and - // there is none: connection-refused, cut-after-write, confirm-timeout, - // settlement-lost and high-latency have never been executed here. - new Entry("messaging-rabbit", List.of("4.3"), Tier.EXPERIMENTAL, true, false), - "messaging-kafka-share-experimental", - new Entry( - "messaging-kafka-share-experimental", - List.of("4.2", "4.3"), - Tier.EXPERIMENTAL, - false, - false), - "messaging-pulsar-experimental", - new Entry( - "messaging-pulsar-experimental", - List.of("4.0", "4.2"), - Tier.EXPERIMENTAL, - false, - false), - "messaging-nats-experimental", - new Entry( - "messaging-nats-experimental", List.of("2.14"), Tier.EXPERIMENTAL, false, false)); + // 4.1 only. The declared 4.2/4.3 were never run: the fixtures pin apache/kafka:4.1.0 and + // the locked client is 4.1.1, so the matrix and the support document agreed with each + // other and with nothing that had executed. A version returns here when a lane runs + // against its image. + new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true)); /** * Returns every certified adapter. diff --git a/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java b/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java index 4df6fa8..a17f10e 100644 --- a/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java +++ b/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/MessagingAdapterHarness.java @@ -9,8 +9,8 @@ import java.util.concurrent.CompletionStage; * The seam each broker adapter implements to run the common contract. * *

    The harness exposes outcomes, not internals: what the platform decided, what reached the dead - * letter destination, and what is still unsettled. Kafka and RabbitMQ answer those three questions - * with completely different machinery, and the contract only passes if the answers match. + * letter destination, and what is still unsettled. Each broker answers those three questions with + * its own machinery, and the contract only passes if the answers match. */ public interface MessagingAdapterHarness extends AutoCloseable { diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java index 0ed64f1..a8eacb4 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CertifiedEvidenceTest.java @@ -53,8 +53,8 @@ class CertifiedEvidenceTest { assertThat(CertifiedEvidence.knownGaps("messaging-kafka")) .as("a Kafka producer buffers before it learns a connection exists, so this stays unproven") .contains(NetworkFaultScenario.CONNECTION_REFUSED); - assertThat(CertifiedEvidence.knownGaps("messaging-rabbit")) - .as("no lane runs a fault scenario against RabbitMQ, so every scenario is a gap") + assertThat(CertifiedEvidence.knownGaps("messaging-artemis")) + .as("an adapter no lane has run has every scenario as a gap") .containsExactlyElementsOf(NetworkFaultScenario.all()); } diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java index f126796..7cccaf2 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CompatibilityMatrixTest.java @@ -32,7 +32,6 @@ class CompatibilityMatrixTest { void noExperimentalAdapterIsEnabledByDefault() { assertThat(CompatibilityMatrix.entries().values()) .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL) - .isNotEmpty() .allSatisfy(entry -> assertThat(entry.enabledByDefault()).isFalse()); } @@ -41,7 +40,6 @@ class CompatibilityMatrixTest { assertThat(CompatibilityMatrix.entries().values()) .filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE) .extracting(CompatibilityMatrix.Entry::adapter) - .as("RabbitMQ passes the shared contract, but no fault scenario has been run against it") .containsExactly("messaging-kafka"); } diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java index adb286a..ff0b29b 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/CrossBrokerContractSuite.java @@ -48,19 +48,16 @@ class CrossBrokerContractSuite { assertThat(matrix.gapsFor("messaging-kafka")) .as("what the Kafka lanes have not exercised against a live broker") .isEqualTo(CertifiedEvidence.knownGaps("messaging-kafka")); - assertThat(matrix.gapsFor("messaging-rabbit")) - .as("what the Rabbit lanes have not exercised against a live broker") - .isEqualTo(CertifiedEvidence.knownGaps("messaging-rabbit")); } @Test void evidenceThatDisagreesWithItsScenarioIsNotCoverage() { BrokerCertificationEvidence contradicting = new BrokerCertificationEvidence( - "messaging-rabbit", - "rabbitmq:4.3-management", + "messaging-kafka", + "apache/kafka:4.1.0", NetworkFaultScenario.CONNECTION_CUT_AFTER_WRITE, - "RabbitBrokerIT#anUnroutablePublishIsRejectedEvenThoughTheExchangeConfirmedIt", + "SomeIT#someScenario", "REJECTED", "repository-local", java.time.Instant.parse("2026-08-15T00:00:00Z")); @@ -105,14 +102,6 @@ class CrossBrokerContractSuite { .isNotEqualTo(Coverage.LIVE_BROKER))); } - @Test - void anExperimentalAdapterIsAllowedGapsButTheyAreRecorded() { - assertThat(matrix.isComplete("messaging-pulsar-experimental")) - .as("the Experimental tier is a statement of fact, not a disclaimer") - .isFalse(); - assertThat(matrix.gapsFor("messaging-pulsar-experimental")).isNotEmpty(); - } - @Test void aFaultThatWasNeverRecordedReadsAsUncoveredRatherThanPassing() { assertThat(matrix.coverageOf("messaging-artemis", NetworkFaultScenario.CONFIRM_TIMEOUT)) diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java index 0b7471a..e97c8ac 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/MessagingDocumentationContractTest.java @@ -135,10 +135,6 @@ class MessagingDocumentationContractTest { private static String brokerLabel(String adapter) { return switch (adapter) { case "messaging-kafka" -> "Kafka"; - case "messaging-rabbit" -> "RabbitMQ"; - case "messaging-pulsar-experimental" -> "Pulsar"; - case "messaging-nats-experimental" -> "NATS"; - case "messaging-kafka-share-experimental" -> "Kafka Share"; default -> adapter; }; }